Parallel Execution Config

## What parallel execution means here JUnit 5 is a platform plus an engine (Jupiter). The platform builds a *test tree*: an engine node at the root, then test classes, then nested classes and test methods as leaves. By default the platform walks that tree on a single thread, so tests run one after another in a deterministic order. Parallel execution means the platform is allowed to hand sibling nodes to different worker threads at the same time. It is opt-in for a good reason: a suite written under the assumption of one thread will happily share static fields, system properties, fixed ports, files in a shared directory and rows in one database schema. Turning parallelism on changes the correctness requirements of your tests, so JUnit makes you ask for it explicitly. ## The master switch ``` junit.jupiter.execution.parallel.enabled = true ``` This tells the Jupiter engine to use the parallel (multi-threaded) hierarchical executor instead of the single-threaded one. On its own it changes **nothing observable**: every node still carries the default execution mode `same_thread`, so the executor keeps running everything on one thread. Almost every first encounter with this feature ends with "I enabled it and the build takes exactly as long" — because step two was missed. ## Choosing what may run concurrently Two more configuration parameters set the defaults for the tree: ``` junit.jupiter.execution.parallel.mode.default = concurrent | same_thread junit.jupiter.execution.parallel.mode.classes.default = concurrent | same_thread ``` `mode.default` is the default mode applied to nodes generally — test methods and nested classes. `mode.classes.default` is the default for top-level test classes, i.e. whether two different test classes may be in flight at once. Out of the box both behave as `same_thread`. Because the classes-level setting is derived from the method-level one when you don't state it, the safest habit is to set both explicitly so you get the shape of parallelism you intended rather than a surprising one. The four useful combinations: | classes.default | mode.default | Effect | |---|---|---| | same_thread | same_thread | fully sequential (the default) | | concurrent | same_thread | classes run in parallel; methods inside one class stay sequential and on one thread | | same_thread | concurrent | one class at a time, but its methods run in parallel | | concurrent | concurrent | maximum parallelism | The `concurrent / same_thread` row is the pragmatic starting point for a legacy suite: the unit of concurrency is a whole class, so per-class fixtures (`@BeforeAll`, a shared container, an instance field under the default per-method lifecycle) stay confined to one thread. For per-target control, `@Execution(ExecutionMode.CONCURRENT)` or `@Execution(ExecutionMode.SAME_THREAD)` on a class or method overrides the configured default for that node and everything below it. ## Where the settings live Three sources, in decreasing precedence: 1. Configuration parameters supplied programmatically in a `LauncherDiscoveryRequest` (what tools and the ConsoleLauncher use under the hood). 2. JVM system properties with the same key names. 3. A `junit-platform.properties` file at the **root of the class path** — conventionally `src/test/resources/junit-platform.properties`. The properties file is what you check into version control so every developer and every CI run gets the same behaviour; a system property is the convenient way to flip it for one run. ## Notable exceptions to the default mode A couple of Jupiter features are incompatible with running a class's methods concurrently, so JUnit keeps them on one thread even when the default is `concurrent`: test classes annotated with `@TestInstance(Lifecycle.PER_CLASS)` (all methods share one instance, so instance state is shared state) and classes that declare a `MethodOrderer` (ordering is meaningless if methods overlap). If you genuinely want those concurrent, you must annotate them explicitly with `@Execution(CONCURRENT)` and accept responsibility for the shared state. ## Verifying it is on The cheapest proof is to log the current thread name from a couple of tests. Under parallel execution you will see several distinct `ForkJoinPool-…-worker-N` names instead of one `main`-ish thread. Wall-clock time on a large suite is the other signal, but on a small suite thread-pool warm-up can hide the gain, which is why the thread name is the better check. ## What to expect afterwards Once concurrency is real, test output interleaves, assertion failures may point at tests that are victims rather than culprits, and anything that mutates JVM-global state becomes a race. Enabling parallelism is therefore a two-part job: the configuration above, plus a pass over the suite to decide which tests are safe to overlap.