[[release-notes-5.7.0]]
== 5.7.0

*Date of Release:* September 13, 2020

*Scope:*

* Promotion of experimental features in JUnit Platform and Jupiter
* Java Flight Recorder support
* TestKit improvements
* `@Isolated` tests
* Configurable default method orderer
* Custom disabled reasons for all `@Enabled*`/`@Disabled*` annotations
* Improvements to `assertTimeoutPreemptively()`
* Improvements to `@CsvFileSource` and `@CsvSource`


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


[[release-notes-5.7.0-RC1-overall-improvements]]
=== Overall Improvements

* Javadoc JARs now contain `package-list` in addition to `element-list` for compatibility
  with tools like NetBeans 11.


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

==== Promoted Features

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

* `LauncherConstants` is now _stable_
* `LauncherConfig` (except for methods introduced in 5.7) is now _stable_
* `LegacyXmlReportGeneratingListener` is now _stable_
* `org.junit.platform.testkit.engine` is now _maintained_

==== Bug Fixes

* 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 `&#0;`.
* The `Launcher` now throws an exception when a previously executed `TestPlan` is
  attempted to be executed again.

==== Deprecations and Breaking Changes

* 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:
  - `execute(String, EngineDiscoveryRequest)` → `execute(String, LauncherDiscoveryRequest)`
  - `execute(TestEngine, EngineDiscoveryRequest)` → `execute(TestEngine, LauncherDiscoveryRequest)`
  - `Builder.filters(DiscoveryFilter...)` → `Builder.filters(Filter...)`
* `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.

==== New Features and Improvements

* 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.
* The `@Testable` annotation may now target any element type, including fields, methods,
  classes, packages, and modules.
* 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.


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

==== Promoted Features

The following APIs have been promoted from _experimental_ to _stable_:

* `junit-jupiter-migrationsupport`
* `junit-jupiter-params` (i.e. `@ParameterizedTest` etc.)
* `@TestMethodOrder`, `MethodOrderer`, and its pre-5.7 implementations
* `@DisplayNameGeneration`, `DisplayNameGenerator`, and its pre-5.7 implementations
* `@Timeout`
* `TestInstanceFactory`
* `TestInstancePreDestroyCallback`
* `TestInstances` and corresponding `ExtensionContext` methods
* `TestWatcher`
* Kotlin-specific assertions that were introduced in 5.1

==== Bug Fixes

* `@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.
* `CloseableResource` instances stored in `ExtensionContext.Store` are now closed in the
  reverse order they were added in. Previously, the order was undefined and unstable.
* 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.

==== Deprecations and Breaking Changes

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

==== New Features and Improvements

* 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.
* 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.


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

==== Bug Fixes

* 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.

==== New Features and Improvements

* 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.
