[[release-notes-5.13.0]]
== 5.13.0

*Date of Release:* May 30, 2025

*Scope:*

* Introduce `@ClassTemplate` and `@ParameterizedClass` support in JUnit Jupiter
* Access to `ParameterInfo` for JUnit Jupiter extensions
* New `@SentenceFragment` annotation for use with `IndicativeSentences` display name generator
* Add `--redirect-stdout` and `--redirect-stderr` options to `ConsoleLauncher`
* Introduce test _discovery_ support in `EngineTestKit`
* Reporting of discovery issues for test engines
* Resource management for launcher sessions and execution requests
* GraalVM: removal of `native-image.properties` files from JARs
* Bug fixes and other minor improvements

For a complete list of all _closed_ issues and pull requests for this release, consult the
link:{junit-framework-repo}+/milestone/85?closed=1+[5.13.0-M1],
link:{junit-framework-repo}+/milestone/92?closed=1+[5.13.0-M2],
link:{junit-framework-repo}+/milestone/93?closed=1+[5.13.0-M3],
link:{junit-framework-repo}+/milestone/96?closed=1+[5.13.0-RC1],
and link:{junit-framework-repo}+/milestone/94?closed=1+[5.13.0] milestone pages in the
JUnit repository on GitHub.


[[release-notes-5.13.0-overall-improvements]]
=== Overall Changes

[[release-notes-5.13.0-overall-new-features-and-improvements]]
==== Deprecations and Breaking Changes

* The JUnit feature in GraalVM Native Build Tools (NBT) has been rewritten to no longer
  require JUnit classes to be initialized at build time when running on JDK 22 and later.
  Therefore, JUnit's JARs no longer ship with `native-image.properties` files that contain
  `--initialize-at-build-time` options (introduced in 5.12.0). Please update to the most
  recent version of GraalVM Native Build Tools prior to upgrading to this version of
  JUnit. Please refer to the
  https://github.com/junit-team/junit-framework/wiki/Upgrading-to-JUnit-5.13[Upgrade Instructions]
  in the wiki for details if you're on NBT 0.10.x or earlier.


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

[[release-notes-5.13.0-junit-platform-bug-fixes]]
==== Bug Fixes

* Notify `LauncherDiscoveryListener` implementation registered via `LaucherConfig` or on
  the `Launcher` of `selectorProcessed` events.
* Reintroduce support for JVM shutdown hooks when using the `-cp`/`--classpath` option of
  the `ConsoleLauncher`. Prior to this release, the created class loader was closed prior
  to JVM shutdown hooks being invoked, which caused hooks to fail with a
  `ClassNotFoundException` when loading classes during shutdown.
* Fix support of `--uid` and `--select-unique-id` options in the console launcher.

[[release-notes-5.13.0-junit-platform-new-features-and-improvements]]
==== New Features and Improvements

* Introduce a mechanism for `TestEngine` implementations to report issues encountered
  during test discovery. If an engine reports a `DiscoveryIssue` with a `Severity` equal
  to or higher than a configurable critical severity, its tests will not be executed.
  Instead, the engine will be reported as failed during execution with a failure message
  listing all critical issues. Non-critical issues will be logged but will not prevent the
  engine from executing its tests. The critical severity can be configured via a new
  configuration parameter and, currently, defaults to `ERROR`. Please refer to the
  <<../user-guide/index.adoc#running-tests-discovery-issues, User Guide>> for details.
+
If you're a test engine maintainer, please see the
<<../user-guide/index.adoc#test-engines-discovery-issues, User Guide>> for details on how
to start reporting discovery issues.
* Start reporting discovery issues for problematic `@Suite` classes:
  - Invalid `@Suite` class declarations (for example, when `private`)
  - Invalid `@BeforeSuite`/`@AfterSuite` method declarations (for example, when not
    `static`)
  - Cyclic dependencies between `@Suite` classes
* Introduce resource management mechanism that allows preparing and sharing state across
  executions or test engines via stores that are scoped to a `LauncherSession` or
  `ExecutionRequest`. The Jupiter API uses these stores as ancestors to the `Store`
  instances accessible via `ExtensionContext` and provides a new method to access them
  directly. Please refer to the User Guide for examples of managing
  <<../user-guide/index.adoc#launcher-api-launcher-session-listeners-tool-example-usage, session-scoped>>
  and
  <<../user-guide/index.adoc#launcher-api-managing-state-across-test-engines, request-scoped>>
  resources.
* New `ConsoleLauncher` options `--redirect-stdout` and `--redirect-stderr` for
  redirecting `stdout` and `stderr` output streams to files.
* Add `TestDescriptor.Visitor.composite(List)` factory method for creating a composite
  visitor that delegates to the given visitors in order.
* Introduce test _discovery_ support in `EngineTestKit` to ease testing for discovery
  issues produced by a `TestEngine`. Please refer to the
  <<../user-guide/index.adoc#testkit-engine, User Guide>> for details.
* Make validation of including `EngineFilters` more strict to avoid misconfiguration, for
  example, due to typos. Prior to this release, an exception was only thrown when _none_
  of a filter's included IDs matched any engine. Now, an exception is thrown if at least
  one included ID across all filters did not match any engine.


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

[[release-notes-5.13.0-junit-jupiter-bug-fixes]]
==== Bug Fixes

* If the `autoCloseArguments` attribute in `@ParameterizedTest` is set to `true`, all
  arguments returned by registered `ArgumentsProvider` implementations are now closed even
  if the test method declares fewer parameters.
* `AutoCloseable` arguments returned by an `ArgumentsProvider` are now closed even if they
  are wrapped with `Named`.
* `AutoCloseable` arguments returned by an `ArgumentsProvider` are now closed even if a
  failure happens prior to invoking the parameterized method.
* Validate _all_ versions specified in `@EnabledOnJre` and `@DisabledOnJre` annotations.

[[release-notes-5.13.0-junit-jupiter-new-features-and-improvements]]
==== New Features and Improvements

* New `@ClassTemplate` annotation and `ClassTemplateInvocationContextProvider` API that
  allow declaring a top-level or `@Nested` test class as a template to be invoked multiple
  times. This may be used, for example, to inject different parameters to be used by all
  tests in the class template or to set up each invocation of the class template
  differently. Please refer to the
  <<../user-guide/index.adoc#writing-tests-class-templates, User Guide>> for details.
* New `BeforeClassTemplateInvocationCallback` and `AfterClassTemplateInvocationCallback`
  extension callback interfaces allow implementing extensions that are invoked before and
  after each invocation of a class template.
* New `@ParameterizedClass` support that builds on `@ClassTemplate` and allows declaring a
  top-level or `@Nested` test class as a parameterized test class to be invoked multiple
  times with different arguments. The same `@...Source` annotations supported with
  `@ParameterizedTest` may be used to provide arguments via constructor or field
  injection. Please refer to the
  <<../user-guide/index.adoc#writing-tests-parameterized-tests, User Guide>> for details.
* New `@ParameterizedClass`-specific
  `@BeforeParameterizedClassInvocation`/`@AfterParameterizedClassInvocation` lifecycle
  methods that are invoked once before/after each invocation of the parameterized class.
* Provide access to the parameters and resolved arguments of a `@ParameterizedTest` or
  `@ParameterizedClass` by storing `ParameterInfo` in the `ExtensionContext.Store` for
  retrieval by other extensions. Please refer to the
  link:../api/org.junit.jupiter.params/org/junit/jupiter/params/support/ParameterInfo.html[Javadoc]
  for details.
* New `@SentenceFragment` annotation which allows one to supply custom text for individual
  sentence fragments when using the `IndicativeSentences` `DisplayNameGenerator`. See the
  updated documentation in the
  <<../user-guide/index.adoc#writing-tests-display-name-generator, User Guide>> for an
  example.
* New `TestTemplateInvocationContext.prepareInvocation(ExtensionContext)` callback method
  which allows extensions to prepare the `ExtensionContext` before the test template
  method is invoked. This may be used, for example, to store entries in the
  `ExtensionContext.Store` to benefit from its cleanup support or for retrieval by other
  extensions.
* Start reporting discovery issues for potentially problematic test classes:
    - Invalid `@Test` and `@TestTemplate` method declarations (for example, when return
      type is not `void`)
    - Invalid `@TestFactory` methods (for example, when return type is invalid)
    - Multiple method-level annotations (for example, `@Test` and `@TestTemplate`)
    - Invalid test class and `@Nested` class declarations (for example, `static` `@Nested`
      classes)
    - Potentially missing `@Nested` annotations (for example, non-abstract inner classes
      that contain test methods)
    - Invalid lifecycle method declarations (for example, when `private`)
    - Invalid `@Tag` syntax
    - Blank `@DisplayName` declarations
    - Blank `@SentenceFragment` declarations
    - `@BeforeParameterizedClassInvocation` and `@AfterParameterizedClassInvocation`
      methods declared in non-parameterized test classes
* By default, `AutoCloseable` objects put into `ExtensionContext.Store` are now treated
  like instances of `CloseableResource` (which has been deprecated) and are closed
  automatically when the store is closed at the end of the test lifecycle. It's possible
  to <<../user-guide/index.adoc#extensions-keeping-state-autocloseable-support, revert to the old behavior>>
  via a configuration parameter. Please also see the
  <<../user-guide/index.adoc#extensions-keeping-state-autocloseable-migration, migration note>>
  for third-party extensions wanting to support both JUnit 5.13 and earlier versions.
* `java.util.Locale` arguments are now converted according to the IETF BCP 47 language tag
  format. See the
  <<../user-guide/index.adoc#writing-tests-parameterized-tests-argument-conversion-implicit, User Guide>>
  for details.
* Avoid reporting potentially misleading validation exception for `@ParameterizedClass`
  test classes and `@ParameterizedTest` methods as suppressed exception for earlier
  failures.
* Add support for Kotlin `Sequence` to `@MethodSource`, `@FieldSource`, and
  `@TestFactory`.
* Allow publishing files to an existing directory via `TestReporter` and
  `ExtensionContext`, for example, when re-running a test class.


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

No changes.
