Which configuration controls the number of threads JUnit 5 uses for parallel test execution?

The short answer

JUnit 5's thread count for parallel execution is controlled by the junit.jupiter.execution.parallel.config.strategy property, together with strategy-specific settings in junit-platform.properties. There is no per-class or per-method annotation that changes the pool size — parallelism is a single engine-wide setting.

How JUnit decides the pool size

Once you enable parallelism with junit.jupiter.execution.parallel.enabled=true, the Jupiter engine builds its worker pool from the configured strategy:

• dynamic (default): parallelism = availableProcessors × junit.jupiter.execution.parallel.config.dynamic.factor (factor defaults to 1, so you get roughly one thread per core).
• fixed: exactly junit.jupiter.execution.parallel.config.fixed.parallelism threads.
• custom: a class you supply implementing the ParallelExecutionConfigurationStrategy interface, named via junit.jupiter.execution.parallel.config.custom.class.

A minimal fixed-size configuration looks like this:

# src/test/resources/junit-platform.properties
junit.jupiter.execution.parallel.enabled=true
junit.jupiter.execution.parallel.mode.default=concurrent
junit.jupiter.execution.parallel.config.strategy=fixed
junit.jupiter.execution.parallel.config.fixed.parallelism=4

Why there is no per-suite override

Annotations like @Execution(CONCURRENT) and @ResourceLock control which tests may run concurrently and how they contend for shared resources — they never resize the pool. If you need different parallelism for different suites, the practical options are: run those suites as separate Maven/Gradle test tasks each with its own junit-platform.properties, or use the custom strategy to compute parallelism from an environment variable or system property. This is a known limitation, not a misconfiguration on your side.

The ForkJoinPool and your latency problem

JUnit 5 submits test work to a ForkJoinPool. The likely explanation for latency that only appears under concurrent execution is pool saturation plus contention: when more tests are eligible to run than there are worker threads, the excess queue up, and wall-clock latency per test grows even though total throughput is fine. If the engine uses the common pool (behavior can vary by version and configuration), other common-pool users in the same JVM — parallel streams in your code under test, or the build tool itself — compete for the same workers. Using @ResourceLock on shared resources (ports, files, static state) can also serialize tests in ways that look like a thread-count problem but are actually lock contention.

Verifying the actual thread count

Don't trust the config file alone — verify what the engine really created:

@Test
void printWorker() {
    System.out.println(Thread.currentThread().getName());
}

Run several concurrent tests and count the distinct junit-jupiter-timeout-thread/worker names (prefix varies by version; look for the ForkJoinPool-style names). Cross-check with jconsole or jcmd <pid> Thread.print while the suite runs, and watch core utilization with htop. If the observed worker count doesn't match your fixed value, confirm the properties file is actually on the test classpath — a file placed in the wrong directory silently falls back to the dynamic default, which is a common cause of "my setting is ignored" reports.

Version note: parallel execution was experimental when introduced in JUnit 5.3 and stabilized later; property names above apply to current 5.x releases. Confirm against the user guide for your exact version.