Writing your first test with JUnit 5 is straightforward. Annotate your test method with @Test and verify the result using assertions. Apart from the basic testing functionality of JUnit 5, there are some features you might not have heard about (yet). Discover five JUnit 5 features I found useful while working with JUnit 5: test execution order, nesting tests, parameter injection, parallelizing tests, and conditionally run tests.
Test Execution Ordering
The first feature we'll explore is influencing the test execution order.
While JUnit 5 has the following default-test execution order:
…, test methods will be ordered using an algorithm that is deterministic but intentionally nonobvious. This ensures that subsequent runs of a test suite execute test methods in the same order, thereby allowing for repeatable builds.
you can configure a different ordering mechanism.
Therefore, either implement your own MethodOrderer or use a built-in that orders: alphabetically, randomly, or numerically based on a specified value.
Let's take a look at how to order some unit tests using the OrderAnnotation ordering mechanism:
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 | @TestMethodOrder(MethodOrderer.OrderAnnotation.class) public class OrderedExecutionTest { @Test @Order(2) public void testTwo() { System.out.println("Executing testTwo"); assertEquals(4, 2 + 2); } @Test @Order(1) public void testOne() { System.out.println("Executing testOne"); assertEquals(4, 2 + 2); } @Test @Order(3) public void testThree() { System.out.println("Executing testThree"); assertEquals(4, 2 + 2); } } |
With @TestMethodOrder(MethodOrderer.OrderAnnotation.class) you basically opt-out from the JUnit 5 default ordering. The actual order is then specified with @Order. A lower value implies a higher priority.
Once you execute the tests above, the order is the following: testOne, testTwo and testThree.
As a general best practice your test should not rely on the order they are executed. Nevertheless, there are scenarios where this feature helps to execute the tests in configurable order.
Nesting Tests With JUnit 5
Usually, you test different business requirements inside the same test class. With Java and JUnit 5, you write them one after the other and add new tests to the bottom of the class.
While this is working for a small number of tests inside a class, this approach gets harder to manage for bigger test suites. Consider you want to adjust tests that verify a common scenario. As there is no defined order or grouping inside your test class you end up scrolling and searching them.
The following JUnit 5 feature allows you to counteract this pain point of a growing test suite: nested tests.
You can use this feature to group tests that verify common functionality. This does not only improves maintainability but also reduces the time to understand what the class under test is responsible for:
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 | public class NestedTest { @Nested @DisplayName("Testing division functionality") class DivisionTests { @Test public void shouldDivideByTwo() { assertEquals(4, 8 / 2); } @Test public void shouldThrowExceptionForDivideByZero() { assertThrows(ArithmeticException.class, () -> { int result = 8 / 0; }); } } @Nested @DisplayName("Testing addition functionality") class AdditionTests { @Test public void shouldAddTwo() { assertEquals(4, 2 + 2); } @Test public void shouldAddZero() { assertEquals(2, 2 + 0); } } } |
You might run into issues while using this feature in conjunction with some Spring Boot test features.
Parameter Injection With JUnit 5
JUnit 5 offers parameter injection for test constructor and method arguments. There are built-in parameter resolvers you can use to inject an instance of TestReport, TestInfo, or RepetitionInfo (in combination with a repeated test):
| 1 2 3 4 5 6 | @RepeatedTest(5) public void testMethodName(TestInfo testInfo, TestReporter testReporter, RepetitionInfo repetitionInfo) { System.out.println(testInfo.getTestMethod().get().getName()); testReporter.publishEntry("secretMessage", "JUnit 5"); System.out.println(repetitionInfo.getCurrentRepetition() + " from " + repetitionInfo.getTotalRepetitions()); } |
Furthermore, you can implement your own ParameterResolver to resolve arguments of any type.
We can use this mechanism to resolve a random UUID for our tests:
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 | public class RandomUUIDParameterResolver implements ParameterResolver { @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.PARAMETER) public @interface RandomUUID { } @Override public boolean supportsParameter(ParameterContext parameterContext, ExtensionContext extensionContext) { return parameterContext.isAnnotated(RandomUUID.class); } @Override public Object resolveParameter(ParameterContext parameterContext, ExtensionContext extensionContext) { return UUID.randomUUID().toString(); } } |
With supportsParameter we indicate that this resolver is capable of resolving a requested parameter, as you can have multiple ParameterResolver . We're checking if the requested parameter is annotated with our custom annotation. In addition, you could also verify that the parameter is of type String.
We can use this resolver for our tests once we register this extension with @ExtendWith:
| 1 2 3 4 5 6 7 8 | @ExtendWith(RandomUUIDParameterResolver.class) public class ParameterInjectionTest { @RepeatedTest(5) public void testUUIDInjection(@RandomUUID String uuid) { System.out.println("Random UUID: " + uuid); } } |
Test Parallelization With JUnit 5
While you might have configured this in the past with the corresponding Maven or Gradle plugin, you can now configure this as an experimental feature with JUnit (since version 5.3). This gives you more fine-grain control on how to parallelize the tests.
A basic configuration can look like the following:
| 1 2 | junit.jupiter.execution.parallel.enabled = true junit.jupiter.execution.parallel.mode.default = concurrent |
This enables parallel execution for all your tests and set the execution mode to concurrent. Compared to same_thread, concurrent does not enforce to execute the test in the same thread of the parent. For a per test class or method mode configuration, you can use the @Execution annotation.
There are multiple ways to set these configuration values, one is to use the Maven Surefire plugin for it:
| 1 2 3 4 5 6 7 8 9 10 11 12 | <plugin> <artifactId>maven-surefire-plugin</artifactId> <version>2.22.2</version> <configuration> <properties> <configurationParameters> junit.jupiter.execution.parallel.enabled = true junit.jupiter.execution.parallel.mode.default = concurrent </configurationParameters> </properties> </configuration> </plugin> |
or a junit-platform.properties file inside src/test/resources with the configuration values as content.
You should benefit the most when using this feature for unit tests. Enabling parallelization for integration tests might not be possible or easy to achieve, depending on your setup. Therefore, I can recommend executing your unit tests with the Maven Surefire plugin and configuring parallelization for them. All your integration tests can then be executed with the Maven Failsafe plugin, where you don't specify these JUnit 5 configuration parameters.
For more fine-grain parallelism configuration, take a look at the official JUnit 5 documentation.
Conditionally Disable Tests with JUnit 5
The last feature is useful when you want to avoid tests being executed based on different conditions. There might be tests that don't run on different operating systems or require different environment variables to be present.
JUnit 5 comes with some built-in conditions that you can use for your tests, e.g.:
| 1 2 3 4 5 6 7 8 9 10 11 | @Test @DisabledOnOs(OS.LINUX) public void disabledOnLinux() { assertEquals(42, 40 + 2); } @Test @DisabledIfEnvironmentVariable(named = "FLAKY_TESTS", matches = "false") public void disableFlakyTest() { assertEquals(42, 40 + 2); } |
On the other side, writing a custom condition is pretty straightforward. Let's consider you don't want to execute a test around midnight:
| 1 2 3 4 5 | @Test @DisabledOnMidnight public void disabledOnMidNight() { assertEquals(42, 40 + 2); } |
All you have to do is to implement ExecutionCondition and add your own condition:
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 | public class DisabledOnMidnightCondition implements ExecutionCondition { private static final ConditionEvaluationResult ENABLED_BY_DEFAULT = enabled("@DisabledOnMidnight is not present"); private static final ConditionEvaluationResult ENABLED_DURING_DAYTIME = enabled("Test is enabled during daytime"); private static final ConditionEvaluationResult DISABLED_ON_MIDNIGHT = disabled("Disabled as it is around midnight"); @Documented @Target({ElementType.TYPE, ElementType.METHOD}) @Retention(RetentionPolicy.RUNTIME) @ExtendWith(DisabledOnMidnightCondition.class) public @interface DisabledOnMidnight { } @Override public ConditionEvaluationResult evaluateExecutionCondition(ExtensionContext context) { Optional<DisabledOnMidnight> optional = findAnnotation(context.getElement(), DisabledOnMidnight.class); if (optional.isPresent()) { LocalDateTime now = LocalDateTime.now(); if (now.getHour() == 23 || now.getHour() <= 1) { return DISABLED_ON_MIDNIGHT; } else { return ENABLED_DURING_DAYTIME; } } return ENABLED_BY_DEFAULT; } } |
There is a dedicated testing category available on my blog for more content about JUnit and topics like Testcontainers, testing Spring Boot or Jakarta EE applications, etc.
You can find the source code for these five JUnit 5 features on GitHub.
Have fun using these JUnit 5 features,
Philip
