release-notes-5.0.0-M5.adoc

5.0.0-M5

Date of Release: ❓

Scope: Fifth milestone release of JUnit 5 with a focus on dynamic containers, test instance lifecycle management, and minor API changes.

Warning

This is a milestone release and contains breaking changes. Please refer to the instructions above to use this version in a version of IntelliJ IDEA that bundles an older milestone release.

For a complete list of all closed issues and pull requests for this release, consult the 5.0 M5 milestone page in the JUnit repository on GitHub.

• All published JAR artifacts now contain an Automatic-Module-Name manifest attribute whose value is used as the name of the automatic module defined by that JAR file when it is placed on the Java 9 module path.

Table 1. Automatic module names

JAR file	Automatic-Module-Name
junit-jupiter-api-<VERSION>.jar	org.junit.jupiter.api
junit-jupiter-engine-<VERSION>.jar	org.junit.jupiter.engine
junit-jupiter-migrationsupport-<VERSION>.jar	org.junit.jupiter.migrationsupport
junit-jupiter-params-<VERSION>.jar	org.junit.jupiter.params
junit-platform-commons-<VERSION>.jar	org.junit.platform.commons
junit-platform-console-<VERSION>.jar	org.junit.platform.console
junit-platform-engine-<VERSION>.jar	org.junit.platform.engine
junit-platform-gradle-plugin-<VERSION>.jar	org.junit.platform.gradle.plugin
junit-platform-launcher-<VERSION>.jar	org.junit.platform.launcher
junit-platform-runner-<VERSION>.jar	org.junit.platform.runner
junit-platform-suite-api-<VERSION>.jar	org.junit.platform.suite.api
junit-platform-surefire-provider-<VERSION>.jar	org.junit.platform.surefire.provider
junit-vintage-engine-<VERSION>.jar	org.junit.vintage.engine

JUnit Platform

Bug Fixes

• MethodSelector.getMethodParameterTypes() no longer returns null for parameter types if the selector is created via DiscoverySelectors without explicit parameter types. Specifically, if parameter types are not supplied and cannot be deduced, an empty string will be returned. Similarly, if parameter types are not explicitly supplied but can be deduced (e.g, via a supplied Method reference), getMethodParameterTypes() now returns a string containing the deduced parameter types.

• Instead of throwing a NullPointerException in Details.TREE mode, the ConsoleLauncher now prints the corresponding throwable’s toString() representation as a fallback mechanism.

• DefaultLauncher now catches and warns about exceptions generated by an engine in its discovery and execution phases. Other engines are processed normally.

• UniqueId.Segment type and value strings are now partially URL encoded when the string representation of a unique ID is generated. All characters reserved by the active UniqueIdFormat syntax (e.g., [, :, ], and /) are encoded. The default parser has also been updated to decode such encoded segments.

Deprecations and Breaking Changes

• The deprecated --hide-details option of the ConsoleLauncher has been removed; use --details none instead.

• The following previously deprecated methods have been removed.

  • junit-platform-engine: Node.execute(EngineExecutionContext)

  • junit-platform-commons: ReflectionUtils.findAllClassesInClasspathRoot(Path, Predicate, Predicate)

• The isLeaf() method of the org.junit.platform.engine.support.hierarchical.Node interface has been removed.

• The default methods pruneTree() and hasTests() have been removed from TestDescriptor.

New Features and Improvements

• When using DiscoverySelectors to select a method by its fully qualified method name or by providing methodParameterTypes as a comma-separated string, it is now possible to describe array parameter types using source code syntax such as int[] for a primitive array and java.lang.String[] for an object array. Furthermore, it is now possible to describe multidimensional array types using either the JVM’s internal String representation (e.g., [[[I for int[][][], [[Ljava.lang.String; for java.lang.String[][], etc.) or source code syntax (e.g., boolean[][][], java.lang.Double[][], etc.).

• The JUnit Platform Gradle plugin task junitPlatformTest can now be accessed directly during the configuration phase of a build.

• When a TestEngine is discovered via Java’s ServiceLoader mechanism, an attempt will now be made to determine the location from which the engine class was loaded, and if the location URL is available, it will be logged at configuration-level.

• The mayRegisterTests() method may be used to signal that a TestDescriptor will register dynamic tests during execution.

• The TestPlan may now be queried for whether it containsTests(). This is used by the Surefire provider to decide if a class is a test class that should be executed.

• The ENGINE enum constant was removed from TestDescriptor.Type. The default type of the EngineDescriptor is now TestDescriptor.Type.CONTAINER.

JUnit Jupiter

Bug Fixes

• @ParameterizedTest arguments are no longer resolved for lifecycle methods and test class constructors to improve interoperability with regular and parameterized test methods with different parameter lists.

Deprecations and Breaking Changes

• The migration support module is now named junit-jupiter-migrationsupport, without the dash - between migration and support.

• In order to ensure the composability of all supported extension APIs in JUnit Jupiter, several methods in existing APIs have been renamed.

  • See Extension API Migration for details.

• The arguments() method in the ArgumentsProvider API in the junit-jupiter-params module has been renamed to provideArguments().

• The ObjectArrayArguments class in the junit-jupiter-params module has been removed; the functionality for creating an Arguments instance is now available via the Arguments.of(…​) static factory method.

• The names property of @MethodSource has been renamed to value.

• The getTestInstance() method in the TestExtensionContext API has been moved to the ExtensionContext API. Furthermore, the signature has changed from Object getTestInstance() to Optional<Object> getTestInstance().

• The getTestException() method in the TestExtensionContext API has been moved to the ExtensionContext API.

• The TestExtensionContext and ContainerExtensionContext interfaces have been removed, and all Extension interfaces have been changed to use ExtensionContext instead.

Table 2. Extension API Migration

Extension API	Old Name	New Name
ParameterResolver	supports()	supportsParameter()
ParameterResolver	resolve()	resolveParameter()
ContainerExecutionCondition	evaluate()	evaluateContainerExecutionCondition()
TestExecutionCondition	evaluate()	evaluateTestExecutionCondition()
TestTemplateInvocationContextProvider	supports()	supportsTestTemplate()
TestTemplateInvocationContextProvider	provide()	provideTestTemplateInvocationContexts()

New Features and Improvements

• The test instance lifecycle can now be switched from the default per-method mode to a new per-class mode via the new class-level @TestInstance annotation. This enables shared test instance state between test methods in a given test class as well as between non-static @BeforeAll and @AfterAll methods in the test class.

  • See [writing-tests-test-instance-lifecycle] for details.

• @BeforeAll and @AfterAll methods are no longer required to be static if the test class is annotated with @TestInstance(Lifecycle.PER_CLASS). This enables the following new features.

  • Declaration of @BeforeAll and @AfterAll methods in @Nested test classes.

  • Declaration of @BeforeAll and @AfterAll on interface default methods.

  • Simplified declaration of @BeforeAll and @AfterAll methods in test classes implemented with the Kotlin programming language.

• Assertions.assertAll() now tracks exceptions of any type (as opposed to only tracking exceptions of type AssertionError), unless the exception is a blacklisted exception in which case it will be immediately rethrown.

• If a @ParameterizedTest accepts an array as an argument, the string representation of the array will now be converted to a human readable format when generating the display name for invocations of the parameterized test.

• The @EnumSource now provides an enum constant selection mode that controls how the supplied names are interpreted. Supported modes include INCLUDE and EXCLUDE as well as regular expression pattern matching modes MATCH_ALL and MATCH_ANY.

• Extensions may now share state across top-level test classes by using the Store of the newly introduced engine-level ExtensionContext.

• Argument providing methods referenced using @MethodSource may now return instances of DoubleStream, IntStream, and LongStream directly.

• @TestFactory now supports arbitrarily nested dynamic containers. See DynamicContainer and abstract base class DynamicNode for details.

JUnit Vintage

Bug Fixes

• The VintageTestEngine no longer filters out test classes declared as static member classes, since they are valid JUnit 4 test classes.

• The VintageTestEngine no longer attempts to execute abstract classes as test classes. Instead, a warning is now logged stating that such classes are excluded.