Parallel execution
Jupiter runs tests one at a time by default. A suite of a thousand small tests spends most of its life waiting, and a machine with several cores can run them together. The switch is a configuration key, not an annotation on every class, and it changes what a test may assume about the order and the shared state.
Serial by default
Without configuration, one test runs at a time on one thread. That is the mode the whole course has used, and it is why a static field or a shared file has been safe so far. The order between methods is still unspecified, but two methods never run at the same moment.
Turning it on
Parallel execution is enabled with a configuration key. A project puts it in src/test/resources/junit-platform.properties, which the launcher reads from the class path:
junit.jupiter.execution.parallel.enabled = true
junit.jupiter.execution.parallel.mode.default = concurrent
junit.jupiter.execution.parallel.mode.classes.default = concurrent
The same keys can be passed on the command line with --config, which is how they were tried for this page:
junit execute --class-path out --scan-classpath --config junit.jupiter.execution.parallel.enabled=true --config junit.jupiter.execution.parallel.mode.default=concurrent --disable-ansi-colors
The two modes are same_thread and concurrent. The default for methods and the default for classes are separate, so a project can run classes in parallel and the methods of one class in order, which is the safe first step.
The test class
The class is three independent arithmetic checks with no shared field. Each test builds its own values, so the three can run at once without seeing each other.
import static org.junit.jupiter.api.Assertions.assertEquals;
import org.junit.jupiter.api.Test;
public class ParallelTest {
@Test
void adds() {
assertEquals(4, 2 + 2);
}
@Test
void multiplies() {
assertEquals(6, 2 * 3);
}
@Test
void subtracts() {
assertEquals(2, 5 - 3);
}
}
The report
The report below is the serial run of the same class, because a parallel run does not promise the order of the method lines and this page is checked line for line. The counts are the same in both modes; only the order and the time differ.
javac -Xlint:all -cp /opt/java-tools/junit-platform-console-standalone.jar -d out ParallelTest.java
junit execute --class-path out --scan-classpath --disable-ansi-colors
Thanks for using JUnit! Support its development at https://junit.org/sponsoring
╷
├─ JUnit Platform Suite ✔
├─ JUnit Jupiter ✔
│ └─ ParallelTest ✔
│ ├─ adds() ✔
│ ├─ subtracts() ✔
│ └─ multiplies() ✔
└─ JUnit Vintage ✔
Test run finished after 466 ms
[ 4 containers found ]
[ 0 containers skipped ]
[ 4 containers started ]
[ 0 containers aborted ]
[ 4 containers successful ]
[ 0 containers failed ]
[ 3 tests found ]
[ 0 tests skipped ]
[ 3 tests started ]
[ 0 tests aborted ]
[ 3 tests successful ]
[ 0 tests failed ]
The order is not promised
Five parallel runs of the same three tests printed the method lines in four different orders. The report sorts the completed results by the launcher's rule, and with several threads finishing at once that order changes. A test that expects a particular sequence of lines, or a page that quotes the tree, has to run in the serial mode.
The counts, the names and the verdicts stay the same; only the order and the time move. A build script that parses the counts is therefore safe, and one that greps a line number is not.
Shared state and parallelism
A static counter, a shared temporary file or a global singleton becomes a race when two tests run at once. The per-test instance removes instance fields from the problem, but a static field is still shared by every thread. A class that must keep such a field can opt out with @Execution(ExecutionMode.SAME_THREAD), which keeps its tests on one thread while the rest of the suite runs in parallel.
The other limit is the machine: the launcher uses a pool sized from the available processors, and the configuration can set junit.jupiter.execution.parallel.config.strategy and its size. A test that starts a server on a fixed port also needs a resource lock, which Jupiter provides with @ResourceLock.
Exercises
- Put the three keys in a properties file, copy it into the output folder, and run --scan-classpath five times. How many orders do you see?
- Set the class mode to concurrent and the method mode to same_thread. Do the methods of one class still run in order?
- Add a static counter that each test increments and asserts. Why does the test become flaky under parallel execution?
- Add @Execution(ExecutionMode.SAME_THREAD) to the class and explain what it restores.
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
Is Jupiter parallel by default?
Answer
No; a configuration key enables it
The default is serial, and junit.jupiter.execution.parallel.enabled turns it on.
-
Where does a project put the parallel configuration?
Answer
In junit-platform.properties on the class path
The launcher reads junit-platform.properties from the class path, usually test resources.
-
What does parallel execution change in the report?
Answer
The order of the method lines and the time
Counts and verdicts stay the same; completion order and elapsed time move.
-
What does this program print?
public class Q1 { public static void main(String[] args) { System.out.println(2 * 3); } }Answer
6
The multiplication gives 6, and println prints it.
-
What does this program print?
public class Q2 { public static void main(String[] args) { System.out.println(5 - 3); } }Answer
2
The subtraction gives 2, and println prints it.
-
What does this program print?
public class Q3 { public static void main(String[] args) { System.out.println("concurrent".length()); } }Answer
10
The word concurrent has ten characters.
-
What does this program print?
public class Q4 { public static void main(String[] args) { System.out.println("true".equals("true")); } }Answer
true
The two strings have the same characters, so equals is true.
-
Which state becomes a race under parallel execution?
Answer
A static field written by more than one test
A static field is shared by all threads; locals and per-instance fields are not.
-
What does
@Execution(ExecutionMode.SAME_THREAD)do?Answer
Keeps the tests of the class on one thread
The annotation opts a class out of concurrent execution while the rest of the suite keeps it.
-
What does this program print?
public class Q5 { public static void main(String[] args) { System.out.println(6 / 2); } }Answer
3
Six divided by two is three.
The code on this page was built with OpenJDK 21.0.13 (javac) and run with JUnit Platform Console Launcher 1.14.3 on Alpine Linux in a Docker container.
Article author: Arthur Isaev