Parallel Test Execution for JUnit 5

1. Introduction

In this article, we'll cover how to execute parallel unit tests using JUnit 5. First, we'll cover basic configuration and minimal requirements to start using this feature. Next, we'll show code examples for different situations, and in the end, we'll talk about the synchronization of shared resources.

Parallel test execution is an experimental feature available as an opt-in since version 5.3.

2. Configuration

First, we need to create a junit-platform.properties file in our src/test/resources folder to enable parallel test execution. We enable the parallelization feature by adding the following line in the mentioned file:

junit.jupiter.execution.parallel.enabled = true

Let's check our configuration by running a few tests. First, we'll create the FirstParallelUnitTest class and two tests in it:

public class FirstParallelUnitTest{
    @Test
    public void first() throws Exception{
        System.out.println("FirstParallelUnitTest first() start => " + Thread.currentThread().getName());
        Thread.sleep(500);
        System.out.println("FirstParallelUnitTest first() end => " + Thread.currentThread().getName());
    }
    @Test
    public void second() throws Exception{
        System.out.println("FirstParallelUnitTest second() start => " + Thread.currentThread().getName());
        Thread.sleep(500);
        System.out.println("FirstParallelUnitTest second() end => " + Thread.currentThread().getName());
    }
}

When we run our tests, we get the following output in the console:

FirstParallelUnitTest second() start => ForkJoinPool-1-worker-19
FirstParallelUnitTest second() end => ForkJoinPool-1-worker-19
FirstParallelUnitTest first() start => ForkJoinPool-1-worker-19
FirstParallelUnitTest first() end => ForkJoinPool-1-worker-19

In this output, we can notice two things. First, our tests run sequentially. Second, we use the ForkJoin thread pool. By enabling parallel execution, the JUnit engine starts using the ForkJoin thread pool.

Next, we need to add a configuration to utilize this thread pool. We need to choose a parallelization strategy. JUnit provides two implementations (dynamic and fixed) and a custom option to create our implementation.

Dynamic strategy determines the number of threads  based on the number of processors/cores multiplied by factor parameter (defaults to 1) specified using:

junit.jupiter.execution.parallel.config.dynamic.factor

On the other hand, the fixed strategy relies on a predefined number of threads specified by:

junit.jupiter.execution.parallel.config.fixed.parallelism

To use the custom strategy, we need to create it first by implementing the ParallelExecutionConfigurationStrategy interface.

3. Test Parallelization Within a Class

We already enabled parallel execution and picked a strategy. Now it's time to execute tests in parallel within the same class. There are two ways to configure this. One is using @Execution(ExecutionMode.CONCURRENT) annotation, and the second is using properties file and line:

junit.jupiter.execution.parallel.mode.default = concurrent

After we choose how to configure this and run our FirstParallelUnitTest class, we can see the following output:

FirstParallelUnitTest second() start => ForkJoinPool-1-worker-5
FirstParallelUnitTest first() start => ForkJoinPool-1-worker-19
FirstParallelUnitTest second() end => ForkJoinPool-1-worker-5
FirstParallelUnitTest first() end => ForkJoinPool-1-worker-19

From the output, we can see that both tests start simultaneously and in two different threads. Note that output can change from one run to another. This is expected when using the ForkJoin thread pool.

There is also an option to run all tests within the FirstParallelUnitTest class in the same thread. In the current scope, using parallelism and the same thread option is not viable so let's expand our scope and add one more test class in the next section.

4. Test Parallelization Within a Module

Before we introduce a new property, we'll create SecondParallelUnitTest class that has two methods similar to FirstParallelUnitTest:

public class SecondParallelUnitTest{
    @Test
    public void first() throws Exception{
        System.out.println("SecondParallelUnitTest first() start => " + Thread.currentThread().getName());
        Thread.sleep(500);
        System.out.println("SecondParallelUnitTest first() end => " + Thread.currentThread().getName());
    }
    @Test
    public void second() throws Exception{
        System.out.println("SecondParallelUnitTest second() start => " + Thread.currentThread().getName());
        Thread.sleep(500);
        System.out.println("SecondParallelUnitTest second() end => " + Thread.currentThread().getName());
    }
}

Before we run our tests in the same batch, we need to set property:

junit.jupiter.execution.parallel.mode.classes.default = concurrent

When we run both tests classes, we get the following output:

SecondParallelUnitTest second() start => ForkJoinPool-1-worker-23
FirstParallelUnitTest first() start => ForkJoinPool-1-worker-19
FirstParallelUnitTest second() start => ForkJoinPool-1-worker-9
SecondParallelUnitTest first() start => ForkJoinPool-1-worker-5
FirstParallelUnitTest first() end => ForkJoinPool-1-worker-19
SecondParallelUnitTest first() end => ForkJoinPool-1-worker-5
FirstParallelUnitTest second() end => ForkJoinPool-1-worker-9
SecondParallelUnitTest second() end => ForkJoinPool-1-worker-23

From the output, we can see that all four tests run in parallel in different threads.

Combining two properties we mentioned in this and previous section and their values (same_thread and concurrent), we get four different modes of execution:

1. (same_thread, same_thread) – all tests run sequentially
2. (same_thread, concurrent) – tests from one class run sequentially, but multiple classes run in parallel
3. (concurrent, same_thread) – tests from one class run parallel, but each class run separately
4. (concurrent, concurrent) – tests run in parallel

5. Synchronization

In ideal situations, all our unit tests are independent and isolated. However, sometimes that's hard to implement because they depend on shared resources. Then, when running tests in parallel, we need to synchronize over common resources in our tests. JUnit5 provides us with such mechanisms in the form of @ResourceLock annotation.

Similarly, as before, let's create ParallelResourceLockUnitTest class:

public class ParallelResourceLockUnitTest{
    private List<String> resources;
    @BeforeEach
    void before() {
        resources = new ArrayList<>();
        resources.add("test");
    }
    @AfterEach
    void after() {
        resources.clear();
    }
    @Test
    @ResourceLock(value = "resources")
    public void first() throws Exception {
        System.out.println("ParallelResourceLockUnitTest first() start => " + Thread.currentThread().getName());
        resources.add("first");
        System.out.println(resources);
        Thread.sleep(500);
        System.out.println("ParallelResourceLockUnitTest first() end => " + Thread.currentThread().getName());
    }
    @Test
    @ResourceLock(value = "resources")
    public void second() throws Exception {
        System.out.println("ParallelResourceLockUnitTest second() start => " + Thread.currentThread().getName());
        resources.add("second");
        System.out.println(resources);
        Thread.sleep(500);
        System.out.println("ParallelResourceLockUnitTest second() end => " + Thread.currentThread().getName());
    }
}

@ResourceLock allows us to specify which resource is shared and the type of lock we want to use (default is ResourceAccessMode.READ_WRITE). With the current setup, the JUnit engine will detect that our tests both use a shared resource and will execute them sequentially:

ParallelResourceLockUnitTest second() start => ForkJoinPool-1-worker-5
[test, second]
ParallelResourceLockUnitTest second() end => ForkJoinPool-1-worker-5
ParallelResourceLockUnitTest first() start => ForkJoinPool-1-worker-19
[test, first]
ParallelResourceLockUnitTest first() end => ForkJoinPool-1-worker-19

6. Conclusion

In this article, first, we covered how to configure parallel execution. Next, what are available strategies for parallelism and how to configure a number of threads? After that, we covered how different configurations affect test execution. In the end, we covered the synchronization of shared resources.

As always, code from this article can be found over on GitHub.