jars/junit5-r5.10.2/documentation/src/docs/asciidoc/release-notes/release-notes-5.10.0.adoc

[[release-notes-5.10.0]]
== 5.10.0

*Date of Release:* July 23, 2023

*Scope:*

* Promotion of various experimental APIs to stable
* New `LauncherInterceptor` SPI
* New `testfeed` details mode for `ConsoleLauncher`
* New `ConsoleLauncher` subcommand for test discovery without execution
* Dry-run mode for test execution
* New `NamespacedHierarchicalStore` for use in third-party test engines
* Stacktrace pruning to hide internal JUnit calls
* New `@SelectMethod` support in test `@Suite` classes.
* New `TempDirFactory` SPI for customizing how temporary directories are created
* Failure threshold for `@RepeatedTest`
* New convenience base classes for implementing `ArgumentsProvider` and `ArgumentConverter`
* Custom class loader support for class/method selectors, `@MethodSource`, `@EnabledIf`,
  and `@DisabledIf`
* Improved configurability of parallel execution
* Numerous bug fixes and minor improvements

For a complete list of all _closed_ issues and pull requests for this release, consult the
link:{junit5-repo}+/milestone/65?closed=1+[5.10.0-M1],
link:{junit5-repo}+/milestone/69?closed=1+[5.10.0-RC1],
link:{junit5-repo}+/milestone/71?closed=1+[5.10.0-RC2], and
link:{junit5-repo}+/milestone/70?closed=1+[5.10.0 GA] milestone pages in the JUnit
repository on GitHub.


[[release-notes-5.10.0-junit-platform]]
=== JUnit Platform

==== Deprecations and Breaking Changes

* Building native images with GraalVM now requires configuring the build arg
  `--initialize-at-build-time=org.junit.platform.launcher.core.LauncherConfig` and
  `--initialize-at-build-time=org.junit.jupiter.engine.config.InstantiatingConfigurationParameterConverter`.
* The `getMethodParameterTypes()` methods in `MethodSelector` and `NestedMethodSelector`
  have been deprecated and replaced by `getParameterTypeNames()` for greater clarity.

==== New Features and Improvements

* Various "experimental" APIs have been promoted to "stable", including
  `ModuleSelector`, `EngineDiscoveryListener`, `EngineDiscoveryRequestResolver`,
  `LauncherSession`, `LauncherSessionListener`, parallel execution support classes,
  `@Suite` and related annotations, and others.
* All utility methods in `ReflectionSupport` that return a `List` now have counterparts
  which return a `Stream`.
* New `tryToLoadClass(...)` variant in `ReflectionSupport` that accepts an explicit
  `ClassLoader`, allowing classes to be resolved with custom `ClassLoader` arrangements.
* `ReflectionSupport.findMethod(Class<?>, String, String)` now uses the `ClassLoader` of
  the supplied `Class` to load parameter types instead of using the _default_
  `ClassLoader`. This allows parameter types to be resolved with custom `ClassLoader`
  arrangements (such as OSGi). Consequently, `DiscoverySelectors.selectMethod(Class<?>,
  String, String)` also now works properly with custom `ClassLoader` arrangements.

* New `@SelectMethod` selector support in the `@Suite` test engine.
* Classes may now be selected by fully-qualified name via the `names` attribute in
  `@SelectClasses`.
* New overloaded constructors for `ClassSelector`, `NestedClassSelector`,
  `MethodSelector`, and `NestedMethodSelector` that take an explicit `ClassLoader` as a
  parameter, allowing selectors to select classes in custom `ClassLoader` arrangements
  like in OSGi.
* New `selectMethod()` and `selectNestedMethod()` variants in `DiscoverySelectors` that
  accept a `Class<?>...` argument of parameter types as a type-safe alternative to
  providing the names of parameter types as a comma-delimited string.
* For consistency with JUnit Jupiter lifecycle callbacks, listener method pairs for
  started/finished and opened/closed events are now invoked using "wrapping" semantics.
  This means that finished/closed event methods are invoked in reverse order compared to
  the corresponding started/opened event methods when multiple listeners are registered.
  This affects the following listener interfaces:
  `TestExecutionListener`, `EngineExecutionListener`, `LauncherDiscoveryListener`, and
  `LauncherSessionListener`.
* New `LauncherInterceptor` SPI for intercepting the creation of instances of `Launcher`
  and `LauncherSessionlistener` as well as invocations of the `discover` and `execute`
  methods of the former. Please refer to the
  <<../user-guide/index.adoc#launcher-api-launcher-interceptors-custom, User Guide>> for
  details.
* Support for limiting the `max-pool-size-factor` for parallel execution via a
  configuration parameter.
* New `testfeed` details mode for `ConsoleLauncher` that prints test execution events as
  they occur in a concise format.
* The existing functionality of the `ConsoleLauncher` has been split into two subcommands:
  `execute` for executing tests and `engines` for listing registered test engines.
* A new `discover` subcommand has been added to the `ConsoleLauncher` to print the
  discovered tests for the specified details mode without executing them.
* Improved error message for cyclic graphs detected during test discovery to be more
  actionable.
* Extracted `NamespacedHierarchicalStore` from JUnit Jupiter engine for reuse by other
  test engines and their extensions.
* New dry-run mode to simulate test execution without actually running tests. Please refer
  to the <<../user-guide/index.adoc#launcher-api-dry-run-mode, User Guide>> for details.
* Stack traces produced by failing tests are now pruned of calls from the `org.junit`,
  `jdk.internal.reflect`, and `sun.reflect` packages. This feature can be disabled via a
  configuration parameter. Please refer to the
  <<../user-guide/index.adoc#stacktrace-pruning, User Guide>> for details.
* New `getAncestors()` method in `TestDescriptor`.


[[release-notes-5.10.0-junit-jupiter]]
=== JUnit Jupiter

==== Bug Fixes

* The extensions supporting `@MethodSource`, `@EnabledIf`, and `@DisabledIf` now load
  classes by fully-qualified class name using the `ClassLoader` obtained from the test
  class when possible. This allows classes to be resolved with custom `ClassLoader`
  arrangements (such as OSGi).
* When converting an argument for a `@ParameterizedTest` method from a fully-qualified
  class name (`String`) to a `Class`, the `ClassLoader` of the class in which the
  `@ParameterizedTest` method is declared is now used to resolve the `Class` instead of
  the _default_ `ClassLoader`.

==== Deprecations and Breaking Changes

* The `dynamic` parallel execution strategy now allows the thread pool to be saturated by
  default.
* Implicit type conversion of boolean values like in `@CsvSource` is now stricter, only
  allowing values `"true"` or `"false"` (case-insensitive), in order to make accidental
  mistakes apparent and to avoid potential confusion.

==== New Features and Improvements

* Various "experimental" APIs have been promoted to "stable", including
  `MethodOrderer`, `ClassOrderer`, `InvocationInterceptor`,
  `LifecycleMethodExecutionExceptionHandler`, `@TempDir`, parallel execution annotations,
  and others.
* `JAVA_22` has been added to the `JRE` enum for use with JRE-based execution conditions.
* New `reason` attribute in `@Execution` which can be used to document the reason for
  using the selected execution mode.
* New `junit.jupiter.execution.parallel.config.dynamic.max-pool-size-factor` configuration
  parameter to set the maximum pool size factor.
* New `junit.jupiter.execution.parallel.config.dynamic.saturate` configuration
  parameter to disable pool saturation.
* `@RepeatedTest` can now be configured with a failure threshold which signifies the
  number of failures after which remaining repetitions will be automatically skipped. See
  the <<../user-guide/index.adoc#writing-tests-repeated-tests, User Guide>> for details.
* If `@MethodSource` is used with a non-static factory method that should be `static`, the
  exception thrown now provides the user a meaningful explanation of how to address the
  problem.
* `@EmptySource` now supports additional types, including `Collection` and `Map` subtypes
  with a public no-arg constructor.
* New `ArgumentsAccessor.getInvocationIndex()` method that supplies the index of a
  `@ParameterizedTest` invocation.
* New `AnnotationBasedArgumentsProvider` convenience base class which implements both
  `ArgumentsProvider` and `AnnotationConsumer`.
* New `AnnotationBasedArgumentConverter` convenience base class which implements both
  `ArgumentConverter` and `AnnotationConsumer`.
* `@TempDir` can now be used as a meta-annotation in order to create custom _composed
  annotations_. See the `@JimfsTempDir` example in the
  <<../user-guide/index.adoc#writing-tests-built-in-extensions-TempDirectory, User Guide>>
  for details.
* `@TempDir` now successfully cleans up files and directories on Windows that are set to
  read-only.
* New `TempDirFactory` SPI for customizing how the `@TempDir` extension creates temporary
  directories. See the
  <<../user-guide/index.adoc#writing-tests-built-in-extensions-TempDirectory, User Guide>>
  for details.
* The <<../user-guide/index.adoc#extensions-RandomNumberExtension, User Guide>> now
  includes an example implementation of the `RandomNumberExtension` in order to improve
  the documentation for extension registration via `@ExtendWith` on fields.
* The scope of applicability for `TestWatcher` implementations is now more extensively
  documented in the User Guide and Javadoc.
* `DisplayNameGenerator` methods are now allowed to return `null`, in order to signal to
  fall back to the default display name generator.


[[release-notes-5.10.0-junit-vintage]]
=== JUnit Vintage

No changes.