diff --git a/documentation/src/docs/asciidoc/release-notes/release-notes-5.8.0.adoc b/documentation/src/docs/asciidoc/release-notes/release-notes-5.8.0.adoc index 7b8c4497caba..5582025143bc 100644 --- a/documentation/src/docs/asciidoc/release-notes/release-notes-5.8.0.adoc +++ b/documentation/src/docs/asciidoc/release-notes/release-notes-5.8.0.adoc @@ -29,12 +29,12 @@ on GitHub. ==== Deprecations and Breaking Changes -* Since the API Guardian dependency is no longer exported as a runtime but as a +* Since the API Guardian dependency is no longer exported as a runtime but rather as a compile-only dependency to consuming Gradle projects, Gradle builds that define their own https://docs.gradle.org/current/userguide/declaring_dependencies.html#sec:what-are-dependency-configurations[dependency configurations] may be affected. For example, if the custom configuration is used to manipulate a source set's classpath directly, dependency attributes needed for Gradle's variant-aware - dependency management are dropped and API Guardian is missing from the compile + dependency management are dropped, and API Guardian is missing from the compile classpath. In that case, the Java compiler emits warnings which -- depending on your configured options -- may cause the build to fail. The solution is to avoid manipulating a source set's classpath directly. Instead, its dependency configurations should extend @@ -71,8 +71,11 @@ on GitHub. ==== New Features and Improvements * New `junit-platform-suite-engine` module to execute declarative test suites on the JUnit - Platform. -* Additional selectors in the suite API in the `junit-platform-suite-api` module. + Platform. See <<../user-guide/index.adoc#junit-platform-suite-engine, JUnit Platform + Suite Engine>> for details. +* Additional selectors in the suite API in the `junit-platform-suite-api` module. See the + Javadoc of the `{suite-api-package}` package for a full list of supported annotations + and further details. * New `UniqueIdTrackingListener` which is a `TestExecutionListener` that tracks the unique IDs of all tests that were skipped or executed during the `TestPlan` and generates a file containing the unique IDs. The generated file can be used to rerun those tests -- @@ -90,12 +93,13 @@ on GitHub. nested container events when using the `EngineTestKit`. For example, `test(displayName("my test"))` can be used to match against a test whose display name is `my test`. -* Generating Java Flight Recorder events via the `junit-platform-jfr` module is now also - supported on Java 8 Update 262 or higher, in addition to Java 11 or later. See - <<../user-guide/index.adoc#running-tests, Flight Recorder Support>> for details. -* The `junit-platform-jfr` module now reports execution events for containers -- for +* Generating Java Flight Recorder (JFR) events via the `junit-platform-jfr` module is now + also supported on Java 8 Update 262 or higher, in addition to Java 11 or later. See + <<../user-guide/index.adoc#running-tests-listeners-flight-recorder, Flight Recorder + Support>> for details. +* The `junit-platform-jfr` module now publishes execution events for containers -- for example, test classes. -* The `junit-platform-jfr` module now reports test discovery events for the launcher and +* The `junit-platform-jfr` module now publishes test discovery events for the launcher and registered test engines. * New `ClassSource.from(URI)` static factory method for creating a `ClassSource` from a URI using the `class` scheme and optional query parameters specifying the line number @@ -153,7 +157,9 @@ on GitHub. * Test classes can now be ordered _globally_ by supplying the fully-qualified name of a class implementing the `ClassOrderer` API as the value of the new - `junit.jupiter.testclass.order.default` configuration parameter. + `junit.jupiter.testclass.order.default` configuration parameter. See + <<../user-guide/index.adoc#writing-tests-test-execution-order-classes, Class Order>> for + details. * `@Nested` test classes can be ordered _locally_ via the new `@TestClassOrder` annotation in which a `ClassOrderer` can be specified. * `@ExtendWith` may now be used to register extensions declaratively via fields or diff --git a/documentation/src/docs/asciidoc/user-guide/junit-platform-suite-engine.adoc b/documentation/src/docs/asciidoc/user-guide/junit-platform-suite-engine.adoc index f22c96a40031..18be01cd9091 100644 --- a/documentation/src/docs/asciidoc/user-guide/junit-platform-suite-engine.adoc +++ b/documentation/src/docs/asciidoc/user-guide/junit-platform-suite-engine.adoc @@ -1,25 +1,29 @@ [[junit-platform-suite-engine]] === JUnit Platform Suite Engine -The JUnit Platform supports declarative definition and execution of suites of tests from -_any_ test engine using the Junit Platform. +The JUnit Platform supports the declarative definition and execution of suites of tests +from _any_ test engine using the JUnit Platform. +[[junit-platform-suite-engine-setup]] ==== Setup -In addition to _at least one_ other test engine, you need the following artifacts and -their dependencies on the classpath. See <> for details regarding -group IDs, artifact IDs, and versions. +In addition to the `junit-platform-suite-api` and `junit-platform-suite-engine` artifacts, +you need _at least one_ other test engine and its dependencies on the classpath. See +<> for details regarding group IDs, artifact IDs, and versions. -===== Explicit Dependencies +[[junit-platform-suite-engine-setup-required-dependencies]] +===== Required Dependencies -* `junit-platform-suite-api` in _test_ scope +* `junit-platform-suite-api` in _test_ scope: artifact containing annotations needed to + configure a test suite * `junit-platform-suite-engine` in _test runtime_ scope: implementation of the - `TestEngine` API for the declarative Junit Platform - Suites + `TestEngine` API for declarative test suites -NOTE: Both dependencies are aggregated in `junit-platform-suite` which can be used in -_test_ scope. +NOTE: Both of the required dependencies are aggregated in the `junit-platform-suite` +artifact which can be declard in _test_ scope instead of declaring explicit dependencies +on `junit-platform-suite-api` and `junit-platform-suite-engine`. +[[junit-platform-suite-engine-setup-transitive-dependencies]] ===== Transitive Dependencies * `junit-platform-suite-commons` in _test_ scope @@ -28,7 +32,8 @@ _test_ scope. * `junit-platform-commons` in _test_ scope * `opentest4j` in _test_ scope -==== Test Suite +[[junit-platform-suite-engine-example]] +==== @Suite Example By annotating a class with `@Suite` it is marked as a test suite on the JUnit Platform. As seen in the following example, selector and filter annotations can then be used to @@ -40,6 +45,6 @@ include::{testDir}/example/SuiteDemo.java[tags=user_guide] ---- .Additional Configuration Options -NOTE: There are more configuration options for discovering and filtering tests than just -`@SelectPackages`. Please consult the Javadoc of the `{suite-api-package}` package for -further details. +NOTE: There are numerous configuration options for discovering and filtering tests in a +test suite. Please consult the Javadoc of the `{suite-api-package}` package for a full +list of supported annotations and further details. diff --git a/documentation/src/docs/asciidoc/user-guide/running-tests.adoc b/documentation/src/docs/asciidoc/user-guide/running-tests.adoc index ea1f7f9abc19..ca81e93082ee 100644 --- a/documentation/src/docs/asciidoc/user-guide/running-tests.adoc +++ b/documentation/src/docs/asciidoc/user-guide/running-tests.adoc @@ -640,6 +640,7 @@ to reporting (see <>). You need the following artifacts and their dependencies on the classpath. See <> for details regarding group IDs, artifact IDs, and versions. +[[running-tests-junit-platform-runner-setup-explicit-dependencies]] ===== Explicit Dependencies * `junit-platform-runner` in _test_ scope: location of the `JUnitPlatform` runner @@ -649,6 +650,7 @@ You need the following artifacts and their dependencies on the classpath. See * `junit-jupiter-engine` in _test runtime_ scope: implementation of the `TestEngine` API for JUnit Jupiter +[[running-tests-junit-platform-runner-setup-transitive-dependencies]] ===== Transitive Dependencies * `junit-platform-suite-api` in _test_ scope diff --git a/documentation/src/test/java/example/SuiteDemo.java b/documentation/src/test/java/example/SuiteDemo.java index 278b662715b8..57201559ac96 100644 --- a/documentation/src/test/java/example/SuiteDemo.java +++ b/documentation/src/test/java/example/SuiteDemo.java @@ -11,6 +11,7 @@ package example; //tag::user_guide[] +import org.junit.platform.suite.api.IncludeClassNamePatterns; import org.junit.platform.suite.api.SelectPackages; import org.junit.platform.suite.api.Suite; import org.junit.platform.suite.api.SuiteDisplayName; @@ -18,9 +19,10 @@ @Suite @SuiteDisplayName("JUnit Platform Suite Demo") @SelectPackages("example") +@IncludeClassNamePatterns(".*Tests") //end::user_guide[] @org.junit.platform.suite.api.ExcludeTags("exclude") //tag::user_guide[] -public class SuiteDemo { +class SuiteDemo { } //end::user_guide[]