JUnit 5 Release Notes

The @EnabledIf annotation introduced in 5.1 M2 has been moved to the org.junit.jupiter.api.condition package.

The value attribute of @MethodSource is no longer mandatory. If no value (or an empty String) is supplied as a method name, a method with the same name as the current @ParameterizedTest method will be used as the factory method by convention.

New predefined @Enabled* and @Disabled* annotations for declarative conditional test execution. See the following sections of the User Guide for details.

New @DisabledIf annotation that is used to control whether the annotated test class or test method is enabled or disabled. It inverts the logic applied by @EnabledIf.

Prior to this release, the Vintage test engine only returned a childless TestDescriptor for test classes annotated with @Ignore. However, build tools like Gradle need to show an accurate number of tests, i.e. they want to access and count the test methods of a test class regardless whether it’s ignored. The Jupiter engine already discovers skipped containers, e.g. test classes annotated with @Disabled, including their children and descendants. The Vintage engine now adopts this approach and returns a full subtree of TestDescriptors for classes annotated with @Ignore. During execution, it will only report the TestDescriptor of the test class as skipped which is consistent with how the Jupiter engine reports skipped containers.

Test methods selected by fully qualified method name via DiscoverySelectors.selectMethod(String), via the method or methods element of the selectors configuration for the junitPlatform Gradle plugin, or via the -select-method or -m command-line options for the ConsoleLauncher can now contain special characters — for example, for JVM languages such as Kotlin and Groovy.

Summary table is no longer printed via the ConsoleLauncher and Gradle plugin when details mode NONE is selected, unless there are errors.

The current module layer is now used when scanning for test classes within modules. The current module layer is the one that the class loader for the ModuleUtils class returns. If the current layer cannot be obtained, the algorithm falls back to the boot layer.

The XML report produced by the ConsoleLauncher and Gradle plugin is no longer invalid when the exception message of a failed test contains the XML CDATA end marker ]]>.

The ConsoleLauncher, the Gradle plugin, and the Maven Surefire provider now attempt to write a valid class name into the classname attribute of <testcase/> elements in the XML reports. In addition, the name attribute of dynamic tests and test template invocations (such as repeated and parameterized tests) is now suffixed with the index of the invocation so they are distinguishable by reporting tools.

The Maven Surefire provider now includes the method parameter types when writing the name attribute of <testcase/> elements into XML reports. However, due to a limitation of Maven Surefire, instead of methodName(Type) they are written as methodName{Type}.

New SUMMARY details mode for the ConsoleLauncher and Gradle plugin which prints the table of success and failure counts at the end of test plan execution. This new mode is analogous to the previous behavior of the NONE details mode.

The summary table of a console launcher run now contains the initial ten stack trace lines to better describe the location of the failure.

Non-inherited composed annotations which are meta-annotated with a given @Inherited annotation are now considered to be implicitly inherited when searching for the given meta-annotation within a class hierarchy.

The Maven Surefire provider now supports the test parameter that tells Surefire to only execute a subset of test classes or methods, e.g. by specifying -Dtest=…​ on the command line (see the Surefire documentation for details).

Tests can now be included or excluded based on their tags using a tag expression language when executed using the Launcher, ConsoleLauncher, Gradle plugin, or Maven Surefire provider.

Test classes selected via one of the selectClass() variants in DiscoverySelectors, via the aClass or classes element of the selectors configuration for the junitPlatform Gradle plugin, or via the -select-class or -c command-line options for the ConsoleLauncher are no longer allowed to be private. This aligns with the behavior for test classes discovered via package, class path, and module path scanning.

Developers can now register extensions programmatically by annotating fields in test classes with @RegisterExtension.

New @EnabledIf annotation that is used to control whether the annotated test class or test method is enabled or disabled by evaluating a script from a dynamic scripting language such as JavaScript or Groovy.

@ValueSource now additionally supports literal values of type short, byte, float, char, and java.lang.Class for parameterized tests.

New support for parameterized tests for implicit conversion from a String to an argument of any of the following common Java types. See the implicit conversion table in the User Guide for examples.

New fallback mechanism for parameterized tests for implicit conversion from a String to an argument of a given target type if the target type declares exactly one suitable factory method or a factory constructor.

Due to a change in the JUnit Platform’s AnnotationUtils class, non-inherited composed annotations which are meta-annotated with a given @Inherited annotation are now considered to be implicitly inherited when searching for the given meta-annotation within a class hierarchy.

Extensions for JUnit Jupiter can now access JUnit Platform configuration parameters at runtime via the new getConfigurationParameter(String key) method in the ExtensionContext API.

Extensions for JUnit Jupiter can now access the Lifecycle of the current test instance via the new getTestInstanceLifecycle() method in the ExtensionContext API.

New callback interface CloseableResource introduced in ExtensionContext.Store. A Store is bound to the lifecycle of its extension context. When the lifecycle of an extension context ends, the associated store is closed, and each stored value that is an instance of ExtensionContext.Store.CloseableResource is notified by an invocation of its close() method.

Selected dynamic tests and test template invocations can now be executed separately without running the complete test factory or test template. This allows to rerun single or selected parameterized, repeated or dynamic tests by selecting their unique IDs in subsequent discovery requests.

New Kotlin-friendly fail methods added as top-level functions in the org.junit.jupiter.api package.

When using a tag filter to include/exclude a tag that represents a JUnit 4 category, e.g. "com.example.Integration", the Vintage Engine no longer mistakenly executes all test methods of test classes that contain at least one included test method, e.g. one that is annotated with @Category(com.example.Integration.class), regardless whether they belong to the same category.

New @SuiteDisplayName annotation in the junit-platform-suite-api module for declaring a custom display name for a test suite.

When running on Java 9 or higher the default implementations of getVersion() and getArtifactId() in the TestEngine interface query the Java Platform Module System for this information.

Class loading errors that occur during classpath scanning are now logged at DEBUG level (i.e., the FINE log level in java.util.logging) instead of as warnings.

New ModuleSelector discovery selector for scanning Java 9 modules for test classes.

New console launcher option --select-module <name> or -o <name> for selecting Java 9 modules for test discovery.

New console launcher option --scan-modules for scanning all resolved Java 9 modules available on the boot layer configuration for test discovery.

The JUnit Platform Maven Surefire provider now runs all specified tests in a single test run, i.e. all registered TestExecutionListeners will receive a single TestPlan. Previously, a separate TestPlan was discovered and executed for each test class.

The @Tag and @Tags annotations are now inherited within test class hierarchies.

New assertAll() variants in Assertions that accept collections of executables.

New Kotlin friendly assertions added as top-level functions in the org.junit.jupiter.api package.

@CsvFileSource now supports a numLinesToSkip attribute which can be used to skip header lines in CSV files.

New getOrComputeIfAbsent(Class) convenience method in ExtensionContext.Store that simplifies use cases where an extension wishes to store a single object of a given type (keyed by that type) in the Store and the object is created using the default constructor for that type.

The JupiterTestEngine supports the new JUnit Platform ModuleSelector for selecting Java 9 modules.

The VintageTestEngine supports the new JUnit Platform ModuleSelector for selecting Java 9 modules.

Summary table is no longer printed via the ConsoleLauncher and Gradle plugin when details mode NONE is selected, unless there are errors.

The XML report produced by the ConsoleLauncher and Gradle plugin is no longer invalid when the exception message of a failed test contains the XML CDATA end marker ]]>.

The ConsoleLauncher, the Gradle plugin, and the Maven Surefire provider now attempt to write a valid class name into the classname attribute of <testcase/> elements in the XML reports. In addition, the name attribute of dynamic tests and test template invocations (such as repeated and parameterized tests) is now suffixed with the index of the invocation so they are distinguishable by reporting tools.

The Maven Surefire provider now includes the method parameter types when writing the name attribute of <testcase/> elements into XML reports. However, due to a limitation of Maven Surefire, instead of methodName(Type) they are written as methodName{Type}.

Non-inherited composed annotations which are meta-annotated with a given @Inherited annotation are now considered to be implicitly inherited when searching for the given meta-annotation within a class hierarchy.

The JUnit Platform Maven Surefire provider now runs all specified tests in a single test run, i.e. all registered TestExecutionListeners will receive a single TestPlan. Previously, a separate TestPlan was discovered and executed for each test class.

New SUMMARY details mode for the ConsoleLauncher and Gradle plugin which prints the table of success and failure counts at the end of test plan execution. This new mode is analogous to the previous behavior of the NONE details mode.

The Maven Surefire provider now supports the test parameter that tells Surefire to only execute a subset of test classes or methods, e.g. by specifying -Dtest=…​ on the command line (see the Surefire documentation for details).

The @Tag and @Tags annotations are now inherited within test class hierarchies.

Due to a change in the JUnit Platform’s AnnotationUtils class, non-inherited composed annotations which are meta-annotated with a given @Inherited annotation are now considered to be implicitly inherited when searching for the given meta-annotation within a class hierarchy.

Failed tests are now reported correctly with Maven Surefire for test engines that do not use MethodSource (e.g. Spek).

Tests that write to System.out or System.err, in particular via a logging framework, are now consistently reported correctly when executed with a non-zero forkCount with Maven Surefire.

The JUnit Platform Maven Surefire provider now supports the redirectTestOutputToFile Surefire feature.

The JUnit Platform Maven Surefire provider now ignores empty strings supplied via <includeTags/>, <groups/>, <excludeTags/>, and <excludedGroups/>.

Trailing spaces in a @CsvSource or @CsvFileSource input line no longer yield null values.

@EnableRuleMigrationSupport previously failed to recognize @Rule methods that returned a subtype of one of the supported TestRule types. Moreover, it mistakenly instantiated some rules declared using methods multiple times. Now, once enabled, it will instantiate all declared rules (fields and methods) exactly once and call them in the same order used by JUnit 4.

Previously, disabled test classes were eagerly instantiated when Lifecycle.PER_CLASS was used. Now, ExecutionCondition evaluation always takes place before test class instantiation.

The junit-jupiter-migrationsupport module no longer incorrectly attempts to register the JupiterTestEngine via the ServiceLoader mechanism, thereby allowing it to be used as a module on the Java 9 module-path.

Failure messages for assertTrue() and assertFalse() in the Assertions class now include details about the expected and actual boolean values.

If a parameterized test does not consume all arguments supplied to it via argument sources, the unconsumed arguments are no longer included in the display name.

ExpectedExceptionSupport from the junit-jupiter-migrationsupport module no longer swallows exceptions if the test class does not declare a JUnit 4 ExpectedException rule.

PackageNameFilters are now applied to tests selected via a ClassSelector, MethodSelector or UniqueIdSelector.