JUnit 5 @TestInstance(Lifecycle.PER_CLASS) Parallel Execution: Thread Safety Uncertainty

Answer

JUnit 5 does not automatically serialize test method execution for @TestInstance(Lifecycle.PER_CLASS) when parallel execution is enabled. The single test instance is shared across threads, so mutable state becomes a race condition unless you explicitly enforce serial execution or adopt a thread‑safe design.

Confirmed Facts

• Parallel execution is configured at the platform level via junit.jupiter.execution.parallel.enabled=true.
• By default, test methods run concurrently unless constrained by @Execution(ExecutionMode.SAME_THREAD) on the class or method.
• Lifecycle callbacks @BeforeAll and @AfterAll run once per class on a single thread, but @BeforeEach and @AfterEach may run concurrently with other test methods.
• Nested test classes inherit the parent’s lifecycle unless they declare their own @TestInstance annotation.
• Parameterized tests create separate invocations per parameter set; each invocation shares the PER_CLASS instance and runs concurrently by default.

Practical Steps to Verify & Mitigate

1. Create a minimal test class:

   @TestInstance(TestInstance.Lifecycle.PER_CLASS)
   class CounterTest {
       int counter = 0;
   
       @Test
       void testA() { counter++; }
   
       @Test
       void testB() { counter++; }
   }
   

2. Run with parallel execution enabled (e.g., add junit.jupiter.execution.parallel.enabled=true to junit-platform.properties).
3. After the test run, print counter in a @AfterAll method. A non‑deterministic value >2 indicates concurrent access.
4. To enforce serialization, add @Execution(ExecutionMode.SAME_THREAD) to the class and re‑run. The counter should reliably equal the number of test methods.
5. Alternatively, remove mutable fields or make them final after @BeforeAll initialization, or use ThreadLocal for per‑thread data.

Thread‑Safe Patterns

• Immutable State: Initialize all fields in @BeforeAll and never modify them thereafter.
• ThreadLocal: Store per‑thread data in a ThreadLocal<T> variable.
• Synchronized Blocks: Guard mutable shared fields with synchronized or java.util.concurrent.locks.Lock.
• Concurrent Collections: Use AtomicInteger, ConcurrentHashMap, etc., for shared mutable state.
• Same‑Thread Execution: Use @Execution(ExecutionMode.SAME_THREAD) on the class or specific methods when isolation is critical.

Nested & Parameterized Tests

• Nested classes that do not declare their own @TestInstance inherit the PER_CLASS instance, so the same concurrency rules apply.
• Parameterized tests share the PER_CLASS instance across all invocations; each invocation may run concurrently unless constrained.
• When using extensions (e.g., SpringExtension), check whether the extension imposes its own synchronization or lifecycle constraints.

Missing Diagnostic Detail

Which junit-jupiter version are you using? The parallel execution semantics changed between 5.3 and 5.9, so the exact behavior can vary with the version.