Boosting Test Speed with Gradle and JUnit 5 Parallel Execution

Testing is a vital part of any build pipeline, but it can eat up precious time. By harnessing multi-core processors, we can run tests in parallel to dramatically cut down execution time. This guide walks you through setting up parallel testing with Gradle and JUnit 5, from configuration to practical examples.

How do you enable parallel test execution in Gradle?

To activate parallel testing in Gradle, you need to set the maxParallelForks property in your build.gradle file. This property controls how many JVM forks run tests simultaneously. A typical setup looks like this:

Boosting Test Speed with Gradle and JUnit 5 Parallel Execution — Source: www.baeldung.com

test {
    maxParallelForks = (int) (Runtime.runtime.availableProcessors() / 2 + 1)
}

Here we use Java's Runtime.availableProcessors() to get the number of CPU cores, then set the fork count to half plus one—balancing resource usage. This configuration tells Gradle to launch multiple test processes at once, each running a subset of tests. Remember to also include the JUnit 5 dependency and the JUnit platform launcher. Optionally, you can filter tests by tags using useJUnitPlatform { includeTags ... }.

What does the maxParallelForks formula mean?

The expression maxParallelForks = (int) (Runtime.runtime.availableProcessors() / 2 + 1) is a heuristic designed to avoid overloading your system. By dividing the number of available processors by two and adding one, you reserve some cores for the operating system and other processes. For example, on a quad-core machine, this yields 3 forks. Each fork runs tests in its own JVM, allowing true parallel execution on multi-core hardware. This setting can be tuned—if tests are I/O heavy, fewer forks may be better; if CPU bound, start with this formula and adjust upward cautiously.

How does the @Tag annotation filter tests in parallel runs?

JUnit 5's @Tag annotation lets you label tests for selective execution. In the Gradle configuration, you can specify which tags to include:

test {
    useJUnitPlatform {
        includeTags project.findProperty('testForGradleTag') ?: 'serial'
    }
}

By default, the property testForGradleTag is set to serial in gradle.properties. This means only tests marked @Tag("serial") will run unless you override it. This is not related to forking—it’s a convenience to control which tests are included in a parallel run. For instance, you could label integration tests as parallel and unit tests as serial to run them separately.

How can you measure execution time when running parallel tests?

To track how long tests take, you can set up timing hooks in your test class. Use @BeforeAll to record the start time and @AfterAll to calculate the total duration. Here’s an example:

@BeforeAll
static void beforeAll() {
    startAll = Instant.now().toEpochMilli();
}

@AfterAll
static void afterAll() {
    long endAll = Instant.now().toEpochMilli();
    System.out.println("Total time: " + (endAll - startAll) + " ms");
}

Additionally, use @BeforeEach and @AfterEach to measure individual test durations. The tearDown() method can print detailed statistics for each test, helping you identify bottlenecks. When running tests in parallel, the overall suite time should be less than the sum of individual test times.

What is the difference between test forking and parallel execution?

Test forking refers to Gradle's ability to launch separate JVM processes to run different test classes (or suites) concurrently. Each fork runs independently, so tests in different forks don’t interfere. In contrast, parallel execution within a single fork (e.g., using JUnit 5's parallel mode) runs tests inside the same JVM. The maxParallelForks setting controls the former—multiple JVMs. This is typically simpler and more isolated. You can combine both approaches: use Gradle forks and then enable JUnit 5's junit.jupiter.execution.parallel.enabled for finer-grained concurrency. For most projects, Gradle forking is sufficient.

How do you create a test class that works well in parallel?

A parallel-safe test class should avoid shared mutable state. Mark it with an appropriate tag, like @Tag("parallel") and @Tag("UnitTest"). Each test method should be independent—here’s a simple example:

@Test
public void whenAny_thenCorrect1() throws InterruptedException {
    Thread.sleep(1000L);
    assertTrue(true);
}

All four identical tests sleep for one second and then assert true. With parallel execution, these methods run in separate threads or forks, so the total time should be about one second instead of four. Use @BeforeEach and @AfterEach to record individual timings. Avoid static variables that aren't thread-safe, and ensure test data is either immutable or created fresh each time.

What are best practices for parallel testing with Gradle and JUnit 5?

First, set maxParallelForks based on your CPU cores—start with the formula cores/2 + 1 and adjust. Second, use @Tag annotations to separate parallel and sequential tests; keep some tests serial if they rely on shared resources (e.g., database). Third, ensure tests are stateless and avoid shared files or in-memory data. Fourth, leverage JUnit 5’s junit.jupiter.execution.parallel.enabled for inside-fork parallelism if needed, but be cautious of thread-safety. Fifth, monitor test times with the timing hooks shown earlier. Finally, use Gradle’s --parallel flag for project-level parallelism across modules. Apply these practices to maximize throughput without flakiness.