A custom Junit4 runner to test MPI+Java programs
This project contains a Junit4 Runner implementation which allows you to run Junit tests for Java programs that use MPI calls. Simply add this project as a dependency and annotate your test class with the @RunWith and @MpiConfig annotations:
@RunWith(MpiRunner.class) // Use the MpiRunner to run the test
@MpiConfig(ranks=4) // Specify how many ranks you want your test to run with
public class MyTestClass {
@Test
public void testMultipleHosts() {
assertTrue(MPI.COMM_WORLD.Size() > 1);
}
}
In normal Junit test execution, the test methods are only run once. With the
MpiRunner however, each mpi process execute the test methods. You will therefore
obtain as many test results as there are ranks for each of your test methods.
| Version | Changes |
|---|---|
| master-latest | Development head (Javadoc) (Maven Report) |
| v1.2.2 | Released June 22nd 2021 Added support for Parameterized MPI tests (Javadoc) (Maven Report) (Download mpi-junit-v1.2.2.jar) |
| v1.2.1 | Released March 26th 2021 Added support for MPJ-native environment Added the option to parse only the results produced by a single host of the computation (Javadoc) (Maven Report) (Download mpi-junit-v1.2.1.jar) |
| v1.2 | Released July 6th 2020 Added support for MPJ-multicore environment as well as a number of useful customization options (Javadoc) (Maven Report) (Download mpi-junit-1.2.jar) |
| v1.0 | Original release limited to mpiJava v1.2.7 native Mpi bindings. Use is not recommended due to issues in the project configuration. |
To run the tests with MPI, the MpiRunner spawns a mpirun process with the
user-specified number of ranks. Each mpi process will write the results of its
test methods to a dedicated file. When the mpirun process terminates, the
MpiRunner will parse these files, aggregate the results and return them to
the “normal” Junit runtime.
As the use of custom Runners is an integral feature of the Junit4 framework, using the MpiRunner should integrate seamlessly with the system you use to run your tests, whether it be the Eclipse Junit launchers / Maven …
(click here) for more detailed information on how the MpiRunner works. (Click here) to look at configuration examples.
All the dependencies for this project are included with the “provided” maven scope, meaning that when you use this project, it will use your Junit and MPI for Java dependencies.
As of now, the MpiRunner supports three MPI implementations:
Be aware that some runtime environment cannot use the MPJ-Express “multicore” configuration. This is the case when mixing the APGAS for Java runtime with MPI for instance. However, if your programs can run with the MPJ-Express “multicore” implementation, you should be able to use this project to run tests.