[[release-notes-5.4.0]]
== 5.4.0

*Date of Release:* February 7, 2019

*Scope:*

* New `junit-jupiter` dependency-aggregating artifact for simplified dependency management
  in build tools
* XML report generating listener
* Test Kit for testing engines and extensions
* `null` and _empty_ argument sources for `@ParameterizedTest` methods
* `@TempDir` support for temporary directories
* Custom display name generator API
* Support for ordering test methods
* Support for ordering extensions registered via `@RegisterExtension`
* `TestWatcher` extension API
* API for accessing outer test instances in `ExtensionContext`
* JUnit 4 `@Ignore` migration support
* Improved diagnostics and error reporting
* Improved documentation and user experience in the User Guide
* Discontinuation of the `junit-platform-surefire-provider`
* Various minor improvements and bug fixes

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


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

==== Bug Fixes

* The `junit-platform-suite-api` artifact no longer has an unnecessary direct dependency
  on `junit-platform-commons`.
* Containers and tests that interrupt the current thread no longer cause surprising
  failures in subsequent tests that interact with the reused thread.
  - This applies specifically to containers and tests executed via a
    `HierarchicalTestExecutorService` -- for example, a `@Test` method in JUnit Jupiter
    -- that interrupt the current thread -- for example, via
    `Thread.currentThread().interrupt()` -- but fail to clear the _interrupted status_
    flag for the current thread.
  - The `TestTask` implementation used internally by `HierarchicalTestExecutorService`
    implementations now automatically clears the _interrupted status_ for the current
    thread after the execution of each container and test and logs a message at `DEBUG`
    level (`FINE` in java.util.logging) if the _interrupted status_ is not cleared
    properly by user code.

==== Deprecations and Breaking Changes

* The JUnit Platform Maven Surefire Provider (`junit-platform-surefire-provider`) has
  been discontinued and is no longer released as part of JUnit 5. Please use
  <<../user-guide/index.adoc#running-tests-build-maven, Maven Surefire’s native support>>
  for running tests on the JUnit Platform instead (requires Maven Surefire 2.22.0 or
  higher).
* `TestPlan.add(TestIdentifier)` has always been considered _internal_ and is now
  _deprecated_. While calls from third-party code will continue to work for the time
  being, IDEs and build tools should remove any such code as soon as possible.

==== New Features and Improvements

* New `junit-platform-reporting` artifact containing a
  `LegacyXmlReportGeneratingListener` that generates XML reports using a format which is
  compatible with the de facto standard for JUnit 4 based test reports that was made
  popular by the Ant build system.
  - See <<../user-guide/index.adoc#launcher-api-listeners-reporting, JUnit Platform
    Reporting>> in the User Guide for details.
* New `junit-platform-testkit` artifact containing a _Test Kit_ API for testing the
  execution of a `{TestEngine}` running on the JUnit Platform.
  - See <<../user-guide/index.adoc#testkit, JUnit Platform Test Kit>> in the User Guide
    for details.
* If a container or test fails, the root cause and suppressed exceptions are now included
  in the stack trace printed by the `ConsoleLauncher`.
* The `ConsoleLauncher` now sanitizes user-provided display names before printing them to
  the console.
  - Common whitespace characters such as `\t`, `\n`, `\x0B`, `\f`, and `\r` are replaced
    by a standard space character, and all other ISO control characters are emitted as a
    single dot (`.`).
* New `ModifierSupport` class providing an API for extension and test engine authors to
  inspect modifiers of classes and members.
  - See the <<../user-guide/index.adoc#extensions-supported-utilities-modifier, User
    Guide>> for details.
* `AnnotationSupport` provides new methods for finding annotated fields and their values.
  - Consult the Javadoc for the various `findAnnotatedFields()` and
    `findAnnotatedFieldValues()` methods in `{AnnotationSupport}` for details.
* `ReflectionSupport` provides new methods for finding fields and reading a field's value.
  - Consult the Javadoc for the `findFields()` and `tryToReadFieldValue()` methods in
    `{ReflectionSupport}` for details.
* Exceptions reported due to failed reflective operations such as loading a class, reading
  a field's value, or looking up a method by name now include the original exception as
  their cause to make it easier to debug underlying issues.
* The `Launcher` API now provides an `execute(TestPlan, TestExecutionListener...)`
  method that allows one to execute a previously discovered `TestPlan`.
* `@RunWith(JUnitPlatform.class)` no longer executes test discovery twice.
* Implementations of `HierarchicalTestEngine` may now add behavior that wraps around the
  invocation of `Node.before()`, `Node.execute()`, and `Node.after()` using the new
  `Node.around()` hook.


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

==== Bug Fixes

* `@RegisterExtension` fields that are `null` when evaluated are no longer silently
  ignored. Instead, the corresponding test class or test method now fails with an
  informative exception.
* `@ParameterizedTest` once again supports `MessageFormat` patterns for individual
  parameters -- for example, `+{0,number,#.##}+`.
* `@ResourceLock` can now be declared on test template methods such as `@RepeatedTest` and
  `@ParameterizedTest` methods. If `@ResourceLock` is used, the invocations will run in
  the same thread, even if parallel execution is enabled.
* The `@Execution` and `@ResourceLock` annotations used to configure parallel test
  execution are now inherited within test class hierarchies (via `@Inherited` semantics).

==== Deprecations and Breaking Changes

* The default mode for parallel test execution has been changed from `CONCURRENT` to
  `SAME_THREAD` to allow for gradual opt-in by using the `@Execution` annotation on
  individual test classes or methods. You can invert this behavior by changing the default
  execution mode via the new `junit.jupiter.execution.parallel.mode.default`
  configuration parameter. Please refer to the
  <<../user-guide/index.adoc#writing-tests-parallel-execution, User Guide>> for details.

==== New Features and Improvements

* New `org.junit.jupiter:junit-jupiter` artifact that simplifies dependency management
  for JUnit Jupiter in build tools such as Gradle and Maven.
  - Specifically, this artifact aggregates all dependencies that are required to use
    JUnit Jupiter along with optional dependencies that extend the core Jupiter APIs.
  - It contains compile-time dependencies on `junit-jupiter-api` and
    `junit-jupiter-params` and a runtime dependency on `junit-jupiter-engine`.
* `Assertions.assertEquals()` variants that compare floating point numbers using a delta
  now support a _delta_ of zero.
* New `Assertions.assertEquals()` variants that accept mixed boxed and unboxed primitive
  values, allowing statements such as `assertEquals(42, Integer.valueOf("42"))` to
  compile.
* New `Assertions.assertNotEquals()` variants that accept the following primitive data
  types: `char`, `byte`, `short`, `int`, `long`, `float`, and `double`. Mixed boxed and
  unboxed primitive values are also supported.
* Exceptions thrown in `Assertions.assertAll()` are now additionally tracked as
  _suppressed exceptions_ in the resulting `MultipleFailuresError`. Consequently, the
  stack traces for such exceptions are now visible as _Suppressed_ at the end of the
  stack trace for the invocation of `assertAll()`.
* JUnit 4's `AssumptionViolatedException` is now supported in JUnit Jupiter for aborting
  a test mid-flight due to a failed assumption -- for example, via JUnit 4's
  `org.junit.Assume` utility class.
* JUnit 4's `@Ignore` annotation is now supported for disabling test classes and test
  methods via the `junit-jupiter-migrationsupport` module.
  - See the <<../user-guide/index.adoc#migrating-from-junit4-ignore-annotation-support,
    User Guide>> for details.
* New `@TempDir` extension (formerly part of JUnit Pioneer) that allows one to write tests
  that require a temporary directory in a `java.nio.file.FileSystem`.
  - See the <<../user-guide/index.adoc#writing-tests-built-in-extensions-TempDirectory,
    User Guide>> for details.
* In addition to returning streams, `@TestFactory`-annotated methods may now return a
  single `DynamicNode` -- for example, a `DynamicTest` or a `DynamicContainer`.
* New `@NullSource`, `@EmptySource`, and `@NullAndEmptySource` argument sources that
  provide `null` and _empty_ arguments to `@ParameterizedTest` methods.
  - See <<../user-guide/index.adoc#writing-tests-parameterized-tests-sources-null-and-empty,
    Null and Empty Sources>> in the User Guide for details.
* Implicit conversion from hexadecimal and octal string representations to integral types
  in `@ParameterizedTest` arguments -- for example, conversion from `"0xff"` to `255`.
* New `JAVA_12` and `JAVA_13` constants in the `JRE` enum for use with `@EnabledOnJre` and
  `@DisabledOnJre`.
* New `LOCALE` and `TIME_ZONE` constants in `org.junit.jupiter.api.parallel.Resources`
  for use with `@ResourceLock` to synchronize test execution regarding the default
  `Locale` and default `TimeZone`, respectively.
* New `MethodOrderer` API for ordering the sequence of tests with built-in support for
  _alphanumeric_, `@Order` annotation based, and _random_ ordering of test methods.
  - See <<../user-guide/index.adoc#writing-tests-test-execution-order, Test Execution
    Order>> in the User Guide for details.
* New `DisplayNameGenerator` interface and `@DisplayNameGeneration` annotation that allow
  declarative configuration of a pre-defined or custom display name generator.
  - See <<../user-guide/index.adoc#writing-tests-display-name-generator, Display Name
    Generators>> in the User Guide for details.
* New `TestWatcher` extension API that allows extensions to process test results by
  defining result-based callbacks invoked after text execution.
  - See <<../user-guide/index.adoc#extensions-test-result-processing, Test Result
    Processing>> in the User Guide for details.
* Extensions registered _programmatically_ via `@RegisterExtension` may now be registered
  in an explicit order via the `@Order` annotation.
  - See <<../user-guide/index.adoc#extensions-registration-programmatic-order, Extension
    Registration Order>> in the User Guide for details.
* New `ExtensionContext` methods to access all test instances, including enclosing ones
  for `@Nested` tests: `getTestInstances()` and `getRequiredTestInstances()`.


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

==== Bug Fixes

* The `VintageTestEngine` now uses the fully qualified class name as the _legacy reporting
  name_ for Vintage test classes instead of the simple class name which caused problems in
  test reports based on legacy reporting names -- for example, reports generated by Maven
  Surefire.

==== New Features and Improvements

* The `VintageTestEngine` now validates that the version of `junit:junit` on the classpath
  is supported (i.e., is equal to or greater than 4.12).
