JUnit 5 Release Notes

The following APIs have been promoted from "experimental" status:

In XML reports generated by the ConsoleLauncher or LegacyXmlReportGeneratingListener, characters in exception messages and other user-supplied values that are not allowed in XML are now replaced with their character reference – for example, \0 becomes �.

The Launcher now throws an exception when a previously executed TestPlan is attempted to be executed again.

EngineTestKit no longer takes into account implicit configuration parameters (i.e. system properties and the junit-platform.properties classpath resource) by default. This change makes tests executed via EngineTestKit independent of the environment they are executed in.

When using the ConsoleLauncher, classes selected explicitly via --select-class and --select-method are now always executed regardless of class name patterns provided via --include-classname or the default class name pattern.

The ConsoleLauncher now honors the --disable-ansi-colors option when printing usage help.

New FilePosition support in FileSelector and ClasspathResourceSelector.

New getJavaClass() and getJavaMethod() methods in org.junit.platform.engine.support.descriptor.MethodSource.

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

New org.junit.platform.jfr module. When running on Java 11 or later, it provides and registers a TestExecutionListener that generates Java Flight Recorder events.

The ExecutionRecorder in junit-platform-testkit is now public for fine-grained testing of classes that use EngineExecutionListener.

ForkJoinPoolHierarchicalTestExecutorService can now be constructed by supplying a ParallelExecutionConfiguration.

HierarchicalTestEngine now supports a global resource lock.

The following APIs have been promoted from experimental to stable:

Inherited @BeforeEach methods are now executed on correct instances for @Nested classes.

Registered TestInstancePreDestroyCallback extensions are now always called if an instance of a test class was created, regardless whether any registered TestInstancePostProcessor extension threw an exception.

Disabled @TestTemplate methods (e.g. @ParameterizedTest and @RepeatedTest methods) are now reported to registered TestWatcher extensions.

MethodOrderer.Alphanumeric has been deprecated in favor of MethodOrderer.MethodName which provides the exact same functionality but has a more descriptive name.

New assertLinesMatch() method overloads in Assertions that accept two Stream<String> instances for comparison.

assertTimeoutPreemptively() in Assertions now reports the stack trace of the timed out thread in the cause of the AssertionFailedError.

assertTimeoutPreemptively() now uses threads with a specific name, conveying their use by the framework, to facilitate debugging and stack trace analysis.

All @Enabled*/@Disabled* annotations now have an optional disabledReason attribute that can be used to provide an additional explanation as to why a test or container might be disabled.

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

New MethodOrderer.MethodName to replace MethodOrderer.Alphanumeric with the exact same functionality but a more descriptive name.

New junit.jupiter.testmethod.order.default configuration parameter to set the default MethodOrderer that will be used unless @TestMethodOrder is present.

New DynamicTest.stream() factory method that accepts a Stream instead of an Iterator for the input source.

@CsvFileSource now allows one to specify file paths as an alternative to classpath resources.

@CsvFileSource and @CsvSource now provide a maxCharsPerColumn attribute for configuring the maximum number of characters per column.

Arguments in display names of parameterized test invocations are now truncated if they exceed a configurable maximum length (defaults to 512 characters).

New @Isolated annotation allows to run test classes in isolation of other test classes when using parallel test execution.

New TypedArgumentConverter for converting one specific type to another, therefore reducing boilerplate type checks compared to implementing ArgumentConverter directly.

New ExtensionContext.getConfigurationParameter(String, Function<String, T>) convenience method for reading transformed configuration parameters from extensions.

In the EngineTestKit API, the all(), containers(), and tests() methods in EngineExecutionResults that were deprecated in JUnit Platform 1.6.0 have been removed in favor of allEvents(), containerEvents(), and testEvents(), respectively.

The following methods in EngineTestKit are now deprecated with replacements:

The number of containers and tests excluded by post discovery filters based on their tags is now logged, along with the exclusion reasons.

New junit.platform.execution.listeners.deactivate configuration parameter that allows one to specify a comma-separated list of patterns for deactivating TestExecutionListener implementations registered via the ServiceLoader mechanism.

The @Testable annotation may now be applied directly to fields.

New Node.DynamicTestExecutor#execute(TestDescriptor, EngineExecutionListener) method for engines that wish to provide a custom EngineExecutionListener and cancel or wait for the execution of a submitted test via the returned Future.

New EngineExecutionListener.NOOP EngineExecutionListener implementation.

All declared methods in the EngineExecutionListener API now have empty default implementations.

The EngineTestKit now reuses the same test discovery and execution logic as the Launcher. Thus, it’s now possible to test an engine’s behavior in the presence of post-discovery filters (e.g. tag filters) and with regard to pruning.

The EngineTestKit now supports matching conditions with events loosely, i.e. an incomplete match with or without a fixed order.

@TempDir is now able to clean up files in read-only directories.

The Jupiter engine now ignores MethodSelectors for methods in non-Jupiter test classes instead of failing for missing methods in such cases.

New @EnabledIf and @DisabledIf annotations can be used to enable or disable a test or container based on condition methods.

New MethodOrderer named DisplayName that sorts test methods alphanumerically based on their display names.

New DisplayNameGenerator named Simple (based on Standard) that removes trailing parentheses for methods with no parameters.

assertThrows() for Kotlin can now be used with suspending functions and other lambda contexts that require inlining.

The JRE enum now provides a static currentVersion() method that returns the enum constant for the currently executing JRE, e.g. for use in custom execution conditions and other extensions.

The name attribute of @ParameterizedTest is now clearly documented to be a MessageFormat pattern.

Synthetic constructors are now ignored when instantiating a test class.

The Javadoc for the provideTestTemplateInvocationContexts() method in TestTemplateInvocationContextProvider has been aligned with the actual implementation. Providers are now officially allowed to return an empty stream, and the error message when all provided streams are empty is now more helpful.

New getDisplayName() method in MethodDescriptor for use in MethodOrderer implementations.

The Vintage engine no longer fails when resolving a MethodSelector for methods of test classes that cannot be found via reflection. This allows selecting Spock feature methods by their source code name even though they have a generated method name in the bytecode.

The internal JUnit4VersionCheck class — which verifies that a supported version of JUnit 4 is on the classpath — now implements a lenient version ID parsing algorithm in order to support custom version ID formats such as 4.12.0, 4.12-patch_1, etc.

ReflectionSupport.findNestedClasses() no longer detects inner class cycles for classes that do not match the supplied Predicate. For example, JUnit Jupiter no longer throws an exception if an inner class cycle is detected in a nested class hierarchy whose inner classes are not annotated with @Nested.

Test discovery no longer halts with an exception for inner class hierarchies that form a cycle if such inner classes are not annotated with @Nested.

Generating display names from JUnit 4 Descriptions now falls back to getDisplayName if getMethodName returns a blank String instead of throwing an exception.

In order to avoid file locking issues on Microsoft Windows, URLs are no longer cached when loading junit-platform.properties files.

The presence of multiple junit-platform.properties files on the classpath now only results in a warning if the files have different URLs.

TestInstancePreDestroyCallback extensions are now invoked in reverse registration order when PER_CLASS test instance lifecycle semantics have been configured.