JUnit 5 Release Notes

Since the API Guardian dependency is no longer exported as a runtime but rather as a compile-only dependency to consuming Gradle projects, Gradle builds that define their own dependency configurations may be affected. For example, if the custom configuration is used to manipulate a source set’s classpath directly, dependency attributes needed for Gradle’s variant-aware dependency management are dropped, and API Guardian is missing from the compile classpath. In that case, the Java compiler emits warnings which — depending on your configured options — may cause the build to fail. The solution is to avoid manipulating a source set’s classpath directly. Instead, its dependency configurations should extend from your custom configuration. An example of such a change can be seen in this commit to the Spring Framework repository.

The API Guardian dependency is now exported as a compile-only dependency for consuming Gradle projects and no longer required at runtime when running on the module path.

Logging messages are no longer issued at INFO level in order to lower the "textual noise" on the console when Java’s Util Logging is used in its default configuration.

Classes explicitly selected via @SelectClasses are now always included in the test suite. This applies to @Suite classes running via the SuiteTestEngine and suite classes running via the JUnitPlatform Runner.

SummaryGeneratingListener is now thread-safe and can handle concurrently failing tests.

The JUnitPlatform runner has been deprecated in favor of the new @Suite support. See the warning in Using JUnit 4 to run the JUnit Platform for details.

For consistency with the rest of the JUnit Platform, the experimental LauncherDiscoveryListener is now an interface instead of an abstract class.

New junit-platform-suite-engine module to execute declarative test suites on the JUnit Platform. See JUnit Platform Suite Engine for details.

Additional selectors in the suite API in the junit-platform-suite-api module. See the Javadoc of the org.junit.platform.suite.api package for a full list of supported annotations and further details.

New UniqueIdTrackingListener which is a TestExecutionListener that tracks the unique IDs of all tests that were skipped or executed during the TestPlan and generates a file containing the unique IDs. The generated file can be used to rerun those tests — for example, in order to run the same set of tests executed on the JVM subsequently within a GraalVM native image. See the Javadoc for UniqueIdTrackingListener for details.

New findAnnotation(Class,Class,SearchOption) method in AnnotationSupport that performs the same search algorithm as findAnnotation(AnnotatedElement,Class) but also searches the enclosing class hierarchy for inner classes if the INCLUDE_ENCLOSING_CLASSES SearchOption is specified. This new method can be used by extension authors to find annotations on enclosing classes for JUnit Jupiter @Nested test classes.

New test(Condition<Event>) and nestedContainer(Class<?>, Condition<Event>) methods in EventConditions that allow you to provide conditions for matching against test and nested container events when using the EngineTestKit. For example, test(displayName("my test")) can be used to match against a test whose display name is my test.

Generating Java Flight Recorder (JFR) events via the junit-platform-jfr module is now also supported on Java 8 Update 262 or higher, in addition to Java 11 or later. See Flight Recorder Support for details.

The junit-platform-jfr module now publishes execution events for containers — for example, test classes.

The junit-platform-jfr module now publishes test discovery events for the launcher and registered test engines.

New ClassSource.from(URI) static factory method for creating a ClassSource from a URI using the class scheme and optional query parameters specifying the line number and column number. This is analogous to the existing ClasspathResourceSource.from(URI) factory method.

New getConfigurationParameters() method in the TestPlan which allows a TestExecutionListener to access configuration parameters. See Configuring an Execution Listener for details.

Custom LauncherDiscoveryListener implementations can now be registered via Java’s ServiceLoader mechanism.

Documented constant value of ExclusiveResource.GLOBAL_KEY.

Instances of TestIdentifier and UniqueId now retain less memory because they no longer store String representations of unique IDs.

Tools that make multiple calls to the Launcher API should now create a LauncherSession in order to allow for executing global setup and teardown code exactly once via the new LauncherSessionListener interface that can be registered via Java’s ServiceLoader mechanism.

@DisplayNameGeneration and @IndicativeSentencesGeneration are now only inherited from enclosing classes if the current class is a @Nested test class.

The IndicativeSentences DisplayNameGenerator no longer includes the display name of the enclosing class when generating an indicative sentence if the enclosing class is not configured to use the IndicativeSentences display name generator as well.

The TypedArgumentConverter base class now supports the conversion of a null source value in parameterized tests.

The TypedArgumentConverter base class now supports conversion to a primitive type if the configured target type is a wrapper for the target primitive type, including primitive widening support — for example, from Integer to int or long.

Exceptions thrown from instances of CloseableResource no longer hide test failures but are instead reported as suppressed exceptions.

The new autoCloseArguments feature in @ParameterizedTest may potentially be a breaking change for existing parameterized test methods if an argument that implements java.lang.AutoCloseable is reused for multiple invocations of the same parameterized test method. If your parameterized test methods start to fail when you upgrade to JUnit Jupiter 5.8, you can disable this feature by declaring @ParameterizedTest(autoCloseArguments = false).

InvocationInterceptor.interceptDynamicTest(Invocation<Void>, ExtensionContext) has been deprecated in favor of InvocationInterceptor.interceptDynamicTest(Invocation<Void>, DynamicTestInvocationContext, ExtensionContext) that provides access to the dynamic test executable via DynamicTestInvocationContext.getExecutable().

Test classes can now be ordered globally by supplying the fully-qualified name of a class implementing the ClassOrderer API as the value of the new junit.jupiter.testclass.order.default configuration parameter. See Class Order for details.

@Nested test classes can be ordered locally via the new @TestClassOrder annotation in which a ClassOrderer can be specified.

@ExtendWith may now be used to register extensions declaratively via fields or parameters in test class constructors, test methods, and lifecycle methods. See Declarative Extension Registration for details.

@RegisterExtension fields may now be private.

New assertThrowsExactly() method in Assertions which is a more strict version of assertThrows() that allows you to assert that the exception thrown is of the exact type specified.

assertDoesNotThrow() in Assertions now supports suspending functions when called from Kotlin.

New assertInstanceOf() methods which produce better error messages comparable to those produced by assertThrows. These new methods serve as a replacement for assertTrue(obj instanceof X).

assertNull() failure messages now include the actual object’s type if the toString() implementation for the actual object returns null or "null". This avoids the generation of confusing failure messages such as expected <null> but was <null>.

@TempDir can now be used to create multiple temporary directories. Instead of creating a single temporary directory per context (i.e. test class or method) every declaration of the @TempDir annotation on a field or method parameter now results in a separate temporary directory. To revert to the old behavior of using a single temporary directory for the entire test class or method (depending on which level the annotation is used), you can set the junit.jupiter.tempdir.scope configuration parameter to per_context.

@TempDir cleanup resets readable and executable permissions of the root temporary directory and any contained directories instead of failing to delete them.

@TempDir fields may now be private.

DynamicTests.stream() can now consume Named input and will use each name-value pair as the display name and value for each generated dynamic test (see User Guide for details).

New class URI scheme for dynamic test sources. This allows tests to be located using the information available in a StackTraceElement.

Dynamic tests now require less memory thanks to a number of improvements to internal data structures.

New autoCloseArguments attribute in @ParameterizedTest to close java.lang.AutoCloseable arguments after each invocation of the parameterized test method. This attribute defaults to true.

Numeric literals used with @CsvSource or CsvFileSource can now be expressed using underscores as in some JVM languages, to improve readability of long numbers like 700_000_000.

CSV rows provided via @CsvSource may now start with a number sign (#).

New ignoreLeadingAndTrailingWhitespace attributes in @CsvSource and @CsvFileSource (set to true by default) to control whether or not to trim whitespace.

In parameterized tests using @MethodSource or @ArgumentSource, arguments can now have optional names (supplied via the new Named API). When the argument is included in the display name of an invocation, this name will be used instead of the value.

Documented constant values in org.junit.jupiter.api.parallel.Resources.

If multiple exceptions are registered as failures for a JUnit 4 based test — for example, if the ErrorCollector rule throws an org.junit.runners.model.MultipleFailureException — all of those failures are now added as suppressed exceptions in the org.opentest4j.MultipleFailuresError created by the VintageTestEngine. This allows users to analyze the stack trace of each failure when such a test fails.

The JUnit Vintage engine now requires less memory and allows for earlier garbage collection thanks to a number of improvements to internal data structures.

Method getRootUrisForPackage() in class ClasspathScanner now returns a valid list of class names when the package name is equal to the name of a module on the module path and when running on Java 8.

Direct child descriptors of the engine descriptor now also acquire the global read lock when they require other exclusive resources.

Test classes annotated with @ResourceLock no longer run in parallel with @Isolated ones.

Improved ExclusiveResource handling: if a Node has only read locks and no read-write locks, then descendants are not forced into SAME_THREAD execution and can run concurrently.

Fix NullPointerException that occurred when using JUnit 3 style suite() methods in conjunction with PostDiscoveryFilters.

StringUtils.nullSafeToString() now returns "null" if the invocation of toString() on the supplied object returns null. Although this is an internal utility, the effect of this change may be witnessed by end users and test engine or extension authors.

Method scanForClassesInPackage(String) in ClasspathScanner now returns a valid list of class names when the package name is equal to the name of a module on the module path.

The legacy XML report now always includes container-level failures (e.g. from @BeforeAll Jupiter lifecycle methods).

If the toString() implementation of an argument passed to a @ParameterizedTest method returns null, the display name formatter for the parameterized test now treats the name of the corresponding argument as "null" instead of throwing an exception. This fixes a regression introduced in JUnit Jupiter 5.7.0.

Creator functions passed to ExtensionContext.Store.getOrComputeIfAbsent() are now only called once even if they throw an exception.

The user guide now explains Nested Tests in more detail.

New utility method in TestInstancePreDestroyCallback helps to ensure all test instances are processed when used in conjunction with @Nested tests.

JAVA_17 has been added to the JRE enum for use with JRE-based execution conditions.

The legacy reporting name of top-level test classes is now always their fully-qualified class name. Previously, a textual description was returned for JUnit 3 suites.