From db5bd86579554b39f3c98ede7fdd2a04c43cfcec Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matthias=20B=C3=BCnger?= Date: Sun, 16 Nov 2025 11:20:40 +0100 Subject: [PATCH 1/4] Initial migration of SystemPropertyExtension --- .../asciidoc/user-guide/writing-tests.adoc | 2355 +++++++---------- .../example/SystemPropertyExtensionDemo.java | 153 ++ .../api/util/AbstractEntryBasedExtension.java | 333 +++ .../jupiter/api/util/ClearSystemProperty.java | 72 + .../jupiter/api/util/ReadsSystemProperty.java | 43 + .../api/util/RestoreSystemProperties.java | 71 + .../jupiter/api/util/SetSystemProperty.java | 80 + .../api/util/SystemPropertyExtension.java | 115 + .../util/SystemPropertyExtensionUtils.java | 62 + .../api/util/WritesSystemProperty.java | 43 + .../junit/jupiter/api/util/package-info.java | 1 + .../api/util/PropertiesAssertions.java | 210 ++ .../util/SystemPropertyExtensionTests.java | 727 +++++ 13 files changed, 2932 insertions(+), 1333 deletions(-) create mode 100644 documentation/src/test/java/example/SystemPropertyExtensionDemo.java create mode 100644 junit-jupiter-api/src/main/java/org/junit/jupiter/api/util/AbstractEntryBasedExtension.java create mode 100644 junit-jupiter-api/src/main/java/org/junit/jupiter/api/util/ClearSystemProperty.java create mode 100644 junit-jupiter-api/src/main/java/org/junit/jupiter/api/util/ReadsSystemProperty.java create mode 100644 junit-jupiter-api/src/main/java/org/junit/jupiter/api/util/RestoreSystemProperties.java create mode 100644 junit-jupiter-api/src/main/java/org/junit/jupiter/api/util/SetSystemProperty.java create mode 100644 junit-jupiter-api/src/main/java/org/junit/jupiter/api/util/SystemPropertyExtension.java create mode 100644 junit-jupiter-api/src/main/java/org/junit/jupiter/api/util/SystemPropertyExtensionUtils.java create mode 100644 junit-jupiter-api/src/main/java/org/junit/jupiter/api/util/WritesSystemProperty.java create mode 100644 jupiter-tests/src/test/java/org/junit/jupiter/api/util/PropertiesAssertions.java create mode 100644 jupiter-tests/src/test/java/org/junit/jupiter/api/util/SystemPropertyExtensionTests.java diff --git a/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc b/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc index 18eddfd55b43..35f7bb4060b4 100644 --- a/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc +++ b/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc @@ -5,9 +5,8 @@ [[writing-tests]] == Writing Tests -The following example provides a glimpse at the minimum requirements for writing a test in -JUnit Jupiter. Subsequent sections of this chapter will provide further details on all -available features. +The following example provides a glimpse at the minimum requirements for writing a test in JUnit Jupiter. +Subsequent sections of this chapter will provide further details on all available features. [source,java,indent=0] .A first test case @@ -18,136 +17,124 @@ include::{testDir}/example/MyFirstJUnitJupiterTests.java[tags=user_guide] [[writing-tests-annotations]] === Annotations -JUnit Jupiter supports the following annotations for configuring tests and extending the -framework. +JUnit Jupiter supports the following annotations for configuring tests and extending the framework. -Unless otherwise stated, all core annotations are located in the `{api-package}` package -in the `junit-jupiter-api` module. +Unless otherwise stated, all core annotations are located in the `{api-package}` package in the `junit-jupiter-api` module. -`*@Test*`:: Denotes that a method is a test method. Unlike JUnit 4's `@Test` annotation, -this annotation does not declare any attributes, since test extensions in JUnit Jupiter -operate based on their own dedicated annotations. Such methods are inherited unless they -are overridden. +`*@Test*`:: Denotes that a method is a test method. +Unlike JUnit 4's `@Test` annotation, this annotation does not declare any attributes, since test extensions in JUnit Jupiter operate based on their own dedicated annotations. +Such methods are inherited unless they are overridden. `*@ParameterizedTest*`:: Denotes that a method is a -<>. Such methods are inherited -unless they are overridden. +<>. +Such methods are inherited unless they are overridden. `*@RepeatedTest*`:: Denotes that a method is a test template for a -<>. Such methods are inherited unless they -are overridden. +<>. +Such methods are inherited unless they are overridden. `*@TestFactory*`:: Denotes that a method is a test factory for -<>. Such methods are inherited unless they are -overridden. +<>. +Such methods are inherited unless they are overridden. `*@TestTemplate*`:: Denotes that a method is a -<> designed to be invoked multiple -times depending on the number of invocation contexts returned by the registered -<>. Such methods are inherited unless they are -overridden. +<> designed to be invoked multiple times depending on the number of invocation contexts returned by the registered +<>. +Such methods are inherited unless they are overridden. `*@TestClassOrder*`:: Used to configure the <> for `@Nested` -test classes in the annotated test class. Such annotations are inherited. +test classes in the annotated test class. +Such annotations are inherited. `*@TestMethodOrder*`:: Used to configure the -<> for the -annotated test class; similar to JUnit 4's `@FixMethodOrder`. Such annotations are -inherited. +<> for the annotated test class; similar to JUnit 4's `@FixMethodOrder`. +Such annotations are inherited. `*@TestInstance*`:: Used to configure the -<> for the annotated test -class. Such annotations are inherited. +<> for the annotated test class. +Such annotations are inherited. -`*@DisplayName*`:: Declares a custom <> for the -test class or test method. Such annotations are not inherited. +`*@DisplayName*`:: Declares a custom <> for the test class or test method. +Such annotations are not inherited. `*@DisplayNameGeneration*`:: Declares a custom -<> for the test class. Such -annotations are inherited. +<> for the test class. +Such annotations are inherited. `*@BeforeEach*`:: Denotes that the annotated method should be executed _before_ *each* -`@Test`, `@RepeatedTest`, `@ParameterizedTest`, or `@TestFactory` method in the current -class; analogous to JUnit 4's `@Before`. Such methods are inherited unless they are -overridden. +`@Test`, `@RepeatedTest`, `@ParameterizedTest`, or `@TestFactory` method in the current class; analogous to JUnit 4's `@Before`. +Such methods are inherited unless they are overridden. `*@AfterEach*`:: Denotes that the annotated method should be executed _after_ *each* -`@Test`, `@RepeatedTest`, `@ParameterizedTest`, or `@TestFactory` method in the current -class; analogous to JUnit 4's `@After`. Such methods are inherited unless they are -overridden. +`@Test`, `@RepeatedTest`, `@ParameterizedTest`, or `@TestFactory` method in the current class; analogous to JUnit 4's `@After`. +Such methods are inherited unless they are overridden. `*@BeforeAll*`:: Denotes that the annotated method should be executed _before_ *all* -`@Test`, `@RepeatedTest`, `@ParameterizedTest`, and `@TestFactory` methods in the current -top-level or `@Nested` test class; analogous to JUnit 4's `@BeforeClass`. Such methods are -inherited unless they are overridden and must be `static` unless the "per-class" +`@Test`, `@RepeatedTest`, `@ParameterizedTest`, and `@TestFactory` methods in the current top-level or `@Nested` test class; analogous to JUnit 4's `@BeforeClass`. +Such methods are inherited unless they are overridden and must be `static` unless the "per-class" <> is used. `*@AfterAll*`:: Denotes that the annotated method should be executed _after_ *all* -`@Test`, `@RepeatedTest`, `@ParameterizedTest`, and `@TestFactory` methods in the current -top-level or `@Nested` test class; analogous to JUnit 4's `@AfterClass`. Such methods are -inherited unless they are overridden and must be `static` unless the "per-class" +`@Test`, `@RepeatedTest`, `@ParameterizedTest`, and `@TestFactory` methods in the current top-level or `@Nested` test class; analogous to JUnit 4's `@AfterClass`. +Such methods are inherited unless they are overridden and must be `static` unless the "per-class" <> is used. `*@ParameterizedClass*`:: Denotes that the annotated class is a -<>. Such annotations are -inherited. +<>. +Such annotations are inherited. -`*@BeforeParameterizedClassInvocation*`:: Denotes that the annotated method should be -executed once _before_ each invocation of a -<>. Such methods are inherited -unless they are overridden. +`*@BeforeParameterizedClassInvocation*`:: Denotes that the annotated method should be executed once _before_ each invocation of a +<>. +Such methods are inherited unless they are overridden. -`*@AfterParameterizedClassInvocation*`:: Denotes that the annotated method should be -executed once _after_ each invocation of a -<>. Such methods are inherited -unless they are overridden. +`*@AfterParameterizedClassInvocation*`:: Denotes that the annotated method should be executed once _after_ each invocation of a +<>. +Such methods are inherited unless they are overridden. `*@ClassTemplate*`:: Denotes that the annotated class is a -<> designed to be executed -multiple times depending on the number of invocation contexts returned by the registered -<>. Such annotations are inherited. +<> designed to be executed multiple times depending on the number of invocation contexts returned by the registered +<>. +Such annotations are inherited. `*@Nested*`:: Denotes that the annotated class is a non-static -<>. Such annotations are not inherited. +<>. +Such annotations are not inherited. `*@Tag*`:: Used to declare -<>, either at the class or -method level; analogous to test groups in TestNG or Categories in JUnit 4. Such -annotations are inherited at the class level but not at the method level. +<>, either at the class or method level; analogous to test groups in TestNG or Categories in JUnit 4. Such annotations are inherited at the class level but not at the method level. -`*@Disabled*`:: Used to <> a test class or test method; -analogous to JUnit 4's `@Ignore`. Such annotations are not inherited. +`*@Disabled*`:: Used to <> a test class or test method; analogous to JUnit 4's `@Ignore`. +Such annotations are not inherited. `*@AutoClose*`:: Denotes that the annotated field represents a resource that will be -<> after test -execution. Such fields are inherited. +<> after test execution. +Such fields are inherited. -`*@Timeout*`:: Used to fail a test, test factory, test template, or lifecycle method if -its execution exceeds a given duration. Such annotations are inherited. +`*@Timeout*`:: Used to fail a test, test factory, test template, or lifecycle method if its execution exceeds a given duration. +Such annotations are inherited. `*@TempDir*`:: Used to supply a -<> via field -injection or parameter injection in a test class constructor, lifecycle method, or test -method; located in the `org.junit.jupiter.api.io` package. Such fields are inherited. +<> via field injection or parameter injection in a test class constructor, lifecycle method, or test method; located in the `org.junit.jupiter.api.io` package. +Such fields are inherited. `*@ExtendWith*`:: Used to -<>. Such -annotations are inherited. +<>. +Such annotations are inherited. `*@RegisterExtension*`:: Used to <> via fields. Such fields are inherited. -WARNING: Some annotations may currently be _experimental_. Consult the table in +WARNING: Some annotations may currently be _experimental_. +Consult the table in <> for details. [[writing-tests-meta-annotations]] ==== Meta-Annotations and Composed Annotations -JUnit Jupiter annotations can be used as _meta-annotations_. That means that you can -define your own _composed annotation_ that will automatically _inherit_ the semantics of -its meta-annotations. +JUnit Jupiter annotations can be used as _meta-annotations_. +That means that you can define your own _composed annotation_ that will automatically _inherit_ the semantics of its meta-annotations. For example, instead of copying and pasting `@Tag("fast")` throughout your code base (see <>), you can create a custom _composed annotation_ @@ -170,16 +157,14 @@ void myFastTest() { } ---- -You can even take that one step further by introducing a custom `@FastTest` annotation -that can be used as a drop-in replacement for `@Tag("fast")` _and_ `@Test`. +You can even take that one step further by introducing a custom `@FastTest` annotation that can be used as a drop-in replacement for `@Tag("fast")` _and_ `@Test`. [source,java,indent=0] ---- include::{testDir}/example/FastTest.java[tags=user_guide] ---- -JUnit automatically recognizes the following as a `@Test` method that is tagged with -"fast". +JUnit automatically recognizes the following as a `@Test` method that is tagged with "fast". [source,java,indent=0] ---- @@ -223,44 +208,35 @@ _tests_ or, potentially (for `@TestFactory`), other _containers_. [[writing-tests-classes-and-methods]] === Test Classes and Methods -Test methods and lifecycle methods may be declared locally within the current test class, -inherited from superclasses, or inherited from interfaces (see -<>). In addition, test methods and -lifecycle methods must not be `abstract` and must not return a value (except `@TestFactory` +Test methods and lifecycle methods may be declared locally within the current test class, inherited from superclasses, or inherited from interfaces (see +<>). +In addition, test methods and lifecycle methods must not be `abstract` and must not return a value (except `@TestFactory` methods which are required to return a value). [NOTE] .Class and method visibility ==== -Test classes, test methods, and lifecycle methods are not required to be `public`, but -they must _not_ be `private`. - -It is generally recommended to omit the `public` modifier for test classes, test methods, -and lifecycle methods unless there is a technical reason for doing so – for example, when -a test class is extended by a test class in another package. Another technical reason for -making classes and methods `public` is to simplify testing on the module path when using -the Java Module System. +Test classes, test methods, and lifecycle methods are not required to be `public`, but they must _not_ be `private`. + +It is generally recommended to omit the `public` modifier for test classes, test methods, and lifecycle methods unless there is a technical reason for doing so – for example, when a test class is extended by a test class in another package. +Another technical reason for making classes and methods `public` is to simplify testing on the module path when using the Java Module System. ==== [NOTE] .Field and method inheritance ==== -Fields in test classes are inherited. For example, a `@TempDir` field from a superclass -will always be applied in a subclass. +Fields in test classes are inherited. +For example, a `@TempDir` field from a superclass will always be applied in a subclass. -Test methods and lifecycle methods are inherited unless they are overridden according to -the visibility rules of the Java language. For example, a `@Test` method from a superclass -will always be applied in a subclass unless the subclass explicitly overrides the method. -Similarly, if a package-private `@Test` method is declared in a superclass that resides in -a different package than the subclass, that `@Test` method will always be applied in the -subclass since the subclass cannot override a package-private method from a superclass in -a different package. +Test methods and lifecycle methods are inherited unless they are overridden according to the visibility rules of the Java language. +For example, a `@Test` method from a superclass will always be applied in a subclass unless the subclass explicitly overrides the method. +Similarly, if a package-private `@Test` method is declared in a superclass that resides in a different package than the subclass, that `@Test` method will always be applied in the subclass since the subclass cannot override a package-private method from a superclass in a different package. See also: <> ==== -The following test class demonstrates the use of `@Test` methods and all supported -lifecycle methods. For further information on runtime semantics, see +The following test class demonstrates the use of `@Test` methods and all supported lifecycle methods. +For further information on runtime semantics, see <> and <>. @@ -270,8 +246,7 @@ lifecycle methods. For further information on runtime semantics, see include::{testDir}/example/StandardTests.java[tags=user_guide] ---- -It is also possible to use Java `record` classes as test classes as illustrated by the -following example. +It is also possible to use Java `record` classes as test classes as illustrated by the following example. [source,java,indent=0] .A test class written as a Java record @@ -290,17 +265,14 @@ include::{kotlinTestDir}/example/KotlinCoroutinesDemo.kt[tags=user_guide] NOTE: Using suspending functions as test or lifecycle methods requires https://central.sonatype.com/artifact/org.jetbrains.kotlin/kotlin-stdlib[`kotlin-stdlib`], -https://central.sonatype.com/artifact/org.jetbrains.kotlin/kotlin-reflect[`kotlin-reflect`], -and +https://central.sonatype.com/artifact/org.jetbrains.kotlin/kotlin-reflect[`kotlin-reflect`], and https://central.sonatype.com/artifact/org.jetbrains.kotlinx/kotlinx-coroutines-core[`kotlinx-coroutines-core`] to be present on the classpath or module path. [[writing-tests-display-names]] === Display Names -Test classes and test methods can declare custom display names via `@DisplayName` -- with -spaces, special characters, and even emojis -- that will be displayed in test reports and -by test runners and IDEs. +Test classes and test methods can declare custom display names via `@DisplayName` -- with spaces, special characters, and even emojis -- that will be displayed in test reports and by test runners and IDEs. [source,java,indent=0] ---- @@ -309,8 +281,8 @@ include::{testDir}/example/DisplayNameDemo.java[tags=user_guide] [NOTE] ==== -Control characters in text-based arguments in display names for parameterized tests are -escaped by default. See <> +Control characters in text-based arguments in display names for parameterized tests are escaped by default. +See <> for details. Any remaining ISO control characters in a display name will be replaced as follows. @@ -339,8 +311,8 @@ Any remaining ISO control characters in a display name will be replaced as follo JUnit Jupiter supports custom display name generators that can be configured via the `@DisplayNameGeneration` annotation. -Generators can be created by implementing the `DisplayNameGenerator` API. The following -table lists the default display name generators available in Jupiter. +Generators can be created by implementing the `DisplayNameGenerator` API. +The following table lists the default display name generators available in Jupiter. [cols="20,80"] |=== @@ -352,12 +324,10 @@ table lists the default display name generators available in Jupiter. | `IndicativeSentences` | Generates complete sentences by concatenating the names of the test and the enclosing classes. |=== -NOTE: Values provided via `@DisplayName` annotations always take precedence over display -names generated by a `DisplayNameGenerator`. +NOTE: Values provided via `@DisplayName` annotations always take precedence over display names generated by a `DisplayNameGenerator`. ====== -The following example demonstrates the use of the `ReplaceUnderscores` display name -generator. +The following example demonstrates the use of the `ReplaceUnderscores` display name generator. [source,java,indent=0] ---- @@ -376,9 +346,7 @@ A year is not supported ✔ ====== ====== -With the `IndicativeSentences` display name generator, you can customize the separator and -the underlying generator by using `@IndicativeSentencesGeneration` as shown in the -following example. +With the `IndicativeSentences` display name generator, you can customize the separator and the underlying generator by using `@IndicativeSentencesGeneration` as shown in the following example. [source,java,indent=0] ---- @@ -418,22 +386,18 @@ A year is a leap year ✔ ``` ====== - [[writing-tests-display-name-generator-default]] ==== Setting the Default Display Name Generator You can use the `junit.jupiter.displayname.generator.default` -<> to specify the fully qualified -class name of the `DisplayNameGenerator` you would like to use by default. Just like for -display name generators configured via the `@DisplayNameGeneration` annotation, the -supplied class has to implement the `DisplayNameGenerator` interface. The default display -name generator will be used for all tests unless the `@DisplayNameGeneration` annotation -is present on an enclosing test class or test interface. Values provided via +<> to specify the fully qualified class name of the `DisplayNameGenerator` you would like to use by default. +Just like for display name generators configured via the `@DisplayNameGeneration` annotation, the supplied class has to implement the `DisplayNameGenerator` interface. +The default display name generator will be used for all tests unless the `@DisplayNameGeneration` annotation is present on an enclosing test class or test interface. +Values provided via `@DisplayName` annotations always take precedence over display names generated by a `DisplayNameGenerator`. -For example, to use the `ReplaceUnderscores` display name generator by default, you should -set the configuration parameter to the corresponding fully qualified class name (e.g., in +For example, to use the `ReplaceUnderscores` display name generator by default, you should set the configuration parameter to the corresponding fully qualified class name (e.g., in `src/test/resources/junit-platform.properties`): [source,properties,indent=0] @@ -446,29 +410,24 @@ Similarly, you can specify the fully qualified name of any custom class that imp `DisplayNameGenerator`. [[writing-tests-display-name-generator-precedence-rules]] -In summary, the display name for a test class or method is determined according to the -following precedence rules: +In summary, the display name for a test class or method is determined according to the following precedence rules: 1. value of the `@DisplayName` annotation, if present 2. by calling the `DisplayNameGenerator` specified in the `@DisplayNameGeneration` - annotation, if present -3. by calling the default `DisplayNameGenerator` configured via the configuration - parameter, if present +annotation, if present +3. by calling the default `DisplayNameGenerator` configured via the configuration parameter, if present 4. by calling `org.junit.jupiter.api.DisplayNameGenerator.Standard` [[writing-tests-assertions]] === Assertions -JUnit Jupiter comes with many of the assertion methods that JUnit 4 has and adds a few -that lend themselves well to being used with Java lambdas. All JUnit Jupiter assertions -are `static` methods in the `{Assertions}` class. +JUnit Jupiter comes with many of the assertion methods that JUnit 4 has and adds a few that lend themselves well to being used with Java lambdas. +All JUnit Jupiter assertions are `static` methods in the `{Assertions}` class. -Assertion methods optionally accept the assertion message as their third parameter, which -can be either a `String` or a `Supplier`. +Assertion methods optionally accept the assertion message as their third parameter, which can be either a `String` or a `Supplier`. -When using a `Supplier` (e.g., a lambda expression), the message is evaluated -lazily. This can provide a performance benefit, especially if message construction is -complex or time-consuming, as it is only evaluated when the assertion fails. +When using a `Supplier` (e.g., a lambda expression), the message is evaluated lazily. +This can provide a performance benefit, especially if message construction is complex or time-consuming, as it is only evaluated when the assertion fails. [source,java,indent=0] ---- @@ -479,19 +438,14 @@ include::{testDir}/example/AssertionsDemo.java[tags=user_guide] [WARNING] .Preemptive Timeouts with `assertTimeoutPreemptively()` ==== -The various `assertTimeoutPreemptively()` methods in the `Assertions` class execute -the provided `executable` or `supplier` in a different thread than that of the calling -code. This behavior can lead to undesirable side effects if the code that is executed -within the `executable` or `supplier` relies on `java.lang.ThreadLocal` storage. +The various `assertTimeoutPreemptively()` methods in the `Assertions` class execute the provided `executable` or `supplier` in a different thread than that of the calling code. +This behavior can lead to undesirable side effects if the code that is executed within the `executable` or `supplier` relies on `java.lang.ThreadLocal` storage. One common example of this is the transactional testing support in the Spring Framework. -Specifically, Spring's testing support binds transaction state to the current thread (via -a `ThreadLocal`) before a test method is invoked. Consequently, if an `executable` or -`supplier` provided to `assertTimeoutPreemptively()` invokes Spring-managed components -that participate in transactions, any actions taken by those components will not be rolled -back with the test-managed transaction. On the contrary, such actions will be committed to -the persistent store (e.g., relational database) even though the test-managed transaction -is rolled back. +Specifically, Spring's testing support binds transaction state to the current thread (via a `ThreadLocal`) before a test method is invoked. +Consequently, if an `executable` or +`supplier` provided to `assertTimeoutPreemptively()` invokes Spring-managed components that participate in transactions, any actions taken by those components will not be rolled back with the test-managed transaction. +On the contrary, such actions will be committed to the persistent store (e.g., relational database) even though the test-managed transaction is rolled back. Similar side effects may be encountered with other frameworks that rely on `ThreadLocal` storage. @@ -500,9 +454,8 @@ Similar side effects may be encountered with other frameworks that rely on [[writing-tests-assertions-kotlin]] ==== Kotlin Assertion Support -JUnit Jupiter also comes with a few assertion methods that lend themselves well to being -used in https://kotlinlang.org/[Kotlin]. All JUnit Jupiter Kotlin assertions are top-level -functions in the `org.junit.jupiter.api` package. +JUnit Jupiter also comes with a few assertion methods that lend themselves well to being used in https://kotlinlang.org/[Kotlin]. +All JUnit Jupiter Kotlin assertions are top-level functions in the `org.junit.jupiter.api` package. [source,kotlin,indent=0] ---- @@ -512,15 +465,12 @@ include::{kotlinTestDir}/example/KotlinAssertionsDemo.kt[tags=user_guide] [[writing-tests-assertions-third-party]] ==== Third-party Assertion Libraries -Even though the assertion facilities provided by JUnit Jupiter are sufficient for many -testing scenarios, there are times when more power and additional functionality are -desired or required. In such cases, the JUnit team recommends the use of third-party -assertion libraries such as {AssertJ}, {Hamcrest}, {Truth}, etc. Developers are therefore -free to use the assertion library of their choice. +Even though the assertion facilities provided by JUnit Jupiter are sufficient for many testing scenarios, there are times when more power and additional functionality are desired or required. +In such cases, the JUnit team recommends the use of third-party assertion libraries such as {AssertJ}, {Hamcrest}, {Truth}, etc. +Developers are therefore free to use the assertion library of their choice. -For example, the following demonstrates how to use the `assertThat()` support from AssertJ -in a JUnit Jupiter test. As long as the AssertJ library has been added to the classpath, -you can statically import methods such as `assertThat()`, `assertThatException()`, etc. +For example, the following demonstrates how to use the `assertThat()` support from AssertJ in a JUnit Jupiter test. +As long as the AssertJ library has been added to the classpath, you can statically import methods such as `assertThat()`, `assertThatException()`, etc. from `org.assertj.core.api.Assertions` and then use them in tests like in the `assertWithAssertJ()` method below. @@ -532,9 +482,7 @@ include::{testDir}/example/AssertJAssertionsDemo.java[tags=user_guide] [TIP] .Excluding Jupiter’s Assertions From a Project’s Classpath ==== -If you would like to enforce that all your tests use a certain third-party assertion -library instead of Jupiter's, you can set up a rule using {Checkstyle} or another static -analysis tool that fails the build if Jupiter's `Assertions` class is used. +If you would like to enforce that all your tests use a certain third-party assertion library instead of Jupiter's, you can set up a rule using {Checkstyle} or another static analysis tool that fails the build if Jupiter's `Assertions` class is used. [source,xml] ---- @@ -558,19 +506,13 @@ analysis tool that fails the build if Jupiter's `Assertions` class is used. [[writing-tests-assumptions]] === Assumptions -Assumptions are typically used whenever it does not make sense to continue execution of a -given test — for example, if the test depends on something that does not exist in the -current runtime environment. +Assumptions are typically used whenever it does not make sense to continue execution of a given test — for example, if the test depends on something that does not exist in the current runtime environment. -* When an assumption is valid, the assumption method does not throw an exception, and - execution of the test continues as usual. +* When an assumption is valid, the assumption method does not throw an exception, and execution of the test continues as usual. * When an assumption is invalid, the assumption method throws an exception of type - `org.opentest4j.TestAbortedException` to signal that the test should be aborted instead - of marked as a failure. +`org.opentest4j.TestAbortedException` to signal that the test should be aborted instead of marked as a failure. -JUnit Jupiter comes with a subset of the _assumption_ methods that JUnit 4 provides and -adds a few that lend themselves well to being used with Java lambda expressions and method -references. +JUnit Jupiter comes with a subset of the _assumption_ methods that JUnit 4 provides and adds a few that lend themselves well to being used with Java lambda expressions and method references. All JUnit Jupiter assumptions are static methods in the `{Assumptions}` class. @@ -579,76 +521,66 @@ All JUnit Jupiter assumptions are static methods in the `{Assumptions}` class. include::{testDir}/example/AssumptionsDemo.java[tags=user_guide] ---- -NOTE: It is also possible to use methods from JUnit 4's `org.junit.Assume` class for -assumptions. Specifically, JUnit Jupiter supports JUnit 4's `AssumptionViolatedException` +NOTE: It is also possible to use methods from JUnit 4's `org.junit.Assume` class for assumptions. +Specifically, JUnit Jupiter supports JUnit 4's `AssumptionViolatedException` to signal that a test should be aborted instead of marked as a failure. TIP: If you use AssertJ for assertions, you may also wish to use AssertJ for assumptions. To do so, you can statically import the `assumeThat()` method from -`org.assertj.core.api.Assumptions` and then use AssertJ's fluent API to specify your -assumptions. +`org.assertj.core.api.Assumptions` and then use AssertJ's fluent API to specify your assumptions. [[writing-tests-exceptions]] === Exception Handling -JUnit Jupiter provides robust support for handling test exceptions. This includes the -built-in mechanisms for managing test failures due to exceptions, the role of exceptions -in implementing assertions and assumptions, and how to specifically assert non-throwing -conditions in code. +JUnit Jupiter provides robust support for handling test exceptions. +This includes the built-in mechanisms for managing test failures due to exceptions, the role of exceptions in implementing assertions and assumptions, and how to specifically assert non-throwing conditions in code. [[writing-tests-exceptions-uncaught]] ==== Uncaught Exceptions -In JUnit Jupiter, if an exception is thrown from a test method, a lifecycle method, or an -extension and not caught within that test method, lifecycle method, or extension, the -framework will mark the test or test class as failed. +In JUnit Jupiter, if an exception is thrown from a test method, a lifecycle method, or an extension and not caught within that test method, lifecycle method, or extension, the framework will mark the test or test class as failed. [TIP] ==== Failed assumptions deviate from this general rule. -In contrast to failed assertions, failed assumptions do not result in a test failure; -rather, a failed assumption results in a test being aborted. +In contrast to failed assertions, failed assumptions do not result in a test failure; rather, a failed assumption results in a test being aborted. See <> for further details and examples. ==== In the following example, the `failsDueToUncaughtException()` method throws an -`ArithmeticException`. Since the exception is not caught within the test method, JUnit -Jupiter will mark the test as failed. +`ArithmeticException`. +Since the exception is not caught within the test method, JUnit Jupiter will mark the test as failed. [source,java,indent=0] ---- include::{testDir}/example/exception/UncaughtExceptionHandlingDemo.java[tags=user_guide] ---- -NOTE: It's important to note that specifying a `throws` clause in the test method has -no effect on the outcome of the test. JUnit Jupiter does not interpret a `throws` clause -as an expectation or assertion about what exceptions the test method should throw. A test -fails only if an exception is thrown unexpectedly or if an assertion fails. +NOTE: It's important to note that specifying a `throws` clause in the test method has no effect on the outcome of the test. +JUnit Jupiter does not interpret a `throws` clause as an expectation or assertion about what exceptions the test method should throw. +A test fails only if an exception is thrown unexpectedly or if an assertion fails. [[writing-tests-exceptions-failed-assertions]] ==== Failed Assertions -Assertions in JUnit Jupiter are implemented using exceptions. The framework provides a set -of assertion methods in the `org.junit.jupiter.api.Assertions` class, which throw -`AssertionError` when an assertion fails. This mechanism is a core aspect of how JUnit -handles assertion failures as exceptions. See the <> section for -further information about JUnit Jupiter's assertion support. +Assertions in JUnit Jupiter are implemented using exceptions. +The framework provides a set of assertion methods in the `org.junit.jupiter.api.Assertions` class, which throw +`AssertionError` when an assertion fails. +This mechanism is a core aspect of how JUnit handles assertion failures as exceptions. +See the <> section for further information about JUnit Jupiter's assertion support. -NOTE: Third-party assertion libraries may choose to throw an `AssertionError` to signal a -failed assertion; however, they may also choose to throw different types of exceptions to -signal failures. See also: <>. +NOTE: Third-party assertion libraries may choose to throw an `AssertionError` to signal a failed assertion; however, they may also choose to throw different types of exceptions to signal failures. +See also: <>. -TIP: JUnit Jupiter itself does not differentiate between failed assertions -(`AssertionError`) and other types of exceptions. All uncaught exceptions lead to a test -failure. However, Integrated Development Environments (IDEs) and other tools may -distinguish between these two types of failures by checking whether the thrown exception -is an instance of `AssertionError`. +TIP: JUnit Jupiter itself does not differentiate between failed assertions (`AssertionError`) and other types of exceptions. +All uncaught exceptions lead to a test failure. +However, Integrated Development Environments (IDEs) and other tools may distinguish between these two types of failures by checking whether the thrown exception is an instance of `AssertionError`. In the following example, the `failsDueToUncaughtAssertionError()` method throws an -`AssertionError`. Since the exception is not caught within the test method, JUnit Jupiter -will mark the test as failed. +`AssertionError`. +Since the exception is not caught within the test method, JUnit Jupiter will mark the test as failed. [source,java,indent=0] ---- @@ -658,19 +590,16 @@ include::{testDir}/example/exception/FailedAssertionDemo.java[tags=user_guide] [[writing-tests-exceptions-expected]] ==== Asserting Expected Exceptions -JUnit Jupiter offers specialized assertions for testing that specific exceptions are -thrown under expected conditions. The `assertThrows()` and `assertThrowsExactly()` -assertions are critical tools for validating that your code responds correctly to error -conditions by throwing the appropriate exceptions. +JUnit Jupiter offers specialized assertions for testing that specific exceptions are thrown under expected conditions. +The `assertThrows()` and `assertThrowsExactly()` +assertions are critical tools for validating that your code responds correctly to error conditions by throwing the appropriate exceptions. [[writing-tests-exceptions-expected-assertThrows]] ===== Using `assertThrows()` -The `assertThrows()` method is used to verify that a particular type of exception is -thrown during the execution of a provided executable block. It not only checks for the -type of the thrown exception but also its subclasses, making it suitable for more -generalized exception handling tests. The `assertThrows()` assertion method returns the -thrown exception object to allow performing additional assertions on it. +The `assertThrows()` method is used to verify that a particular type of exception is thrown during the execution of a provided executable block. +It not only checks for the type of the thrown exception but also its subclasses, making it suitable for more generalized exception handling tests. +The `assertThrows()` assertion method returns the thrown exception object to allow performing additional assertions on it. [source,java,indent=0] ---- @@ -680,11 +609,9 @@ include::{testDir}/example/exception/ExceptionAssertionDemo.java[tags=user_guide [[writing-tests-exceptions-expected-assertThrowsExactly]] ===== Using `assertThrowsExactly()` -The `assertThrowsExactly()` method is used when you need to assert that the exception -thrown is exactly of a specific type, not allowing for subclasses of the expected -exception type. This is useful when precise exception handling behavior needs to be -validated. Similar to `assertThrows()`, the `assertThrowsExactly()` assertion method also -returns the thrown exception object to allow performing additional assertions on it. +The `assertThrowsExactly()` method is used when you need to assert that the exception thrown is exactly of a specific type, not allowing for subclasses of the expected exception type. +This is useful when precise exception handling behavior needs to be validated. +Similar to `assertThrows()`, the `assertThrowsExactly()` assertion method also returns the thrown exception object to allow performing additional assertions on it. [source,java,indent=0] ---- @@ -694,19 +621,19 @@ include::{testDir}/example/exception/ExceptionAssertionExactDemo.java[tags=user_ [[writing-tests-exceptions-not-expected]] ==== Asserting That no Exception is Expected -Although any exception thrown from a test method will cause the test to fail, there are -certain use cases where it can be beneficial to explicitly assert that an exception is -_not_ thrown for a given code block within a test method. The `assertDoesNotThrow()` -assertion can be used when you want to verify that a particular piece of code does not -throw any exceptions. +Although any exception thrown from a test method will cause the test to fail, there are certain use cases where it can be beneficial to explicitly assert that an exception is +_not_ thrown for a given code block within a test method. +The `assertDoesNotThrow()` +assertion can be used when you want to verify that a particular piece of code does not throw any exceptions. [source,java,indent=0] ---- include::{testDir}/example/exception/AssertDoesNotThrowExceptionDemo.java[tags=user_guide] ---- -NOTE: Third-party assertion libraries often provide similar support. For example, AssertJ -has `assertThatNoException().isThrownBy(() -> ...)`. See also: +NOTE: Third-party assertion libraries often provide similar support. +For example, AssertJ has `assertThatNoException().isThrownBy(() -> ...)`. +See also: <>. [[writing-tests-disabling]] @@ -717,14 +644,10 @@ annotation, via one of the annotations discussed in <>, or via a custom <>. -When `@Disabled` is applied at the class level, all test methods within that class are -automatically disabled as well. +When `@Disabled` is applied at the class level, all test methods within that class are automatically disabled as well. -If a test method is disabled via `@Disabled`, that prevents execution of the test method -and method-level lifecycle callbacks such as `@BeforeEach` methods, `@AfterEach` methods, -and corresponding extension APIs. However, that does not prevent the test class from being -instantiated, and it does not prevent the execution of class-level lifecycle callbacks -such as `@BeforeAll` methods, `@AfterAll` methods, and corresponding extension APIs. +If a test method is disabled via `@Disabled`, that prevents execution of the test method and method-level lifecycle callbacks such as `@BeforeEach` methods, `@AfterEach` methods, and corresponding extension APIs. +However, that does not prevent the test class from being instantiated, and it does not prevent the execution of class-level lifecycle callbacks such as `@BeforeAll` methods, `@AfterAll` methods, and corresponding extension APIs. Here's a `@Disabled` test class. @@ -742,81 +665,62 @@ include::{testDir}/example/DisabledTestsDemo.java[tags=user_guide] [TIP] ==== -`@Disabled` may be declared without providing a _reason_; however, the JUnit team -recommends that developers provide a short explanation for why a test class or test -method has been disabled. Consequently, the above examples both show the use of a reason --- for example, `@Disabled("Disabled until bug #42 has been resolved")`. Some development -teams even require the presence of issue tracking numbers in the _reason_ for automated -traceability, etc. +`@Disabled` may be declared without providing a _reason_; however, the JUnit team recommends that developers provide a short explanation for why a test class or test method has been disabled. +Consequently, the above examples both show the use of a reason +-- for example, `@Disabled("Disabled until bug #42 has been resolved")`. +Some development teams even require the presence of issue tracking numbers in the _reason_ for automated traceability, etc. ==== [NOTE] ==== -`@Disabled` is not `@Inherited`. Consequently, if you wish to disable a class whose -superclass is `@Disabled`, you must redeclare `@Disabled` on the subclass. +`@Disabled` is not `@Inherited`. +Consequently, if you wish to disable a class whose superclass is `@Disabled`, you must redeclare `@Disabled` on the subclass. ==== - [[writing-tests-conditional-execution]] === Conditional Test Execution -The <> extension API in JUnit Jupiter allows -developers to either _enable_ or _disable_ a test class or test method based on certain -conditions _programmatically_. The simplest example of such a condition is the built-in +The <> extension API in JUnit Jupiter allows developers to either _enable_ or _disable_ a test class or test method based on certain conditions _programmatically_. +The simplest example of such a condition is the built-in `{DisabledCondition}` which supports the `{Disabled}` annotation (see <>). -In addition to `@Disabled`, JUnit Jupiter also supports several other annotation-based -conditions in the `org.junit.jupiter.api.condition` package that allow developers to -enable or disable test classes and test methods _declaratively_. If you wish to provide -details about why they might be disabled, every annotation associated with these built-in -conditions has a `disabledReason` attribute available for that purpose. - -When multiple `ExecutionCondition` extensions are registered, a test class or test method -is disabled as soon as one of the conditions returns _disabled_. If a test class is -disabled, all test methods within that class are automatically disabled as well. If a test -method is disabled, that prevents execution of the test method and method-level lifecycle -callbacks such as `@BeforeEach` methods, `@AfterEach` methods, and corresponding extension -APIs. However, that does not prevent the test class from being instantiated, and it does -not prevent the execution of class-level lifecycle callbacks such as `@BeforeAll` methods, +In addition to `@Disabled`, JUnit Jupiter also supports several other annotation-based conditions in the `org.junit.jupiter.api.condition` package that allow developers to enable or disable test classes and test methods _declaratively_. +If you wish to provide details about why they might be disabled, every annotation associated with these built-in conditions has a `disabledReason` attribute available for that purpose. + +When multiple `ExecutionCondition` extensions are registered, a test class or test method is disabled as soon as one of the conditions returns _disabled_. +If a test class is disabled, all test methods within that class are automatically disabled as well. +If a test method is disabled, that prevents execution of the test method and method-level lifecycle callbacks such as `@BeforeEach` methods, `@AfterEach` methods, and corresponding extension APIs. +However, that does not prevent the test class from being instantiated, and it does not prevent the execution of class-level lifecycle callbacks such as `@BeforeAll` methods, `@AfterAll` methods, and corresponding extension APIs. -See <> and the following sections for -details. +See <> and the following sections for details. [TIP] .Composed Annotations ==== -Note that any of the _conditional_ annotations listed in the following sections may also -be used as a meta-annotation in order to create a custom _composed annotation_. For -example, the `@TestOnMac` annotation in the -<> shows how you can -combine `@Test` and `@EnabledOnOs` in a single, reusable annotation. +Note that any of the _conditional_ annotations listed in the following sections may also be used as a meta-annotation in order to create a custom _composed annotation_. +For example, the `@TestOnMac` annotation in the +<> shows how you can combine `@Test` and `@EnabledOnOs` in a single, reusable annotation. ==== [NOTE] ==== -_Conditional_ annotations in JUnit Jupiter are not `@Inherited`. Consequently, if you wish -to apply the same semantics to subclasses, each conditional annotation must be redeclared -on each subclass. +_Conditional_ annotations in JUnit Jupiter are not `@Inherited`. +Consequently, if you wish to apply the same semantics to subclasses, each conditional annotation must be redeclared on each subclass. ==== [WARNING] ==== -Unless otherwise stated, each of the _conditional_ annotations listed in the following -sections can only be declared once on a given test interface, test class, or test method. -If a conditional annotation is directly present, indirectly present, or meta-present -multiple times on a given element, only the first such annotation discovered by JUnit will -be used; any additional declarations will be silently ignored. Note, however, that each -conditional annotation may be used in conjunction with other conditional annotations in -the `org.junit.jupiter.api.condition` package. +Unless otherwise stated, each of the _conditional_ annotations listed in the following sections can only be declared once on a given test interface, test class, or test method. +If a conditional annotation is directly present, indirectly present, or meta-present multiple times on a given element, only the first such annotation discovered by JUnit will be used; any additional declarations will be silently ignored. +Note, however, that each conditional annotation may be used in conjunction with other conditional annotations in the `org.junit.jupiter.api.condition` package. ==== [[writing-tests-conditional-execution-os]] ==== Operating System and Architecture Conditions -A container or test may be enabled or disabled on a particular operating system, -architecture, or combination of both via the `{EnabledOnOs}` and `{DisabledOnOs}` +A container or test may be enabled or disabled on a particular operating system, architecture, or combination of both via the `{EnabledOnOs}` and `{DisabledOnOs}` annotations. [[writing-tests-conditional-execution-os-demo]] @@ -836,31 +740,27 @@ include::{testDir}/example/ConditionalTestExecutionDemo.java[tags=user_guide_arc [[writing-tests-conditional-execution-jre]] ==== Java Runtime Environment Conditions -A container or test may be enabled or disabled on particular versions of the Java Runtime -Environment (JRE) via the `{EnabledOnJre}` and `{DisabledOnJre}` annotations or on a -particular range of versions of the JRE via the `{EnabledForJreRange}` and -`{DisabledForJreRange}` annotations. The range effectively defaults to `JRE.JAVA_8` as the -lower bound and `JRE.OTHER` as the upper bound, which allows usage of half open ranges. +A container or test may be enabled or disabled on particular versions of the Java Runtime Environment (JRE) via the `{EnabledOnJre}` and `{DisabledOnJre}` annotations or on a particular range of versions of the JRE via the `{EnabledForJreRange}` and +`{DisabledForJreRange}` annotations. +The range effectively defaults to `JRE.JAVA_8` as the lower bound and `JRE.OTHER` as the upper bound, which allows usage of half open ranges. -The following listing demonstrates the use of these annotations with predefined {JRE} enum -constants. +The following listing demonstrates the use of these annotations with predefined {JRE} enum constants. [source,java,indent=0] ---- include::{testDir}/example/ConditionalTestExecutionDemo.java[tags=user_guide_jre] ---- -Since the enum constants defined in {JRE} are static for any given JUnit release, you -might find that you need to configure a Java version that is not supported by the `JRE` -enum. For example, when JUnit Jupiter 5.12 was released the `JRE` enum defined `JAVA_25` -as the highest supported Java version. However, you may wish to run your tests against -later versions of Java. To support such use cases, you can specify arbitrary Java versions -via the `versions` attributes in `@EnabledOnJre` and `@DisabledOnJre` and via the +Since the enum constants defined in {JRE} are static for any given JUnit release, you might find that you need to configure a Java version that is not supported by the `JRE` +enum. +For example, when JUnit Jupiter 5.12 was released the `JRE` enum defined `JAVA_25` +as the highest supported Java version. +However, you may wish to run your tests against later versions of Java. +To support such use cases, you can specify arbitrary Java versions via the `versions` attributes in `@EnabledOnJre` and `@DisabledOnJre` and via the `minVersion` and `maxVersion` attributes in `@EnabledForJreRange` and `@DisabledForJreRange`. -The following listing demonstrates the use of these annotations with arbitrary Java -versions. +The following listing demonstrates the use of these annotations with arbitrary Java versions. [source,java,indent=0] ---- @@ -872,9 +772,8 @@ include::{testDir}/example/ConditionalTestExecutionDemo.java[tags=user_guide_jre A container or test may be enabled or disabled within a https://www.graalvm.org/reference-manual/native-image/[GraalVM native image] via the -`{EnabledInNativeImage}` and `{DisabledInNativeImage}` annotations. These annotations are -typically used when running tests within a native image using the Gradle and Maven -plug-ins from the GraalVM https://graalvm.github.io/native-build-tools/latest/[Native +`{EnabledInNativeImage}` and `{DisabledInNativeImage}` annotations. +These annotations are typically used when running tests within a native image using the Gradle and Maven plug-ins from the GraalVM https://graalvm.github.io/native-build-tools/latest/[Native Build Tools] project. [source,java,indent=0] @@ -885,10 +784,9 @@ include::{testDir}/example/ConditionalTestExecutionDemo.java[tags=user_guide_nat [[writing-tests-conditional-execution-system-properties]] ==== System Property Conditions -A container or test may be enabled or disabled based on the value of the `named` JVM -system property via the `{EnabledIfSystemProperty}` and `{DisabledIfSystemProperty}` -annotations. The value supplied via the `matches` attribute will be interpreted as a -regular expression. +A container or test may be enabled or disabled based on the value of the `named` JVM system property via the `{EnabledIfSystemProperty}` and `{DisabledIfSystemProperty}` +annotations. +The value supplied via the `matches` attribute will be interpreted as a regular expression. [source,java,indent=0] ---- @@ -898,9 +796,8 @@ include::{testDir}/example/ConditionalTestExecutionDemo.java[tags=user_guide_sys [TIP] ==== `{EnabledIfSystemProperty}` and `{DisabledIfSystemProperty}` are _repeatable annotations_. -Consequently, these annotations may be declared multiple times on a test interface, test -class, or test method. Specifically, these annotations will be found if they are directly -present, indirectly present, or meta-present on a given element. +Consequently, these annotations may be declared multiple times on a test interface, test class, or test method. +Specifically, these annotations will be found if they are directly present, indirectly present, or meta-present on a given element. ==== [[writing-tests-conditional-execution-environment-variables]] @@ -908,8 +805,8 @@ present, indirectly present, or meta-present on a given element. A container or test may be enabled or disabled based on the value of the `named` environment variable from the underlying operating system via the -`{EnabledIfEnvironmentVariable}` and `{DisabledIfEnvironmentVariable}` annotations. The -value supplied via the `matches` attribute will be interpreted as a regular expression. +`{EnabledIfEnvironmentVariable}` and `{DisabledIfEnvironmentVariable}` annotations. +The value supplied via the `matches` attribute will be interpreted as a regular expression. [source,java,indent=0] ---- @@ -918,18 +815,16 @@ include::{testDir}/example/ConditionalTestExecutionDemo.java[tags=user_guide_env [TIP] ==== -`{EnabledIfEnvironmentVariable}` and `{DisabledIfEnvironmentVariable}` are _repeatable -annotations_. Consequently, these annotations may be declared multiple times on a test -interface, test class, or test method. Specifically, these annotations will be found if -they are directly present, indirectly present, or meta-present on a given element. +`{EnabledIfEnvironmentVariable}` and `{DisabledIfEnvironmentVariable}` are _repeatable annotations_. +Consequently, these annotations may be declared multiple times on a test interface, test class, or test method. +Specifically, these annotations will be found if they are directly present, indirectly present, or meta-present on a given element. ==== [[writing-tests-conditional-execution-custom]] ==== Custom Conditions -As an alternative to implementing an <>, a -container or test may be enabled or disabled based on a _condition method_ configured via -the `{EnabledIf}` and `{DisabledIf}` annotations. A condition method must have a `boolean` +As an alternative to implementing an <>, a container or test may be enabled or disabled based on a _condition method_ configured via the `{EnabledIf}` and `{DisabledIf}` annotations. +A condition method must have a `boolean` return type and may accept either no arguments or a single `ExtensionContext` argument. The following test class demonstrates how to configure a local method named @@ -940,9 +835,8 @@ The following test class demonstrates how to configure a local method named include::{testDir}/example/ConditionalTestExecutionDemo.java[tags=user_guide_custom] ---- -Alternatively, the condition method can be located outside the test class. In this case, -it must be referenced by its _fully qualified name_ as demonstrated in the following -example. +Alternatively, the condition method can be located outside the test class. +In this case, it must be referenced by its _fully qualified name_ as demonstrated in the following example. [source,java,indent=0] ---- @@ -957,22 +851,19 @@ There are several cases where a condition method would need to be `static`: - when `@EnabledIf` or `@DisabledIf` is used at class level - when `@EnabledIf` or `@DisabledIf` is used on a `@ParameterizedTest` or a - `@TestTemplate` method +`@TestTemplate` method - when the condition method is located in an external class -In any other case, you can use either static methods or instance methods as condition -methods. +In any other case, you can use either static methods or instance methods as condition methods. ==== [TIP] ==== -It is often the case that you can use an existing static method in a utility class as a -custom condition. +It is often the case that you can use an existing static method in a utility class as a custom condition. For example, `java.awt.GraphicsEnvironment` provides a `public static boolean isHeadless()` -method that can be used to determine if the current environment does not support a -graphical display. Thus, if you have a test that depends on graphical support you can -disable it when such support is unavailable as follows. +method that can be used to determine if the current environment does not support a graphical display. +Thus, if you have a test that depends on graphical support you can disable it when such support is unavailable as follows. [source,java,indent=0] ---- @@ -984,62 +875,48 @@ disable it when such support is unavailable as follows. [[writing-tests-tagging-and-filtering]] === Tagging and Filtering -Test classes and methods can be tagged via the `@Tag` annotation. Those tags can later be -used to filter <>. Please refer to the -<> section for more information about tag support in the JUnit -Platform. +Test classes and methods can be tagged via the `@Tag` annotation. +Those tags can later be used to filter <>. +Please refer to the +<> section for more information about tag support in the JUnit Platform. [source,java,indent=0] ---- include::{testDir}/example/TaggingDemo.java[tags=user_guide] ---- -TIP: See <> for examples demonstrating how to create -custom annotations for tags. +TIP: See <> for examples demonstrating how to create custom annotations for tags. [[writing-tests-test-execution-order]] === Test Execution Order -By default, test classes and methods will be ordered using an algorithm that is -deterministic but intentionally nonobvious. This ensures that subsequent runs of a test -suite execute test classes and test methods in the same order, thereby allowing for -repeatable builds. +By default, test classes and methods will be ordered using an algorithm that is deterministic but intentionally nonobvious. +This ensures that subsequent runs of a test suite execute test classes and test methods in the same order, thereby allowing for repeatable builds. NOTE: See <> for a definition of _test method_ and _test class_. [[writing-tests-test-execution-order-methods]] ==== Method Order -Although true _unit tests_ typically should not rely on the order in which they are -executed, there are times when it is necessary to enforce a specific test method execution -order -- for example, when writing _integration tests_ or _functional tests_ where the -sequence of the tests is important, especially in conjunction with +Although true _unit tests_ typically should not rely on the order in which they are executed, there are times when it is necessary to enforce a specific test method execution order -- for example, when writing _integration tests_ or _functional tests_ where the sequence of the tests is important, especially in conjunction with `@TestInstance(Lifecycle.PER_CLASS)`. -To control the order in which test methods are executed, annotate your test class or test -interface with `{TestMethodOrder}` and specify the desired `{MethodOrderer}` -implementation. You can implement your own custom `MethodOrderer` or use one of the -following built-in `MethodOrderer` implementations. - -* `{MethodOrderer_DisplayName}`: sorts test methods _alphanumerically_ based on their - display names (see <>) -* `{MethodOrderer_MethodName}`: sorts test methods _alphanumerically_ based on their names - and formal parameter lists -* `{MethodOrderer_OrderAnnotation}`: sorts test methods _numerically_ based on values - specified via the `{Order}` annotation -* `{MethodOrderer_Random}`: orders test methods _pseudo-randomly_ and supports - configuration of a custom _seed_ - -The `MethodOrderer` configured on a test class is inherited by the `@Nested` test classes -it contains, recursively. If you want to avoid that a `@Nested` test class uses the same -`MethodOrderer` as its enclosing class, you can specify `{MethodOrderer_Default}` together -with `{TestMethodOrder}`. +To control the order in which test methods are executed, annotate your test class or test interface with `{TestMethodOrder}` and specify the desired `{MethodOrderer}` +implementation. +You can implement your own custom `MethodOrderer` or use one of the following built-in `MethodOrderer` implementations. + +* `{MethodOrderer_DisplayName}`: sorts test methods _alphanumerically_ based on their display names (see <>) +* `{MethodOrderer_MethodName}`: sorts test methods _alphanumerically_ based on their names and formal parameter lists +* `{MethodOrderer_OrderAnnotation}`: sorts test methods _numerically_ based on values specified via the `{Order}` annotation +* `{MethodOrderer_Random}`: orders test methods _pseudo-randomly_ and supports configuration of a custom _seed_ + +The `MethodOrderer` configured on a test class is inherited by the `@Nested` test classes it contains, recursively. +If you want to avoid that a `@Nested` test class uses the same +`MethodOrderer` as its enclosing class, you can specify `{MethodOrderer_Default}` together with `{TestMethodOrder}`. NOTE: See also: <> -The following example demonstrates how to guarantee that test methods are executed in the -order specified via the `@Order` annotation. +The following example demonstrates how to guarantee that test methods are executed in the order specified via the `@Order` annotation. [source,java,indent=0] ---- @@ -1049,16 +926,14 @@ include::{testDir}/example/OrderedTestsDemo.java[tags=user_guide] [[writing-tests-test-execution-order-methods-default]] ===== Setting the Default Method Orderer -You can use the `junit.jupiter.testmethod.order.default` <> to specify the fully qualified class name of the -`{MethodOrderer}` you would like to use by default. Just like for the orderer configured -via the `{TestMethodOrder}` annotation, the supplied class has to implement the -`MethodOrderer` interface. The default orderer will be used for all tests unless the +You can use the `junit.jupiter.testmethod.order.default` <> to specify the fully qualified class name of the +`{MethodOrderer}` you would like to use by default. +Just like for the orderer configured via the `{TestMethodOrder}` annotation, the supplied class has to implement the +`MethodOrderer` interface. +The default orderer will be used for all tests unless the `@TestMethodOrder` annotation is present on an enclosing test class or test interface. -For example, to use the `{MethodOrderer_OrderAnnotation}` method orderer by default, you -should set the configuration parameter to the corresponding fully qualified class name -(e.g., in `src/test/resources/junit-platform.properties`): +For example, to use the `{MethodOrderer_OrderAnnotation}` method orderer by default, you should set the configuration parameter to the corresponding fully qualified class name (e.g., in `src/test/resources/junit-platform.properties`): [source,properties,indent=0] ---- @@ -1072,38 +947,26 @@ Similarly, you can specify the fully qualified name of any custom class that imp [[writing-tests-test-execution-order-classes]] ==== Class Order -Although test classes typically should not rely on the order in which they are executed, -there are times when it is desirable to enforce a specific test class execution order. You -may wish to execute test classes in a random order to ensure there are no accidental -dependencies between test classes, or you may wish to order test classes to optimize build -time as outlined in the following scenarios. +Although test classes typically should not rely on the order in which they are executed, there are times when it is desirable to enforce a specific test class execution order. +You may wish to execute test classes in a random order to ensure there are no accidental dependencies between test classes, or you may wish to order test classes to optimize build time as outlined in the following scenarios. * Run previously failing tests and faster tests first: "fail fast" mode -* With parallel execution enabled, schedule longer tests first: "shortest test plan - execution duration" mode +* With parallel execution enabled, schedule longer tests first: "shortest test plan execution duration" mode * Various other use cases To configure test class execution order _globally_ for the entire test suite, use the -`junit.jupiter.testclass.order.default` <> to specify the fully qualified class name of the `{ClassOrderer}` you would -like to use. The supplied class must implement the `ClassOrderer` interface. +`junit.jupiter.testclass.order.default` <> to specify the fully qualified class name of the `{ClassOrderer}` you would like to use. +The supplied class must implement the `ClassOrderer` interface. You can implement your own custom `ClassOrderer` or use one of the following built-in `ClassOrderer` implementations. -* `{ClassOrderer_ClassName}`: sorts test classes _alphanumerically_ based on their fully - qualified class names -* `{ClassOrderer_DisplayName}`: sorts test classes _alphanumerically_ based on their - display names (see <>) -* `{ClassOrderer_OrderAnnotation}`: sorts test classes _numerically_ based on values - specified via the `{Order}` annotation -* `{ClassOrderer_Random}`: orders test classes _pseudo-randomly_ and supports - configuration of a custom _seed_ - -For example, for the `@Order` annotation to be honored on _test classes_, you should -configure the `{ClassOrderer_OrderAnnotation}` class orderer using the configuration -parameter with the corresponding fully qualified class name (e.g., in +* `{ClassOrderer_ClassName}`: sorts test classes _alphanumerically_ based on their fully qualified class names +* `{ClassOrderer_DisplayName}`: sorts test classes _alphanumerically_ based on their display names (see <>) +* `{ClassOrderer_OrderAnnotation}`: sorts test classes _numerically_ based on values specified via the `{Order}` annotation +* `{ClassOrderer_Random}`: orders test classes _pseudo-randomly_ and supports configuration of a custom _seed_ + +For example, for the `@Order` annotation to be honored on _test classes_, you should configure the `{ClassOrderer_OrderAnnotation}` class orderer using the configuration parameter with the corresponding fully qualified class name (e.g., in `src/test/resources/junit-platform.properties`): [source,properties,indent=0] @@ -1120,18 +983,15 @@ test classes will be ordered relative to other `@Nested` test classes sharing th _enclosing class_. To configure test class execution order _locally_ for `@Nested` test classes, declare the -`{TestClassOrder}` annotation on the enclosing class for the `@Nested` test classes you -want to order, and supply a class reference to the `ClassOrderer` implementation you would -like to use directly in the `@TestClassOrder` annotation. The configured `ClassOrderer` +`{TestClassOrder}` annotation on the enclosing class for the `@Nested` test classes you want to order, and supply a class reference to the `ClassOrderer` implementation you would like to use directly in the `@TestClassOrder` annotation. +The configured `ClassOrderer` will be applied recursively to `@Nested` test classes and their `@Nested` test classes. -If you want to avoid that a `@Nested` test class uses the same `ClassOrderer` as its -enclosing class, you can specify `{ClassOrderer_Default}` together with `@TestClassOrder`. +If you want to avoid that a `@Nested` test class uses the same `ClassOrderer` as its enclosing class, you can specify `{ClassOrderer_Default}` together with `@TestClassOrder`. Note that a local `@TestClassOrder` declaration always overrides an inherited `@TestClassOrder` declaration or a `ClassOrderer` configured globally via the `junit.jupiter.testclass.order.default` configuration parameter. -The following example demonstrates how to guarantee that `@Nested` test classes are -executed in the order specified via the `@Order` annotation. +The following example demonstrates how to guarantee that `@Nested` test classes are executed in the order specified via the `@Order` annotation. [source,java,indent=0] ---- @@ -1141,74 +1001,56 @@ include::{testDir}/example/OrderedNestedTestClassesDemo.java[tags=user_guide] [[writing-tests-test-instance-lifecycle]] === Test Instance Lifecycle -In order to allow individual test methods to be executed in isolation and to avoid -unexpected side effects due to mutable test instance state, JUnit creates a new instance -of each test class before executing each _test method_ (see -<>). This "per-method" test instance lifecycle is the default -behavior in JUnit Jupiter and is analogous to all previous versions of JUnit. +In order to allow individual test methods to be executed in isolation and to avoid unexpected side effects due to mutable test instance state, JUnit creates a new instance of each test class before executing each _test method_ (see +<>). +This "per-method" test instance lifecycle is the default behavior in JUnit Jupiter and is analogous to all previous versions of JUnit. NOTE: Please note that the test class will still be instantiated if a given _test method_ is _disabled_ via a <> (e.g., `@Disabled`, `@DisabledOnOs`, etc.) even when the "per-method" test instance lifecycle mode is active. -If you would prefer that JUnit Jupiter execute all test methods on the same test -instance, annotate your test class with `@TestInstance(Lifecycle.PER_CLASS)`. When using -this mode, a new test instance will be created once per test class. Thus, if your test -methods rely on state stored in instance variables, you may need to reset that state in +If you would prefer that JUnit Jupiter execute all test methods on the same test instance, annotate your test class with `@TestInstance(Lifecycle.PER_CLASS)`. +When using this mode, a new test instance will be created once per test class. +Thus, if your test methods rely on state stored in instance variables, you may need to reset that state in `@BeforeEach` or `@AfterEach` methods. The "per-class" mode has some additional benefits over the default "per-method" mode. Specifically, with the "per-class" mode it becomes possible to declare `@BeforeAll` and `@AfterAll` on non-static methods as well as on interface `default` methods. -If you are authoring tests using the Kotlin programming language, you may also find it -easier to implement non-static `@BeforeAll` and `@AfterAll` lifecycle methods as well as -`@MethodSource` factory methods by switching to the "per-class" test instance lifecycle -mode. +If you are authoring tests using the Kotlin programming language, you may also find it easier to implement non-static `@BeforeAll` and `@AfterAll` lifecycle methods as well as +`@MethodSource` factory methods by switching to the "per-class" test instance lifecycle mode. [[writing-tests-test-instance-lifecycle-changing-default]] ==== Changing the Default Test Instance Lifecycle -If a test class or test interface is not annotated with `@TestInstance`, JUnit Jupiter -will use a _default_ lifecycle mode. The standard _default_ mode is `PER_METHOD`; -however, it is possible to change the _default_ for the execution of an entire test plan. +If a test class or test interface is not annotated with `@TestInstance`, JUnit Jupiter will use a _default_ lifecycle mode. +The standard _default_ mode is `PER_METHOD`; however, it is possible to change the _default_ for the execution of an entire test plan. To change the default test instance lifecycle mode, set the -`junit.jupiter.testinstance.lifecycle.default` _configuration parameter_ to the name of -an enum constant defined in `TestInstance.Lifecycle`, ignoring case. This can be supplied -as a JVM system property, as a _configuration parameter_ in the -`LauncherDiscoveryRequest` that is passed to the `Launcher`, or via the JUnit Platform -configuration file (see <> for details). +`junit.jupiter.testinstance.lifecycle.default` _configuration parameter_ to the name of an enum constant defined in `TestInstance.Lifecycle`, ignoring case. +This can be supplied as a JVM system property, as a _configuration parameter_ in the +`LauncherDiscoveryRequest` that is passed to the `Launcher`, or via the JUnit Platform configuration file (see <> for details). -For example, to set the default test instance lifecycle mode to `Lifecycle.PER_CLASS`, -you can start your JVM with the following system property. +For example, to set the default test instance lifecycle mode to `Lifecycle.PER_CLASS`, you can start your JVM with the following system property. `-Djunit.jupiter.testinstance.lifecycle.default=per_class` -Note, however, that setting the default test instance lifecycle mode via the JUnit -Platform configuration file is a more robust solution since the configuration file can be -checked into a version control system along with your project and can therefore be used -within IDEs and your build software. +Note, however, that setting the default test instance lifecycle mode via the JUnit Platform configuration file is a more robust solution since the configuration file can be checked into a version control system along with your project and can therefore be used within IDEs and your build software. -To set the default test instance lifecycle mode to `Lifecycle.PER_CLASS` via the JUnit -Platform configuration file, create a file named `junit-platform.properties` in the root -of the class path (e.g., `src/test/resources`) with the following content. +To set the default test instance lifecycle mode to `Lifecycle.PER_CLASS` via the JUnit Platform configuration file, create a file named `junit-platform.properties` in the root of the class path (e.g., `src/test/resources`) with the following content. `junit.jupiter.testinstance.lifecycle.default = per_class` -WARNING: Changing the _default_ test instance lifecycle mode can lead to unpredictable -results and fragile builds if not applied consistently. For example, if the build -configures "per-class" semantics as the default but tests in the IDE are executed using -"per-method" semantics, that can make it difficult to debug errors that occur on the -build server. It is therefore recommended to change the default in the JUnit Platform -configuration file instead of via a JVM system property. +WARNING: Changing the _default_ test instance lifecycle mode can lead to unpredictable results and fragile builds if not applied consistently. +For example, if the build configures "per-class" semantics as the default but tests in the IDE are executed using "per-method" semantics, that can make it difficult to debug errors that occur on the build server. +It is therefore recommended to change the default in the JUnit Platform configuration file instead of via a JVM system property. [[writing-tests-nested]] === Nested Tests -`@Nested` tests give the test writer more capabilities to express the relationship among -several groups of tests. Such nested tests make use of Java's nested classes and -facilitate hierarchical thinking about the test structure. Here's an elaborate example, -both as source code and as a screenshot of the execution within an IDE. +`@Nested` tests give the test writer more capabilities to express the relationship among several groups of tests. +Such nested tests make use of Java's nested classes and facilitate hierarchical thinking about the test structure. +Here's an elaborate example, both as source code and as a screenshot of the execution within an IDE. [source,java,indent=0] .Nested test suite for testing a stack @@ -1216,30 +1058,25 @@ both as source code and as a screenshot of the execution within an IDE. include::{testDir}/example/TestingAStackDemo.java[tags=user_guide] ---- -When executing this example in an IDE, the test execution tree in the GUI will look -similar to the following image. +When executing this example in an IDE, the test execution tree in the GUI will look similar to the following image. image::writing-tests_nested_test_ide.png[caption='',title='Executing a nested test in an IDE'] -In this example, preconditions from outer tests are used in inner tests by defining -hierarchical lifecycle methods for the setup code. For example, `createNewStack()` is a -`@BeforeEach` lifecycle method that is used in the test class in which it is defined and -in all levels in the nesting tree below the class in which it is defined. +In this example, preconditions from outer tests are used in inner tests by defining hierarchical lifecycle methods for the setup code. +For example, `createNewStack()` is a +`@BeforeEach` lifecycle method that is used in the test class in which it is defined and in all levels in the nesting tree below the class in which it is defined. -The fact that setup code from outer tests is run before inner tests are executed gives you -the ability to run all tests independently. You can even run inner tests alone without -running the outer tests, because the setup code from the outer tests is always executed. +The fact that setup code from outer tests is run before inner tests are executed gives you the ability to run all tests independently. +You can even run inner tests alone without running the outer tests, because the setup code from the outer tests is always executed. -NOTE: _Only non-static nested classes_ (i.e. _inner classes_) can serve as `@Nested` test -classes. Nesting can be arbitrarily deep, and those inner classes are subject to full -lifecycle support, including `@BeforeAll` and `@AfterAll` methods on each level. +NOTE: _Only non-static nested classes_ (i.e. _inner classes_) can serve as `@Nested` test classes. +Nesting can be arbitrarily deep, and those inner classes are subject to full lifecycle support, including `@BeforeAll` and `@AfterAll` methods on each level. [[writing-tests-nested-interoperability]] ==== Interoperability `@Nested` may be combined with -<> in which case the nested test -class is parameterized. +<> in which case the nested test class is parameterized. The following example illustrates how to combine `@Nested` with `@ParameterizedClass` and `@ParameterizedTest`. @@ -1278,30 +1115,25 @@ FruitTests ✔ [[writing-tests-dependency-injection]] === Dependency Injection for Constructors and Methods -In all prior JUnit versions, test constructors or methods were not allowed to have -parameters (at least not with the standard `Runner` implementations). As one of the major -changes in JUnit Jupiter, both test constructors and methods are now permitted to have -parameters. This allows for greater flexibility and enables _Dependency Injection_ for -constructors and methods. +In all prior JUnit versions, test constructors or methods were not allowed to have parameters (at least not with the standard `Runner` implementations). +As one of the major changes in JUnit Jupiter, both test constructors and methods are now permitted to have parameters. +This allows for greater flexibility and enables _Dependency Injection_ for constructors and methods. `{ParameterResolver}` defines the API for test extensions that wish to _dynamically_ -resolve parameters at runtime. If a _test class_ constructor, a _test method_, or a -_lifecycle method_ (see <>) accepts a parameter, the parameter -must be resolved at runtime by a registered `ParameterResolver`. +resolve parameters at runtime. +If a _test class_ constructor, a _test method_, or a +_lifecycle method_ (see <>) accepts a parameter, the parameter must be resolved at runtime by a registered `ParameterResolver`. There are currently three built-in resolvers that are registered automatically. * `{TestInfoParameterResolver}`: if a constructor or method parameter is of type - `{TestInfo}`, the `TestInfoParameterResolver` will supply an instance of `TestInfo` - corresponding to the current container or test as the value for the parameter. The - `TestInfo` can then be used to retrieve information about the current container or test - such as the display name, the test class, the test method, and associated tags. The - display name is either a technical name, such as the name of the test class or test - method, or a custom name configured via `@DisplayName`. +`{TestInfo}`, the `TestInfoParameterResolver` will supply an instance of `TestInfo` +corresponding to the current container or test as the value for the parameter. +The +`TestInfo` can then be used to retrieve information about the current container or test such as the display name, the test class, the test method, and associated tags. +The display name is either a technical name, such as the name of the test class or test method, or a custom name configured via `@DisplayName`. + -`{TestInfo}` acts as a drop-in replacement for the `TestName` rule from JUnit 4. The -following demonstrates how to have `TestInfo` injected into a `@BeforeAll` method, test -class constructor, `@BeforeEach` method, and `@Test` method. +`{TestInfo}` acts as a drop-in replacement for the `TestName` rule from JUnit 4. The following demonstrates how to have `TestInfo` injected into a `@BeforeAll` method, test class constructor, `@BeforeEach` method, and `@Test` method. [source,java,indent=0] ---- @@ -1309,23 +1141,22 @@ include::{testDir}/example/TestInfoDemo.java[tags=user_guide] ---- * `{RepetitionExtension}`: if a method parameter in a `@RepeatedTest`, `@BeforeEach`, or - `@AfterEach` method is of type `{RepetitionInfo}`, the `RepetitionExtension` will supply - an instance of `RepetitionInfo`. `RepetitionInfo` can then be used to retrieve - information about the current repetition, the total number of repetitions, the number of - repetitions that have failed, and the failure threshold for the corresponding - `@RepeatedTest`. Note, however, that `RepetitionExtension` is not registered outside the - context of a `@RepeatedTest`. See <>. +`@AfterEach` method is of type `{RepetitionInfo}`, the `RepetitionExtension` will supply an instance of `RepetitionInfo`. `RepetitionInfo` can then be used to retrieve information about the current repetition, the total number of repetitions, the number of repetitions that have failed, and the failure threshold for the corresponding +`@RepeatedTest`. +Note, however, that `RepetitionExtension` is not registered outside the context of a `@RepeatedTest`. +See <>. * `{TestReporterParameterResolver}`: if a constructor or method parameter is of type - `{TestReporter}`, the `TestReporterParameterResolver` will supply an instance of - `TestReporter`. The `TestReporter` can be used to publish additional data about the - current test run or attach files to it. The data can be consumed in a - `{TestExecutionListener}` via the `reportingEntryPublished()` or `fileEntryPublished()` - method, respectively. This allows them to be viewed in IDEs or included in reports. +`{TestReporter}`, the `TestReporterParameterResolver` will supply an instance of +`TestReporter`. +The `TestReporter` can be used to publish additional data about the current test run or attach files to it. +The data can be consumed in a +`{TestExecutionListener}` via the `reportingEntryPublished()` or `fileEntryPublished()` +method, respectively. +This allows them to be viewed in IDEs or included in reports. + In JUnit Jupiter you should use `TestReporter` where you used to print information to -`stdout` or `stderr` in JUnit 4. Some IDEs print report entries to `stdout` or display -them in the user interface for test results. +`stdout` or `stderr` in JUnit 4. Some IDEs print report entries to `stdout` or display them in the user interface for test results. [source,java,indent=0] ---- @@ -1336,9 +1167,8 @@ NOTE: Other parameter resolvers must be explicitly enabled by registering approp <> via `@ExtendWith`. Check out the `{RandomParametersExtension}` for an example of a custom -`{ParameterResolver}`. While not intended to be production-ready, it demonstrates the -simplicity and expressiveness of both the extension model and the parameter resolution -process. `MyRandomParametersTest` demonstrates how to inject random values into `@Test` +`{ParameterResolver}`. +While not intended to be production-ready, it demonstrates the simplicity and expressiveness of both the extension model and the parameter resolution process. `MyRandomParametersTest` demonstrates how to inject random values into `@Test` methods. [source,java,indent=0] @@ -1364,18 +1194,16 @@ For real-world use cases, check out the source code for the `{MockitoExtension}` When the type of the parameter to inject is the only condition for your `{ParameterResolver}`, you can use the generic `{TypeBasedParameterResolver}` base class. -The `supportsParameters` method is implemented behind the scenes and supports -parameterized types. +The `supportsParameters` method is implemented behind the scenes and supports parameterized types. [[writing-tests-test-interfaces-and-default-methods]] === Test Interfaces and Default Methods JUnit Jupiter allows `@Test`, `@RepeatedTest`, `@ParameterizedTest`, `@TestFactory`, `@TestTemplate`, `@BeforeEach`, and `@AfterEach` to be declared on interface `default` -methods. `@BeforeAll` and `@AfterAll` can either be declared on `static` methods in a -test interface or on interface `default` methods _if_ the test interface or test class is -annotated with `@TestInstance(Lifecycle.PER_CLASS)` (see -<>). Here are some examples. +methods. `@BeforeAll` and `@AfterAll` can either be declared on `static` methods in a test interface or on interface `default` methods _if_ the test interface or test class is annotated with `@TestInstance(Lifecycle.PER_CLASS)` (see +<>). +Here are some examples. [source,java] ---- @@ -1387,8 +1215,8 @@ include::{testDir}/example/testinterface/TestLifecycleLogger.java[tags=user_guid include::{testDir}/example/testinterface/TestInterfaceDynamicTestsDemo.java[tags=user_guide] ---- -`@ExtendWith` and `@Tag` can be declared on a test interface so that classes that -implement the interface automatically inherit its tags and extensions. See +`@ExtendWith` and `@Tag` can be declared on a test interface so that classes that implement the interface automatically inherit its tags and extensions. +See <> for the source code of the <>. @@ -1436,8 +1264,8 @@ include::{testDir}/example/defaultmethods/EqualsContract.java[tags=user_guide] include::{testDir}/example/defaultmethods/ComparableContract.java[tags=user_guide] ---- -In your test class you can then implement both contract interfaces thereby inheriting the -corresponding tests. Of course you'll have to implement the abstract methods. +In your test class you can then implement both contract interfaces thereby inheriting the corresponding tests. +Of course you'll have to implement the abstract methods. [source,java] ---- @@ -1446,17 +1274,14 @@ include::{testDir}/example/defaultmethods/StringTests.java[tags=user_guide] NOTE: The above tests are merely meant as examples and therefore not complete. - [[writing-tests-repeated-tests]] === Repeated Tests -JUnit Jupiter provides the ability to repeat a test a specified number of times by -annotating a method with `@RepeatedTest` and specifying the total number of repetitions -desired. Each invocation of a repeated test behaves like the execution of a regular +JUnit Jupiter provides the ability to repeat a test a specified number of times by annotating a method with `@RepeatedTest` and specifying the total number of repetitions desired. +Each invocation of a repeated test behaves like the execution of a regular `@Test` method with full support for the same lifecycle callbacks and extensions. -The following example demonstrates how to declare a test named `repeatedTest()` that -will be automatically repeated 10 times. +The following example demonstrates how to declare a test named `repeatedTest()` that will be automatically repeated 10 times. [source,java] ---- @@ -1466,32 +1291,25 @@ void repeatedTest() { } ---- -`@RepeatedTest` can be configured with a failure threshold which signifies the number of -failures after which remaining repetitions will be automatically skipped. Set the -`failureThreshold` attribute to a positive number less than the total number of -repetitions in order to skip the invocations of remaining repetitions after the specified -number of failures has been encountered. +`@RepeatedTest` can be configured with a failure threshold which signifies the number of failures after which remaining repetitions will be automatically skipped. +Set the +`failureThreshold` attribute to a positive number less than the total number of repetitions in order to skip the invocations of remaining repetitions after the specified number of failures has been encountered. -For example, if you are using `@RepeatedTest` to repeatedly invoke a test that you suspect -to be _flaky_, a single failure is sufficient to demonstrate that the test is flaky, and -there is no need to invoke the remaining repetitions. To support that specific use case, -set `failureThreshold = 1`. You can alternatively set the threshold to a number greater -than 1 depending on your use case. +For example, if you are using `@RepeatedTest` to repeatedly invoke a test that you suspect to be _flaky_, a single failure is sufficient to demonstrate that the test is flaky, and there is no need to invoke the remaining repetitions. +To support that specific use case, set `failureThreshold = 1`. +You can alternatively set the threshold to a number greater than 1 depending on your use case. -By default, the `failureThreshold` attribute is set to `Integer.MAX_VALUE`, signaling that -no failure threshold will be applied, which effectively means that the specified number of -repetitions will be invoked regardless of whether any repetitions fail. +By default, the `failureThreshold` attribute is set to `Integer.MAX_VALUE`, signaling that no failure threshold will be applied, which effectively means that the specified number of repetitions will be invoked regardless of whether any repetitions fail. -WARNING: If the repetitions of a `@RepeatedTest` method are executed in parallel, no -guarantees can be made regarding the failure threshold. It is therefore recommended that a -`@RepeatedTest` method be annotated with `@Execution(SAME_THREAD)` when parallel execution -is configured. See <> for further details. +WARNING: If the repetitions of a `@RepeatedTest` method are executed in parallel, no guarantees can be made regarding the failure threshold. +It is therefore recommended that a +`@RepeatedTest` method be annotated with `@Execution(SAME_THREAD)` when parallel execution is configured. +See <> for further details. -In addition to specifying the number of repetitions and failure threshold, a custom -display name can be configured for each repetition via the `name` attribute of the -`@RepeatedTest` annotation. Furthermore, the display name can be a pattern composed of a -combination of static text and dynamic placeholders. The following placeholders are -currently supported. +In addition to specifying the number of repetitions and failure threshold, a custom display name can be configured for each repetition via the `name` attribute of the +`@RepeatedTest` annotation. +Furthermore, the display name can be a pattern composed of a combination of static text and dynamic placeholders. +The following placeholders are currently supported. - `+{displayName}+`: display name of the `@RepeatedTest` method - `+{currentRepetition}+`: the current repetition count @@ -1507,21 +1325,17 @@ latter is equal to `"+{displayName}+ :: repetition +{currentRepetition}+ of +{totalRepetitions}+"` which results in display names for individual repetitions like `repeatedTest() :: repetition 1 of 10`, `repeatedTest() :: repetition 2 of 10`, etc. -In order to retrieve information about the current repetition, the total number of -repetitions, the number of repetitions that have failed, and the failure threshold, a -developer can choose to have an instance of `{RepetitionInfo}` injected into a +In order to retrieve information about the current repetition, the total number of repetitions, the number of repetitions that have failed, and the failure threshold, a developer can choose to have an instance of `{RepetitionInfo}` injected into a `@RepeatedTest`, `@BeforeEach`, or `@AfterEach` method. [[writing-tests-repeated-tests-examples]] ==== Repeated Test Examples -The `RepeatedTestsDemo` class at the end of this section demonstrates several examples of -repeated tests. +The `RepeatedTestsDemo` class at the end of this section demonstrates several examples of repeated tests. The `repeatedTest()` method is identical to the example from the previous section; whereas, `repeatedTestWithRepetitionInfo()` demonstrates how to have an instance of -`RepetitionInfo` injected into a test to access the total number of repetitions for the -current repeated test. +`RepetitionInfo` injected into a test to access the total number of repetitions for the current repeated test. `repeatedTestWithFailureThreshold()` demonstrates how to set a failure threshold and simulates an unexpected failure for every second repetition.The resulting behavior can be @@ -1536,14 +1350,12 @@ from the `@DisplayName` declaration, and `1/1` comes from `customDisplayNameWithLongPattern()` uses the aforementioned predefined `RepeatedTest.LONG_DISPLAY_NAME` pattern. -`repeatedTestInGerman()` demonstrates the ability to translate display names of repeated -tests into foreign languages -- in this case German, resulting in names for individual -repetitions such as: `Wiederholung 1 von 5`, `Wiederholung 2 von 5`, etc. +`repeatedTestInGerman()` demonstrates the ability to translate display names of repeated tests into foreign languages -- in this case German, resulting in names for individual repetitions such as: `Wiederholung 1 von 5`, `Wiederholung 2 von 5`, etc. -Since the `beforeEach()` method is annotated with `@BeforeEach` it will get executed -before each repetition of each repeated test. By having the `TestInfo` and -`RepetitionInfo` injected into the method, we see that it's possible to obtain -information about the currently executing repeated test. Executing `RepeatedTestsDemo` +Since the `beforeEach()` method is annotated with `@BeforeEach` it will get executed before each repetition of each repeated test. +By having the `TestInfo` and +`RepetitionInfo` injected into the method, we see that it's possible to obtain information about the currently executing repeated test. +Executing `RepeatedTestsDemo` with the `INFO` log level enabled results in the following output. .... @@ -1623,28 +1435,24 @@ When using the `ConsoleLauncher` with the unicode theme enabled, execution of │ └─ Wiederholung 5 von 5 ✔ .... - [[writing-tests-parameterized-tests]] === Parameterized Classes and Tests -_Parameterized tests_ make it possible to run a test method multiple times with different -arguments. They are declared just like regular `@Test` methods but use the +_Parameterized tests_ make it possible to run a test method multiple times with different arguments. +They are declared just like regular `@Test` methods but use the `{ParameterizedTest}` annotation instead. _Parameterized classes_ make it possible to run _all_ tests in a test class, including -<>, multiple times with different arguments. They are declared just -like regular test classes and may contain any supported test method type (including +<>, multiple times with different arguments. +They are declared just like regular test classes and may contain any supported test method type (including `@ParameterizedTest`) but annotated with the `{ParameterizedClass}` annotation. -WARNING: _Parameterized classes_ are currently an _experimental_ feature. You're invited -to give it a try and provide feedback to the JUnit team so they can improve and eventually +WARNING: _Parameterized classes_ are currently an _experimental_ feature. +You're invited to give it a try and provide feedback to the JUnit team so they can improve and eventually <> this feature. -Regardless of whether you are parameterizing a test method or a test class, you must -declare at least one <> that will -provide the arguments for each invocation and then -<> the arguments in the -parameterized method or class, respectively. +Regardless of whether you are parameterizing a test method or a test class, you must declare at least one <> that will provide the arguments for each invocation and then +<> the arguments in the parameterized method or class, respectively. The following example demonstrates a parameterized test that uses the `@ValueSource` annotation to specify a `String` array as the source of arguments. @@ -1654,9 +1462,8 @@ annotation to specify a `String` array as the source of arguments. include::{testDir}/example/ParameterizedTestDemo.java[tags=first_example] ---- -When executing the above parameterized test method, each invocation will be reported -separately. For instance, the `ConsoleLauncher` will print output similar to the -following. +When executing the above parameterized test method, each invocation will be reported separately. +For instance, the `ConsoleLauncher` will print output similar to the following. .... palindromes(String) ✔ @@ -1673,9 +1480,8 @@ The same `@ValueSource` annotation can be used to specify the source of argument include::{testDir}/example/ParameterizedClassDemo.java[tags=first_example] ---- -When executing the above parameterized test class, each invocation will be reported -separately. For instance, the `ConsoleLauncher` will print output similar to the -following. +When executing the above parameterized test class, each invocation will be reported separately. +For instance, the `ConsoleLauncher` will print output similar to the following. .... PalindromeTests ✔ @@ -1694,7 +1500,8 @@ PalindromeTests ✔ ==== Required Setup In order to use parameterized classes or tests you need to add a dependency on the -`junit-jupiter-params` artifact. Please refer to <> for details. +`junit-jupiter-params` artifact. +Please refer to <> for details. [[writing-tests-parameterized-tests-consuming-arguments]] ==== Consuming Arguments @@ -1703,54 +1510,49 @@ In order to use parameterized classes or tests you need to add a dependency on t ===== Parameterized Tests Parameterized test methods _consume_ arguments directly from the configured source (see -<>) following a one-to-one correlation between -argument source index and method parameter index (see examples in -<>). However, a parameterized test -method may also choose to _aggregate_ arguments from the source into a single object -passed to the method (see <>). -Additional arguments may also be provided by a `ParameterResolver` (e.g., to obtain an -instance of `TestInfo`, `TestReporter`, etc.). Specifically, a parameterized test method -must declare formal parameters according to the following rules. +<>) following a one-to-one correlation between argument source index and method parameter index (see examples in +<>). +However, a parameterized test method may also choose to _aggregate_ arguments from the source into a single object passed to the method (see <>). +Additional arguments may also be provided by a `ParameterResolver` (e.g., to obtain an instance of `TestInfo`, `TestReporter`, etc.). +Specifically, a parameterized test method must declare formal parameters according to the following rules. * Zero or more _indexed parameters_ must be declared first. * Zero or more _aggregators_ must be declared next. * Zero or more arguments supplied by a `ParameterResolver` must be declared last. In this context, an _indexed parameter_ is an argument for a given index in the -`{Arguments}` provided by an `{ArgumentsProvider}` that is passed as an argument to the -parameterized method at the same index in the method's formal parameter list. An -_aggregator_ is any parameter of type `{ArgumentsAccessor}` or any parameter annotated -with `{AggregateWith}`. +`{Arguments}` provided by an `{ArgumentsProvider}` that is passed as an argument to the parameterized method at the same index in the method's formal parameter list. +An +_aggregator_ is any parameter of type `{ArgumentsAccessor}` or any parameter annotated with `{AggregateWith}`. [[writing-tests-parameterized-tests-consuming-arguments-classes]] ===== Parameterized Classes Parameterized classes _consume_ arguments directly from the configured source (see -<>); either via their unique constructor or via -field injection. If a `{Parameter}`-annotated field is declared in the parameterized class -or one of its superclasses, field injection will be used. Otherwise, constructor injection -will be used. +<>); either via their unique constructor or via field injection. +If a `{Parameter}`-annotated field is declared in the parameterized class or one of its superclasses, field injection will be used. +Otherwise, constructor injection will be used. [[writing-tests-parameterized-tests-consuming-arguments-constructor-injection]] ====== Constructor Injection WARNING: Constructor injection can only be used with the (default) `PER_METHOD` -<> mode. Please use +<> mode. +Please use <> with the `PER_CLASS` mode instead. For constructor injection, the same rules apply as defined for <> -above. In the following example, two arguments are injected into the constructor of the -test class. +above. +In the following example, two arguments are injected into the constructor of the test class. [source,java,indent=0] ---- include::{testDir}/example/ParameterizedClassDemo.java[tags=constructor_injection] ---- -You may use _records_ to implement parameterized classes that avoid the boilerplate code -of declaring a test class constructor. +You may use _records_ to implement parameterized classes that avoid the boilerplate code of declaring a test class constructor. [source,java,indent=0] ---- @@ -1762,85 +1564,72 @@ include::{testDir}/example/ParameterizedRecordDemo.java[tags=example] For field injection, the following rules apply for fields annotated with `@Parameter`. -* Zero or more _indexed parameters_ may be declared; each must have a unique index - specified in its `@Parameter(index)` annotation. The index may be omitted if there is - only one indexed parameter. If there are at least two indexed parameter declarations, - there must be declarations for all indexes from 0 to the largest declared index. +* Zero or more _indexed parameters_ may be declared; each must have a unique index specified in its `@Parameter(index)` annotation. +The index may be omitted if there is only one indexed parameter. +If there are at least two indexed parameter declarations, there must be declarations for all indexes from 0 to the largest declared index. * Zero or more _aggregators_ may be declared; each without specifying an index in its - `@Parameter` annotation. +`@Parameter` annotation. * Zero or more other fields may be declared as usual as long as they're not annotated with - `@Parameter`. +`@Parameter`. In this context, an _indexed parameter_ is an argument for a given index in the -`{Arguments}` provided by an `{ArgumentsProvider}` that is injected into a field annotated -with `@Parameter(index)`. An _aggregator_ is any `@Parameter`-annotated field of type +`{Arguments}` provided by an `{ArgumentsProvider}` that is injected into a field annotated with `@Parameter(index)`. +An _aggregator_ is any `@Parameter`-annotated field of type {ArgumentsAccessor} or any field annotated with {AggregateWith}. -The following example demonstrates how to use field injection to consume multiple -arguments in a parameterized class. +The following example demonstrates how to use field injection to consume multiple arguments in a parameterized class. [source,java,indent=0] ---- include::{testDir}/example/ParameterizedClassDemo.java[tags=field_injection] ---- -If field injection is used, no constructor parameters will be resolved with arguments from -the source. Other <> +If field injection is used, no constructor parameters will be resolved with arguments from the source. +Other <> may resolve constructor parameters as usual, though. [[writing-tests-parameterized-tests-consuming-arguments-lifecycle-method]] ====== Lifecycle Methods -`{BeforeParameterizedClassInvocation}` and `{AfterParameterizedClassInvocation}` can also -be used to consume arguments if their `injectArguments` attribute is set to `true` (the -default). If so, their method signatures must follow the same rules apply as defined for -<> and -additionally use the same parameter types as the _indexed parameters_ of the parameterized -test class. Please refer to the Javadoc of `{BeforeParameterizedClassInvocation}` and +`{BeforeParameterizedClassInvocation}` and `{AfterParameterizedClassInvocation}` can also be used to consume arguments if their `injectArguments` attribute is set to `true` (the default). +If so, their method signatures must follow the same rules apply as defined for +<> and additionally use the same parameter types as the _indexed parameters_ of the parameterized test class. +Please refer to the Javadoc of `{BeforeParameterizedClassInvocation}` and `{AfterParameterizedClassInvocation}` for details and to the -<> section for an -example. +<> section for an example. [NOTE] .AutoCloseable arguments ==== Arguments that implement `java.lang.AutoCloseable` (or `java.io.Closeable` which extends -`java.lang.AutoCloseable`) will be automatically closed after the parameterized class or -test invocation. +`java.lang.AutoCloseable`) will be automatically closed after the parameterized class or test invocation. To prevent this from happening, set the `autoCloseArguments` attribute in -`@ParameterizedTest` to `false`. Specifically, if an argument that implements -`AutoCloseable` is reused for multiple invocations of the same parameterized class or test -method, you must specify the `autoCloseArguments = false` on the `{ParameterizedClass}` or -`{ParameterizedTest}` annotation to ensure that the argument is not closed between -invocations. +`@ParameterizedTest` to `false`. +Specifically, if an argument that implements +`AutoCloseable` is reused for multiple invocations of the same parameterized class or test method, you must specify the `autoCloseArguments = false` on the `{ParameterizedClass}` or +`{ParameterizedTest}` annotation to ensure that the argument is not closed between invocations. ==== [[writing-tests-parameterized-tests-consuming-arguments-other-extensions]] ===== Other Extensions -Other extensions can access the parameters and resolved arguments of a parameterized test -or class by retrieving a `{ParameterInfo}` object from the `{ExtensionContext_Store}`. +Other extensions can access the parameters and resolved arguments of a parameterized test or class by retrieving a `{ParameterInfo}` object from the `{ExtensionContext_Store}`. Please refer to the Javadoc of `{ParameterInfo}` for details. [[writing-tests-parameterized-tests-sources]] ==== Sources of Arguments -Out of the box, JUnit Jupiter provides quite a few _source_ annotations. Each of the -following subsections provides a brief overview and an example for each of them. Please -refer to the Javadoc in the `{params-provider-package}` package for additional -information. TIP: All source annotations in this section are applicable to both `{ParameterizedClass}` -and `{ParameterizedTest}`. For the sake of brevity, the examples in this section will only -show how to use them with `{ParameterizedTest}` methods. +and `{ParameterizedTest}`. +For the sake of brevity, the examples in this section will only show how to use them with `{ParameterizedTest}` methods. [[writing-tests-parameterized-tests-sources-ValueSource]] ===== @ValueSource -`@ValueSource` is one of the simplest possible sources. It lets you specify a single -array of literal values and can only be used for providing a single argument per -parameterized test invocation. +`@ValueSource` is one of the simplest possible sources. +It lets you specify a single array of literal values and can only be used for providing a single argument per parameterized test invocation. The following types of literal values are supported by `@ValueSource`. @@ -1855,8 +1644,7 @@ The following types of literal values are supported by `@ValueSource`. - `java.lang.String` - `java.lang.Class` -For example, the following `@ParameterizedTest` method will be invoked three times, with -the values `1`, `2`, and `3` respectively. +For example, the following `@ParameterizedTest` method will be invoked three times, with the values `1`, `2`, and `3` respectively. [source,java,indent=0] ---- @@ -1866,49 +1654,40 @@ include::{testDir}/example/ParameterizedTestDemo.java[tags=ValueSource_example] [[writing-tests-parameterized-tests-sources-null-and-empty]] ===== Null and Empty Sources -In order to check corner cases and verify proper behavior of our software when it is -supplied _bad input_, it can be useful to have `null` and _empty_ values supplied to our -parameterized tests. The following annotations serve as sources of `null` and empty values -for parameterized tests that accept a single argument. +In order to check corner cases and verify proper behavior of our software when it is supplied _bad input_, it can be useful to have `null` and _empty_ values supplied to our parameterized tests. +The following annotations serve as sources of `null` and empty values for parameterized tests that accept a single argument. * `{NullSource}`: provides a single `null` argument to the annotated `@ParameterizedClass` - or `@ParameterizedTest`. - - `@NullSource` cannot be used for a parameter that has a primitive type. +or `@ParameterizedTest`. +- `@NullSource` cannot be used for a parameter that has a primitive type. * `{EmptySource}`: provides a single _empty_ argument to the annotated - `@ParameterizedClass` or `@ParameterizedTest` for parameters of the following types: - `java.lang.String`, `java.util.Collection` (and concrete subtypes with a `public` no-arg - constructor), `java.util.List`, `java.util.Set`, `java.util.SortedSet`, - `java.util.NavigableSet`, `java.util.Map` (and concrete subtypes with a `public` no-arg - constructor), `java.util.SortedMap`, `java.util.NavigableMap`, primitive arrays (e.g., - `int[]`, `char[][]`, etc.), object arrays (e.g., `String[]`, `Integer[][]`, etc.). +`@ParameterizedClass` or `@ParameterizedTest` for parameters of the following types: +`java.lang.String`, `java.util.Collection` (and concrete subtypes with a `public` no-arg constructor), `java.util.List`, `java.util.Set`, `java.util.SortedSet`, +`java.util.NavigableSet`, `java.util.Map` (and concrete subtypes with a `public` no-arg constructor), `java.util.SortedMap`, `java.util.NavigableMap`, primitive arrays (e.g., +`int[]`, `char[][]`, etc.), object arrays (e.g., `String[]`, `Integer[][]`, etc.). * `{NullAndEmptySource}`: a _composed annotation_ that combines the functionality of - `@NullSource` and `@EmptySource`. +`@NullSource` and `@EmptySource`. -If you need to supply multiple varying types of _blank_ strings to a parameterized -class or test, you can achieve that using +If you need to supply multiple varying types of _blank_ strings to a parameterized class or test, you can achieve that using <> -- for example, `@ValueSource(strings = {"{nbsp}", "{nbsp}{nbsp}{nbsp}", "\t", "\n"})`. -You can also combine `@NullSource`, `@EmptySource`, and `@ValueSource` to test a wider -range of `null`, _empty_, and _blank_ input. The following example demonstrates how to -achieve this for strings. +You can also combine `@NullSource`, `@EmptySource`, and `@ValueSource` to test a wider range of `null`, _empty_, and _blank_ input. +The following example demonstrates how to achieve this for strings. [source,java,indent=0] ---- include::{testDir}/example/ParameterizedTestDemo.java[tags=NullAndEmptySource_example1] ---- -Making use of the composed `@NullAndEmptySource` annotation simplifies the above as -follows. +Making use of the composed `@NullAndEmptySource` annotation simplifies the above as follows. [source,java,indent=0] ---- include::{testDir}/example/ParameterizedTestDemo.java[tags=NullAndEmptySource_example2] ---- -NOTE: Both variants of the `nullEmptyAndBlankStrings(String)` parameterized test method -result in six invocations: 1 for `null`, 1 for the empty string, and 4 for the explicit -blank strings supplied via `@ValueSource`. +NOTE: Both variants of the `nullEmptyAndBlankStrings(String)` parameterized test method result in six invocations: 1 for `null`, 1 for the empty string, and 4 for the explicit blank strings supplied via `@ValueSource`. [[writing-tests-parameterized-tests-sources-EnumSource]] ===== @EnumSource @@ -1920,45 +1699,39 @@ blank strings supplied via `@ValueSource`. include::{testDir}/example/ParameterizedTestDemo.java[tags=EnumSource_example] ---- -The annotation's `value` attribute is optional. When omitted, the declared type of the -first parameter is used. The test will fail if it does not reference an enum type. -Thus, the `value` attribute is required in the above example because the method parameter -is declared as `TemporalUnit`, i.e. the interface implemented by `ChronoUnit`, which isn't -an enum type. Changing the method parameter type to `ChronoUnit` allows you to omit the -explicit enum type from the annotation as follows. +The annotation's `value` attribute is optional. +When omitted, the declared type of the first parameter is used. +The test will fail if it does not reference an enum type. +Thus, the `value` attribute is required in the above example because the method parameter is declared as `TemporalUnit`, i.e. the interface implemented by `ChronoUnit`, which isn't an enum type. +Changing the method parameter type to `ChronoUnit` allows you to omit the explicit enum type from the annotation as follows. [source,java,indent=0] ---- include::{testDir}/example/ParameterizedTestDemo.java[tags=EnumSource_example_autodetection] ---- -The annotation provides an optional `names` attribute that lets you specify which -constants shall be used, like in the following example. +The annotation provides an optional `names` attribute that lets you specify which constants shall be used, like in the following example. [source,java,indent=0] ---- include::{testDir}/example/ParameterizedTestDemo.java[tags=EnumSource_include_example] ---- -In addition to `names`, you can use the `from` and `to` attributes to specify a range of -constants. The range starts from the constant specified in the `from` attribute and -includes all subsequent constants up to and including the one specified in the `to` +In addition to `names`, you can use the `from` and `to` attributes to specify a range of constants. +The range starts from the constant specified in the `from` attribute and includes all subsequent constants up to and including the one specified in the `to` attribute, based on the natural order of the enum constants. -If `from` and `to` attributes are omitted, they default to the first and last constants -in the enum type, respectively. If all `names`, `from`, and `to` attributes are omitted, -all constants will be used. The following example demonstrates how to specify a range of -constants. +If `from` and `to` attributes are omitted, they default to the first and last constants in the enum type, respectively. +If all `names`, `from`, and `to` attributes are omitted, all constants will be used. +The following example demonstrates how to specify a range of constants. [source,java,indent=0] ---- include::{testDir}/example/ParameterizedTestDemo.java[tags=EnumSource_range_example] ---- -The `@EnumSource` annotation also provides an optional `mode` attribute that enables -fine-grained control over which constants are passed to the test method. For example, you -can exclude names from the enum constant pool or specify regular expressions as in the -following examples. +The `@EnumSource` annotation also provides an optional `mode` attribute that enables fine-grained control over which constants are passed to the test method. +For example, you can exclude names from the enum constant pool or specify regular expressions as in the following examples. [source,java,indent=0] ---- @@ -1970,8 +1743,7 @@ include::{testDir}/example/ParameterizedTestDemo.java[tags=EnumSource_exclude_ex include::{testDir}/example/ParameterizedTestDemo.java[tags=EnumSource_regex_example] ---- -You can also combine `mode` with the `from`, `to` and `names` attributes to define a -range of constants while excluding specific values from that range as shown below. +You can also combine `mode` with the `from`, `to` and `names` attributes to define a range of constants while excluding specific values from that range as shown below. [source,java,indent=0] ---- @@ -1981,60 +1753,46 @@ include::{testDir}/example/ParameterizedTestDemo.java[tags=EnumSource_range_excl [[writing-tests-parameterized-tests-sources-MethodSource]] ===== @MethodSource -`{MethodSource}` allows you to refer to one or more _factory_ methods of the test class -or external classes. +`{MethodSource}` allows you to refer to one or more _factory_ methods of the test class or external classes. -Factory methods within the test class must be `static` unless the test class is annotated -with `@TestInstance(Lifecycle.PER_CLASS)`; whereas, factory methods in external classes -must always be `static`. +Factory methods within the test class must be `static` unless the test class is annotated with `@TestInstance(Lifecycle.PER_CLASS)`; whereas, factory methods in external classes must always be `static`. -Each factory method must generate a _stream_ of _arguments_, and each set of arguments -within the stream will be provided as the physical arguments for individual invocations -of the annotated `@ParameterizedClass` or `@ParameterizedTest`. Generally speaking this -translates to a `Stream` of `Arguments` (i.e., `Stream`); however, the actual -concrete return type can take on many forms. In this context, a "stream" is anything that -JUnit can reliably convert into a `Stream`, such as `Stream`, `DoubleStream`, -`LongStream`, `IntStream`, `Collection`, `Iterator`, `Iterable`, an array of objects or -primitives, or any type that provides an `iterator(): Iterator` method (such as, for -example, a `kotlin.sequences.Sequence`). The "arguments" within the stream can be supplied -as an instance of `Arguments`, an array of objects (e.g., `Object[]`), or a single value -if the parameterized class or test method accepts a single argument. +Each factory method must generate a _stream_ of _arguments_, and each set of arguments within the stream will be provided as the physical arguments for individual invocations of the annotated `@ParameterizedClass` or `@ParameterizedTest`. +Generally speaking this translates to a `Stream` of `Arguments` (i.e., `Stream`); however, the actual concrete return type can take on many forms. +In this context, a "stream" is anything that JUnit can reliably convert into a `Stream`, such as `Stream`, `DoubleStream`, +`LongStream`, `IntStream`, `Collection`, `Iterator`, `Iterable`, an array of objects or primitives, or any type that provides an `iterator(): Iterator` method (such as, for example, a `kotlin.sequences.Sequence`). +The "arguments" within the stream can be supplied as an instance of `Arguments`, an array of objects (e.g., `Object[]`), or a single value if the parameterized class or test method accepts a single argument. -If the return type is `Stream` or one of the primitive streams, -JUnit will properly close it by calling `BaseStream.close()`, -making it safe to use a resource such as `Files.lines()`. +If the return type is `Stream` or one of the primitive streams, JUnit will properly close it by calling `BaseStream.close()`, making it safe to use a resource such as `Files.lines()`. -If you only need a single parameter, you can return a `Stream` of instances of the -parameter type as demonstrated in the following example. +If you only need a single parameter, you can return a `Stream` of instances of the parameter type as demonstrated in the following example. [source,java,indent=0] ---- include::{testDir}/example/ParameterizedTestDemo.java[tags=simple_MethodSource_example] ---- -For a `@ParameterizedClass`, providing a factory method name via `@MethodSource` is -mandatory. For a `@ParameterizedTest`, if you do not explicitly provide a factory method -name, JUnit Jupiter will search for a _factory_ method with the same name as the current -`@ParameterizedTest` method by convention. This is demonstrated in the following example. +For a `@ParameterizedClass`, providing a factory method name via `@MethodSource` is mandatory. +For a `@ParameterizedTest`, if you do not explicitly provide a factory method name, JUnit Jupiter will search for a _factory_ method with the same name as the current +`@ParameterizedTest` method by convention. +This is demonstrated in the following example. [source,java,indent=0] ---- include::{testDir}/example/ParameterizedTestDemo.java[tags=simple_MethodSource_without_value_example] ---- -Streams for primitive types (`DoubleStream`, `IntStream`, and `LongStream`) are also -supported as demonstrated by the following example. +Streams for primitive types (`DoubleStream`, `IntStream`, and `LongStream`) are also supported as demonstrated by the following example. [source,java,indent=0] ---- include::{testDir}/example/ParameterizedTestDemo.java[tags=primitive_MethodSource_example] ---- -If a parameterized class or test method declares multiple parameters, you need to return a -collection, stream, or array of `Arguments` instances or object arrays as shown below (see -the Javadoc for `{MethodSource}` for further details on supported return types). Note that -`arguments(Object...)` is a static factory method defined in the `Arguments` interface. In -addition, `Arguments.of(Object...)` may be used as an alternative to +If a parameterized class or test method declares multiple parameters, you need to return a collection, stream, or array of `Arguments` instances or object arrays as shown below (see the Javadoc for `{MethodSource}` for further details on supported return types). +Note that +`arguments(Object...)` is a static factory method defined in the `Arguments` interface. +In addition, `Arguments.of(Object...)` may be used as an alternative to `arguments(Object...)`. [source,java,indent=0] @@ -2042,8 +1800,7 @@ addition, `Arguments.of(Object...)` may be used as an alternative to include::{testDir}/example/ParameterizedTestDemo.java[tags=multi_arg_MethodSource_example] ---- -An external, `static` _factory_ method can be referenced by providing its _fully qualified -method name_ as demonstrated in the following example. +An external, `static` _factory_ method can be referenced by providing its _fully qualified method name_ as demonstrated in the following example. [source,java,indent=0] ---- @@ -2052,13 +1809,11 @@ package example; include::{testDir}/example/ExternalMethodSourceDemo.java[tags=external_MethodSource_example] ---- -Factory methods can declare parameters, which will be provided by registered -implementations of the `ParameterResolver` extension API. In the following example, the -factory method is referenced by its name since there is only one such method in the test -class. If there are several local methods with the same name, parameters can also be -provided to differentiate them – for example, `@MethodSource("factoryMethod()")` or -`@MethodSource("factoryMethod(java.lang.String)")`. Alternatively, the factory method -can be referenced by its fully qualified method name, e.g. +Factory methods can declare parameters, which will be provided by registered implementations of the `ParameterResolver` extension API. +In the following example, the factory method is referenced by its name since there is only one such method in the test class. +If there are several local methods with the same name, parameters can also be provided to differentiate them – for example, `@MethodSource("factoryMethod()")` or +`@MethodSource("factoryMethod(java.lang.String)")`. +Alternatively, the factory method can be referenced by its fully qualified method name, e.g. `@MethodSource("example.MyTests#factoryMethod(java.lang.String)")`. [source,java,indent=0] @@ -2069,51 +1824,40 @@ include::{testDir}/example/MethodSourceParameterResolutionDemo.java[tags=paramet [[writing-tests-parameterized-tests-sources-FieldSource]] ===== @FieldSource -`{FieldSource}` allows you to refer to one or more fields of the test class or external -classes. +`{FieldSource}` allows you to refer to one or more fields of the test class or external classes. Fields within the test class must be `static` unless the test class is annotated with `@TestInstance(Lifecycle.PER_CLASS)`; whereas, fields in external classes must always be `static`. -Each field must be able to supply a _stream_ of arguments, and each set of "arguments" -within the "stream" will be provided as the physical arguments for individual invocations -of the annotated `@ParameterizedClass` or `@ParameterizedTest`. +Each field must be able to supply a _stream_ of arguments, and each set of "arguments" within the "stream" will be provided as the physical arguments for individual invocations of the annotated `@ParameterizedClass` or `@ParameterizedTest`. -In this context, a "stream" is anything that JUnit can reliably convert to a `Stream`; -however, the actual concrete field type can take on many forms. Generally speaking this -translates to a `Collection`, an `Iterable`, a `Supplier` of a stream (`Stream`, -`DoubleStream`, `LongStream`, or `IntStream`), a `Supplier` of an `Iterator`, an array of -objects or primitives, or any type that provides an `iterator(): Iterator` method (such -as, for example, a `kotlin.sequences.Sequence`). Each set of "arguments" within the -"stream" can be supplied as an instance of `Arguments`, an array of objects (for example, -`Object[]`, `String[]`, etc.), or a single value if the parameterized class or test method accepts -a single argument. +In this context, a "stream" is anything that JUnit can reliably convert to a `Stream`; however, the actual concrete field type can take on many forms. +Generally speaking this translates to a `Collection`, an `Iterable`, a `Supplier` of a stream (`Stream`, +`DoubleStream`, `LongStream`, or `IntStream`), a `Supplier` of an `Iterator`, an array of objects or primitives, or any type that provides an `iterator(): Iterator` method (such as, for example, a `kotlin.sequences.Sequence`). +Each set of "arguments" within the "stream" can be supplied as an instance of `Arguments`, an array of objects (for example, +`Object[]`, `String[]`, etc.), or a single value if the parameterized class or test method accepts a single argument. [WARNING] ==== In contrast to the supported return types for -<> factory -methods, the value of a `@FieldSource` field cannot be an instance of `Stream`, -`DoubleStream`, `LongStream`, `IntStream`, or `Iterator`, since the values of such types -are _consumed_ the first time they are processed. However, if you wish to use one of -these types, you can wrap it in a `Supplier` — for example, `Supplier`. +<> factory methods, the value of a `@FieldSource` field cannot be an instance of `Stream`, +`DoubleStream`, `LongStream`, `IntStream`, or `Iterator`, since the values of such types are _consumed_ the first time they are processed. +However, if you wish to use one of these types, you can wrap it in a `Supplier` — for example, `Supplier`. ==== -If the `Supplier` return type is `Stream` or one of the primitive streams, -JUnit will properly close it by calling `BaseStream.close()`, -making it safe to use a resource such as `Files.lines()`. +If the `Supplier` return type is `Stream` or one of the primitive streams, JUnit will properly close it by calling `BaseStream.close()`, making it safe to use a resource such as `Files.lines()`. -Please note that a one-dimensional array of objects supplied as a set of "arguments" will -be handled differently than other types of arguments. Specifically, all the elements of a -one-dimensional array of objects will be passed as individual physical arguments to the -`@ParameterizedClass` or `@ParameterizedTest`. See the Javadoc for `{FieldSource}` for -further details. +Please note that a one-dimensional array of objects supplied as a set of "arguments" will be handled differently than other types of arguments. +Specifically, all the elements of a one-dimensional array of objects will be passed as individual physical arguments to the +`@ParameterizedClass` or `@ParameterizedTest`. +See the Javadoc for `{FieldSource}` for further details. -For a `@ParameterizedClass`, providing a field name via `@FieldSource` is mandatory. For a -`@ParameterizedTest`, if you do not explicitly provide a field name, JUnit Jupiter will -search in the test class for a field that has the same name as the current -`@ParameterizedTest` method by convention. This is demonstrated in the following example. +For a `@ParameterizedClass`, providing a field name via `@FieldSource` is mandatory. +For a +`@ParameterizedTest`, if you do not explicitly provide a field name, JUnit Jupiter will search in the test class for a field that has the same name as the current +`@ParameterizedTest` method by convention. +This is demonstrated in the following example. This parameterized test method will be invoked twice: with the values `"apple"` and `"banana"`. @@ -2123,7 +1867,8 @@ include::{testDir}/example/ParameterizedTestDemo.java[tags=default_field_FieldSo ---- The following example demonstrates how to provide a single explicit field name via -`@FieldSource`. This parameterized test method will be invoked twice: with the values +`@FieldSource`. +This parameterized test method will be invoked twice: with the values `"apple"` and `"banana"`. [source,java,indent=0] @@ -2132,9 +1877,9 @@ include::{testDir}/example/ParameterizedTestDemo.java[tags=explicit_field_FieldS ---- The following example demonstrates how to provide multiple explicit field names via -`@FieldSource`. This example uses the `listOfFruits` field from the previous example as -well as the `additionalFruits` field. Consequently, this parameterized test method will -be invoked four times: with the values `"apple"`, `"banana"`, `"cherry"`, and +`@FieldSource`. +This example uses the `listOfFruits` field from the previous example as well as the `additionalFruits` field. +Consequently, this parameterized test method will be invoked four times: with the values `"apple"`, `"banana"`, `"cherry"`, and `"dewberry"`. [source,java,indent=0] @@ -2143,11 +1888,9 @@ include::{testDir}/example/ParameterizedTestDemo.java[tags=multiple_fields_Field ---- It is also possible to provide a `Stream`, `DoubleStream`, `IntStream`, `LongStream`, or -`Iterator` as the source of arguments via a `@FieldSource` field as long as the stream or -iterator is wrapped in a `java.util.function.Supplier`. The following example demonstrates -how to provide a `Supplier` of a `Stream` of named arguments. This parameterized test -method will be invoked twice: with the values `"apple"` and `"banana"` and with display -names `"Apple"` and `"Banana"`, respectively. +`Iterator` as the source of arguments via a `@FieldSource` field as long as the stream or iterator is wrapped in a `java.util.function.Supplier`. +The following example demonstrates how to provide a `Supplier` of a `Stream` of named arguments. +This parameterized test method will be invoked twice: with the values `"apple"` and `"banana"` and with display names `"Apple"` and `"Banana"`, respectively. [source,java,indent=0] ---- @@ -2191,10 +1934,10 @@ include::{testDir}/example/ExternalFieldSourceDemo.java[tags=external_field_Fiel ===== @CsvSource `@CsvSource` allows you to express argument lists as comma-separated values (i.e., CSV -`String` literals). Each string provided via the `value` attribute in `@CsvSource` -represents a CSV record and results in one invocation of the parameterized class or -test. The first record may optionally be used to supply CSV headers (see the Javadoc for -the `useHeadersInDisplayName` attribute for details and an example). +`String` literals). +Each string provided via the `value` attribute in `@CsvSource` +represents a CSV record and results in one invocation of the parameterized class or test. +The first record may optionally be used to supply CSV headers (see the Javadoc for the `useHeadersInDisplayName` attribute for details and an example). [source,java,indent=0] ---- @@ -2202,24 +1945,24 @@ include::{testDir}/example/ParameterizedTestDemo.java[tags=CsvSource_example] ---- The default delimiter is a comma (`,`), but you can use another character by setting the -`delimiter` attribute. Alternatively, the `delimiterString` attribute allows you to use a -`String` delimiter instead of a single character. However, both delimiter attributes -cannot be set simultaneously. +`delimiter` attribute. +Alternatively, the `delimiterString` attribute allows you to use a +`String` delimiter instead of a single character. +However, both delimiter attributes cannot be set simultaneously. By default, `@CsvSource` uses a single quote (`'`) as its quote character, but this can be -changed via the `quoteCharacter` attribute. See the `'lemon, lime'` value in the example -above and in the table below. An empty, quoted value (`''`) results in an empty `String` -unless the `emptyValue` attribute is set; whereas, an entirely _empty_ value is -interpreted as a `null` reference. By specifying one or more `nullValues`, a custom value -can be interpreted as a `null` reference (see the `NIL` example in the table below). An -`ArgumentConversionException` is thrown if the target type of a `null` reference is a -primitive type. - -NOTE: An _unquoted_ empty value will always be converted to a `null` reference regardless -of any custom values configured via the `nullValues` attribute. - -Except within a quoted string, leading and trailing whitespace in a CSV column is trimmed -by default. This behavior can be changed by setting the +changed via the `quoteCharacter` attribute. +See the `'lemon, lime'` value in the example above and in the table below. +An empty, quoted value (`''`) results in an empty `String` +unless the `emptyValue` attribute is set; whereas, an entirely _empty_ value is interpreted as a `null` reference. +By specifying one or more `nullValues`, a custom value can be interpreted as a `null` reference (see the `NIL` example in the table below). +An +`ArgumentConversionException` is thrown if the target type of a `null` reference is a primitive type. + +NOTE: An _unquoted_ empty value will always be converted to a `null` reference regardless of any custom values configured via the `nullValues` attribute. + +Except within a quoted string, leading and trailing whitespace in a CSV column is trimmed by default. +This behavior can be changed by setting the `ignoreLeadingAndTrailingWhitespace` attribute to `true`. [cols="50,50"] @@ -2234,12 +1977,10 @@ by default. This behavior can be changed by setting the | `@CsvSource(value = { " apple , banana" }, ignoreLeadingAndTrailingWhitespace = false)` | `" apple "`, `" banana"` |=== -If the programming language you are using supports Java _text blocks_ or equivalent -multi-line string literals, you can alternatively use the `textBlock` attribute of -`@CsvSource`. Each record within a text block represents a CSV record and results in one -invocation of the parameterized class or test. The first record may optionally be used to -supply CSV headers by setting the `useHeadersInDisplayName` attribute to `true` as in the -example below. +If the programming language you are using supports Java _text blocks_ or equivalent multi-line string literals, you can alternatively use the `textBlock` attribute of +`@CsvSource`. +Each record within a text block represents a CSV record and results in one invocation of the parameterized class or test. +The first record may optionally be used to supply CSV headers by setting the `useHeadersInDisplayName` attribute to `true` as in the example below. Using a text block, the previous example can be implemented as follows. @@ -2267,17 +2008,13 @@ The generated display names for the previous example include the CSV header name [4] FRUIT = "strawberry", RANK = "700_000" ---- -In contrast to CSV records supplied via the `value` attribute, a text block can contain -comments. Any line beginning with the value of the `commentCharacter` attribute (`+++#+++` -by default) will be treated as a comment and ignored. Note that there is one exception -to this rule: if the comment character appears within a quoted field, it loses -its special meaning. +In contrast to CSV records supplied via the `value` attribute, a text block can contain comments. +Any line beginning with the value of the `commentCharacter` attribute (`+++#+++` +by default) will be treated as a comment and ignored. +Note that there is one exception to this rule: if the comment character appears within a quoted field, it loses its special meaning. -The comment character must be the first character on the line without any leading -whitespace. It is therefore recommended that the closing text block delimiter (`"""`) -be placed either at the end of the last line of input or on the following line, -left aligned with the rest of the input (as can be seen in the example below which -demonstrates formatting similar to a table). +The comment character must be the first character on the line without any leading whitespace. +It is therefore recommended that the closing text block delimiter (`"""`) be placed either at the end of the last line of input or on the following line, left aligned with the rest of the input (as can be seen in the example below which demonstrates formatting similar to a table). [source,java,indent=0] ---- @@ -2304,27 +2041,27 @@ void testWithCsvSource(String fruit, int rank) { ==== Java's https://docs.oracle.com/en/java/javase/17/text-blocks/index.html[text block] feature automatically removes _incidental whitespace_ when the code is compiled. -However other JVM languages such as Groovy and Kotlin do not. Thus, if you are using a -programming language other than Java and your text block contains comments or new lines -within quoted strings, you will need to ensure that there is no leading whitespace within -your text block. +However other JVM languages such as Groovy and Kotlin do not. +Thus, if you are using a programming language other than Java and your text block contains comments or new lines within quoted strings, you will need to ensure that there is no leading whitespace within your text block. ==== [[writing-tests-parameterized-tests-sources-CsvFileSource]] ===== @CsvFileSource -`@CsvFileSource` lets you use comma-separated value (CSV) files from the classpath or the -local file system. Each record from a CSV file results in one invocation of the -parameterized class or test. The first record may optionally be used to supply CSV -headers. You can instruct JUnit to ignore the headers via the `numLinesToSkip` attribute. +`@CsvFileSource` lets you use comma-separated value (CSV) files from the classpath or the local file system. +Each record from a CSV file results in one invocation of the parameterized class or test. +The first record may optionally be used to supply CSV headers. +You can instruct JUnit to ignore the headers via the `numLinesToSkip` attribute. If you would like for the headers to be used in the display names, you can set the -`useHeadersInDisplayName` attribute to `true`. The examples below demonstrate the use of +`useHeadersInDisplayName` attribute to `true`. +The examples below demonstrate the use of `numLinesToSkip` and `useHeadersInDisplayName`. The default delimiter is a comma (`,`), but you can use another character by setting the -`delimiter` attribute. Alternatively, the `delimiterString` attribute allows you to use a -`String` delimiter instead of a single character. However, both delimiter attributes -cannot be set simultaneously. +`delimiter` attribute. +Alternatively, the `delimiterString` attribute allows you to use a +`String` delimiter instead of a single character. +However, both delimiter attributes cannot be set simultaneously. .Comments in CSV files NOTE: Any line beginning with the value of the `commentCharacter` attribute (`+++#+++` @@ -2341,8 +2078,7 @@ include::{testDir}/example/ParameterizedTestDemo.java[tags=CsvFileSource_example include::{testResourcesDir}/two-column.csv[] ---- -The following listing shows the generated display names for the first two parameterized -test methods above. +The following listing shows the generated display names for the first two parameterized test methods above. ---- [1] country = "Sweden", reference = "1" @@ -2351,8 +2087,7 @@ test methods above. [4] country = "France", reference = "700_000" ---- -The following listing shows the generated display names for the last parameterized test -method above that uses CSV header names. +The following listing shows the generated display names for the last parameterized test method above that uses CSV header names. ---- [1] COUNTRY = "Sweden", REFERENCE = "1" @@ -2361,28 +2096,26 @@ method above that uses CSV header names. [4] COUNTRY = "France", REFERENCE = "700_000" ---- -In contrast to the default syntax used in `@CsvSource`, `@CsvFileSource` uses a double -quote (`+++"+++`) as the quote character by default, but this can be changed via the -`quoteCharacter` attribute. See the `"United States of America"` value in the example -above. An empty, quoted value (`+++""+++`) results in an empty `String` unless the +In contrast to the default syntax used in `@CsvSource`, `@CsvFileSource` uses a double quote (`+++"+++`) as the quote character by default, but this can be changed via the +`quoteCharacter` attribute. +See the `"United States of America"` value in the example above. +An empty, quoted value (`+++""+++`) results in an empty `String` unless the `emptyValue` attribute is set; whereas, an entirely _empty_ value is interpreted as a -`null` reference. By specifying one or more `nullValues`, a custom value can be -interpreted as a `null` reference. An `ArgumentConversionException` is thrown if the -target type of a `null` reference is a primitive type. +`null` reference. +By specifying one or more `nullValues`, a custom value can be interpreted as a `null` reference. +An `ArgumentConversionException` is thrown if the target type of a `null` reference is a primitive type. -NOTE: An _unquoted_ empty value will always be converted to a `null` reference regardless -of any custom values configured via the `nullValues` attribute. +NOTE: An _unquoted_ empty value will always be converted to a `null` reference regardless of any custom values configured via the `nullValues` attribute. -Except within a quoted string, leading and trailing whitespace in a CSV column is trimmed -by default. This behavior can be changed by setting the +Except within a quoted string, leading and trailing whitespace in a CSV column is trimmed by default. +This behavior can be changed by setting the `ignoreLeadingAndTrailingWhitespace` attribute to `true`. [[writing-tests-parameterized-tests-sources-ArgumentsSource]] ===== @ArgumentsSource -`@ArgumentsSource` can be used to specify a custom, reusable `ArgumentsProvider`. Note -that an implementation of `ArgumentsProvider` must be declared as either a top-level -class or as a `static` nested class. +`@ArgumentsSource` can be used to specify a custom, reusable `ArgumentsProvider`. +Note that an implementation of `ArgumentsProvider` must be declared as either a top-level class or as a `static` nested class. [source,java,indent=0] ---- @@ -2394,13 +2127,9 @@ include::{testDir}/example/ParameterizedTestDemo.java[tags=ArgumentsSource_examp include::{testDir}/example/ParameterizedTestDemo.java[tags=ArgumentsProvider_example] ---- -If you wish to implement a custom `ArgumentsProvider` that also consumes an annotation -(like built-in providers such as `{ValueArgumentsProvider}` or `{CsvArgumentsProvider}`), -you have the possibility to extend the `{AnnotationBasedArgumentsProvider}` class. +If you wish to implement a custom `ArgumentsProvider` that also consumes an annotation (like built-in providers such as `{ValueArgumentsProvider}` or `{CsvArgumentsProvider}`), you have the possibility to extend the `{AnnotationBasedArgumentsProvider}` class. -Moreover, `ArgumentsProvider` implementations may declare constructor parameters in case -they need to be resolved by a registered `ParameterResolver` as demonstrated in the -following example. +Moreover, `ArgumentsProvider` implementations may declare constructor parameters in case they need to be resolved by a registered `ParameterResolver` as demonstrated in the following example. [source,java,indent=0] ---- @@ -2410,8 +2139,7 @@ include::{testDir}/example/ParameterizedTestDemo.java[tags=ArgumentsProviderWith [[writing-tests-parameterized-repeatable-sources]] ===== Multiple sources using repeatable annotations -Repeatable annotations provide a convenient way to specify multiple sources from -different providers. +Repeatable annotations provide a convenient way to specify multiple sources from different providers. [source,java,indent=0] ---- @@ -2438,10 +2166,8 @@ The following annotations are repeatable: [[writing-tests-parameterized-tests-argument-count-validation]] ==== Argument Count Validation -By default, when an arguments source provides more arguments than the test method needs, -those additional arguments are ignored and the test executes as usual. -This can lead to bugs where arguments are never passed to the parameterized class or -method. +By default, when an arguments source provides more arguments than the test method needs, those additional arguments are ignored and the test executes as usual. +This can lead to bugs where arguments are never passed to the parameterized class or method. To prevent this, you can set argument count validation to 'strict'. Then, any additional arguments will cause an error instead. @@ -2449,8 +2175,7 @@ Then, any additional arguments will cause an error instead. To change this behavior for all tests, set the `junit.jupiter.params.argumentCountValidation` <> to `strict`. -To change this behavior for a single parameterized class or test method, -use the `argumentCountValidation` attribute of the `@ParameterizedClass` or +To change this behavior for a single parameterized class or test method, use the `argumentCountValidation` attribute of the `@ParameterizedClass` or `@ParameterizedTest` annotation: [source,java,indent=0] @@ -2474,13 +2199,10 @@ For example, a parameterized class or test method annotated with [[writing-tests-parameterized-tests-argument-conversion-implicit]] ===== Implicit Conversion -To support use cases like `@CsvSource`, JUnit Jupiter provides a number of built-in -implicit type converters. The conversion process depends on the declared type of each -method parameter. +To support use cases like `@CsvSource`, JUnit Jupiter provides a number of built-in implicit type converters. +The conversion process depends on the declared type of each method parameter. -For example, if a `@ParameterizedClass` or `@ParameterizedTest` declares a parameter -of type `TimeUnit` and the actual type supplied by the declared source is a `String`, the -string will be automatically converted into the corresponding `TimeUnit` enum constant. +For example, if a `@ParameterizedClass` or `@ParameterizedTest` declares a parameter of type `TimeUnit` and the actual type supplied by the declared source is a `String`, the string will be automatically converted into the corresponding `TimeUnit` enum constant. [source,java,indent=0] ---- @@ -2489,8 +2211,7 @@ include::{testDir}/example/ParameterizedTestDemo.java[tags=implicit_conversion_e `String` instances are implicitly converted to the following target types. -NOTE: Decimal, hexadecimal, and octal `String` literals will be converted to their -integral types: `byte`, `short`, `int`, `long`, and their boxed counterparts. +NOTE: Decimal, hexadecimal, and octal `String` literals will be converted to their integral types: `byte`, `short`, `int`, `long`, and their boxed counterparts. [[writing-tests-parameterized-tests-argument-conversion-implicit-table]] [cols="10,90"] @@ -2538,25 +2259,18 @@ integral types: `byte`, `short`, `int`, `long`, and their boxed counterparts. [[writing-tests-parameterized-tests-argument-conversion-implicit-fallback]] ====== Fallback String-to-Object Conversion -In addition to implicit conversion from strings to the target types listed in the above -table, JUnit Jupiter also provides a fallback mechanism for automatic conversion from a -`String` to a given target type if the target type declares exactly one suitable _factory -method_ or a _factory constructor_ as defined below. - -- __factory method__: a non-private, `static` method declared in the target type that - accepts either a single `String` argument or a single `CharSequence` argument and - returns an instance of the target type. The name of the method can be arbitrary and need - not follow any particular convention. -- __factory constructor__: a non-private constructor in the target type that accepts a - either a single `String` argument or a single `CharSequence` argument. Note that the - target type must be declared as either a top-level class or as a `static` nested class. - -NOTE: If multiple _factory methods_ are discovered, they will be ignored. If a _factory -method_ and a _factory constructor_ are discovered, the factory method will be used -instead of the constructor. - -For example, in the following `@ParameterizedTest` method, the `Book` argument will be -created by invoking the `Book.fromTitle(String)` factory method and passing `"42 Cats"` +In addition to implicit conversion from strings to the target types listed in the above table, JUnit Jupiter also provides a fallback mechanism for automatic conversion from a +`String` to a given target type if the target type declares exactly one suitable _factory method_ or a _factory constructor_ as defined below. + +- __factory method__: a non-private, `static` method declared in the target type that accepts either a single `String` argument or a single `CharSequence` argument and returns an instance of the target type. +The name of the method can be arbitrary and need not follow any particular convention. +- __factory constructor__: a non-private constructor in the target type that accepts a either a single `String` argument or a single `CharSequence` argument. +Note that the target type must be declared as either a top-level class or as a `static` nested class. + +NOTE: If multiple _factory methods_ are discovered, they will be ignored. +If a _factory method_ and a _factory constructor_ are discovered, the factory method will be used instead of the constructor. + +For example, in the following `@ParameterizedTest` method, the `Book` argument will be created by invoking the `Book.fromTitle(String)` factory method and passing `"42 Cats"` as the title of the book. [source,java,indent=0] @@ -2573,9 +2287,8 @@ include::{testDir}/example/ParameterizedTestDemo.java[tags=implicit_fallback_con ===== Explicit Conversion Instead of relying on implicit argument conversion, you may explicitly specify an -`ArgumentConverter` to use for a certain parameter using the `@ConvertWith` annotation -like in the following example. Note that an implementation of `ArgumentConverter` must be -declared as either a top-level class or as a `static` nested class. +`ArgumentConverter` to use for a certain parameter using the `@ConvertWith` annotation like in the following example. +Note that an implementation of `ArgumentConverter` must be declared as either a top-level class or as a `static` nested class. [source,java,indent=0] ---- @@ -2596,30 +2309,27 @@ include::{testDir}/example/ParameterizedTestDemo.java[tags=explicit_conversion_e ---- Explicit argument converters are meant to be implemented by test and extension authors. -Thus, `junit-jupiter-params` only provides a single explicit argument converter that may -also serve as a reference implementation: `JavaTimeArgumentConverter`. It is used via the -composed annotation `JavaTimeConversionPattern`. +Thus, `junit-jupiter-params` only provides a single explicit argument converter that may also serve as a reference implementation: `JavaTimeArgumentConverter`. +It is used via the composed annotation `JavaTimeConversionPattern`. [source,java,indent=0] ---- include::{testDir}/example/ParameterizedTestDemo.java[tags=explicit_java_time_converter] ---- -If you wish to implement a custom `ArgumentConverter` that also consumes an annotation -(like `JavaTimeArgumentConverter`), you have the possibility to extend the +If you wish to implement a custom `ArgumentConverter` that also consumes an annotation (like `JavaTimeArgumentConverter`), you have the possibility to extend the `{AnnotationBasedArgumentConverter}` class. [[writing-tests-parameterized-tests-argument-aggregation]] ==== Argument Aggregation By default, each _argument_ provided to a `@ParameterizedClass` or `@ParameterizedTest` -corresponds to a single method parameter. Consequently, argument sources which are -expected to supply a large number of arguments can lead to large constructor or method -signatures, respectively. +corresponds to a single method parameter. +Consequently, argument sources which are expected to supply a large number of arguments can lead to large constructor or method signatures, respectively. -In such cases, an `{ArgumentsAccessor}` can be used instead of multiple parameters. Using -this API, you can access the provided arguments through a single argument passed to your -test method. In addition, type conversion is supported as discussed in +In such cases, an `{ArgumentsAccessor}` can be used instead of multiple parameters. +Using this API, you can access the provided arguments through a single argument passed to your test method. +In addition, type conversion is supported as discussed in <>. Besides, you can retrieve the current test invocation index with @@ -2637,15 +2347,12 @@ _An instance of `ArgumentsAccessor` is automatically injected into any parameter ===== Custom Aggregators Apart from direct access to the arguments of a `@ParameterizedClass` or -`@ParameterizedTest` using an `ArgumentsAccessor`, JUnit Jupiter also supports the usage -of custom, reusable _aggregators_. +`@ParameterizedTest` using an `ArgumentsAccessor`, JUnit Jupiter also supports the usage of custom, reusable _aggregators_. -To use a custom aggregator, implement the `{ArgumentsAggregator}` interface and register -it via the `@AggregateWith` annotation on a compatible parameter of the -`@ParameterizedClass` or `@ParameterizedTest`. The result of the aggregation will then be -provided as an argument for the corresponding parameter when the parameterized test is -invoked. Note that an implementation of `ArgumentsAggregator` must be declared as either a -top-level class or as a `static` nested class. +To use a custom aggregator, implement the `{ArgumentsAggregator}` interface and register it via the `@AggregateWith` annotation on a compatible parameter of the +`@ParameterizedClass` or `@ParameterizedTest`. +The result of the aggregation will then be provided as an argument for the corresponding parameter when the parameterized test is invoked. +Note that an implementation of `ArgumentsAggregator` must be declared as either a top-level class or as a `static` nested class. [source,java,indent=0] ---- @@ -2657,11 +2364,9 @@ include::{testDir}/example/ParameterizedTestDemo.java[tags=ArgumentsAggregator_e include::{testDir}/example/ParameterizedTestDemo.java[tags=ArgumentsAggregator_example_PersonAggregator] ---- -If you find yourself repeatedly declaring `@AggregateWith(MyTypeAggregator.class)` for -multiple parameterized classes or methods across your codebase, you may wish to create a -custom _composed annotation_ such as `@CsvToMyType` that is meta-annotated with -`@AggregateWith(MyTypeAggregator.class)`. The following example demonstrates this in -action with a custom `@CsvToPerson` annotation. +If you find yourself repeatedly declaring `@AggregateWith(MyTypeAggregator.class)` for multiple parameterized classes or methods across your codebase, you may wish to create a custom _composed annotation_ such as `@CsvToMyType` that is meta-annotated with +`@AggregateWith(MyTypeAggregator.class)`. +The following example demonstrates this in action with a custom `@CsvToPerson` annotation. [source,java,indent=0] ---- @@ -2673,22 +2378,15 @@ include::{testDir}/example/ParameterizedTestDemo.java[tags=ArgumentsAggregator_w include::{testDir}/example/ParameterizedTestDemo.java[tags=ArgumentsAggregator_with_custom_annotation_example_CsvToPerson] ---- - [[writing-tests-parameterized-tests-display-names]] ==== Customizing Display Names -By default, the display name of a parameterized class or test invocation contains the -invocation index and a comma-separated list of the `String` representations of all -arguments for that specific invocation. If parameter names are present in the bytecode, -each argument will be preceded by its parameter name and an equals sign (unless the -argument is only available via an `ArgumentsAccessor` or `ArgumentAggregator`) – for -example, `firstName = "Jane"`. +By default, the display name of a parameterized class or test invocation contains the invocation index and a comma-separated list of the `String` representations of all arguments for that specific invocation. +If parameter names are present in the bytecode, each argument will be preceded by its parameter name and an equals sign (unless the argument is only available via an `ArgumentsAccessor` or `ArgumentAggregator`) – for example, `firstName = "Jane"`. [TIP] ==== -To ensure that parameter names are present in the bytecode, test code must be compiled -with the `-parameters` compiler flag for Java or with the `-java-parameters` compiler flag -for Kotlin. +To ensure that parameter names are present in the bytecode, test code must be compiled with the `-parameters` compiler flag for Java or with the `-java-parameters` compiler flag for Kotlin. ==== However, you can customize invocation display names via the `name` attribute of the @@ -2700,8 +2398,7 @@ However, you can customize invocation display names via the `name` attribute of include::{testDir}/example/ParameterizedTestDemo.java[tags=custom_display_names] ---- -When executing the above method using the `ConsoleLauncher` you will see output similar to -the following. +When executing the above method using the `ConsoleLauncher` you will see output similar to the following. .... Display name of container ✔ @@ -2713,7 +2410,8 @@ Display name of container ✔ [NOTE] ==== -Please note that `name` is a `MessageFormat` pattern. Thus, a single quote (`'`) needs to +Please note that `name` is a `MessageFormat` pattern. +Thus, a single quote (`'`) needs to be represented as a doubled single quote (`''`) in order to be displayed. ==== @@ -2732,17 +2430,13 @@ The following placeholders are supported within custom display names. | `\{0}`, `\{1}`, ... | an individual argument |=== -NOTE: When including arguments in display names, their string representations are truncated -if they exceed the configured maximum length. The limit is configurable via the -`junit.jupiter.params.displayname.argument.maxlength` configuration parameter and defaults -to 512 characters. +NOTE: When including arguments in display names, their string representations are truncated if they exceed the configured maximum length. +The limit is configurable via the +`junit.jupiter.params.displayname.argument.maxlength` configuration parameter and defaults to 512 characters. -When using `@MethodSource`, `@FieldSource`, or `@ArgumentsSource`, you can provide custom -names for individual arguments or custom names for entire sets of arguments. +When using `@MethodSource`, `@FieldSource`, or `@ArgumentsSource`, you can provide custom names for individual arguments or custom names for entire sets of arguments. -Use the `{Named}` API to provide a custom name for an individual argument, and the custom -name will be used if the argument is included in the invocation display name, like in the -example below. +Use the `{Named}` API to provide a custom name for an individual argument, and the custom name will be used if the argument is included in the invocation display name, like in the example below. ====== [source,java,indent=0] @@ -2750,8 +2444,7 @@ example below. include::{testDir}/example/ParameterizedTestDemo.java[tags=named_arguments] ---- -When executing the above method using the `ConsoleLauncher` you will see output similar to -the following. +When executing the above method using the `ConsoleLauncher` you will see output similar to the following. .... A parameterized test with named arguments ✔ @@ -2769,8 +2462,7 @@ Similarly, `named(String, Object)` is a static factory method defined in the `org.junit.jupiter.api.Named` interface. ==== -Use the `ArgumentSet` API to provide a custom name for the entire set of arguments, and -the custom name will be used as the display name, like in the example below. +Use the `ArgumentSet` API to provide a custom name for the entire set of arguments, and the custom name will be used as the display name, like in the example below. ====== [source,java,indent=0] @@ -2778,8 +2470,7 @@ the custom name will be used as the display name, like in the example below. include::{testDir}/example/ParameterizedTestDemo.java[tags=named_argument_set] ---- -When executing the above method using the `ConsoleLauncher` you will see output similar to -the following. +When executing the above method using the `ConsoleLauncher` you will see output similar to the following. .... A parameterized test with named argument sets ✔ @@ -2797,13 +2488,14 @@ Note that `argumentSet(String, Object...)` is a static factory method defined in [[writing-tests-parameterized-tests-display-names-quoted-text]] ===== Quoted Text-based Arguments -As of JUnit Jupiter 6.0, text-based arguments in display names for parameterized tests are -quoted by default. In this context, any `CharSequence` (such as a `String`) or `Character` -is considered text. A `CharSequence` is wrapped in double quotes (`"`), and a `Character` +As of JUnit Jupiter 6.0, text-based arguments in display names for parameterized tests are quoted by default. +In this context, any `CharSequence` (such as a `String`) or `Character` +is considered text. +A `CharSequence` is wrapped in double quotes (`"`), and a `Character` is wrapped in single quotes (`'`). -Special characters will be escaped in the quoted text. For example, carriage returns and -line feeds will be escaped as `\\r` and `\\n`, respectively. +Special characters will be escaped in the quoted text. +For example, carriage returns and line feeds will be escaped as `\\r` and `\\n`, respectively. [TIP] ==== @@ -2811,17 +2503,14 @@ This feature can be disabled by setting the `quoteTextArguments` attributes in `@ParameterizedClass` and `@ParameterizedTest` to `false`. ==== -For example, given a string argument `"line 1\nline 2"`, the physical representation in -the display name will be `"\"line 1\\nline 2\""` which is printed as `"line 1\nline 2"`. -Similarly, given a string argument `"\t"`, the physical representation in the display name -will be `"\"\\t\""` which is printed as `"\t"` instead of a blank string or invisible tab -character. The same applies for a character argument `'\t'`, whose physical representation +For example, given a string argument `"line 1\nline 2"`, the physical representation in the display name will be `"\"line 1\\nline 2\""` which is printed as `"line 1\nline 2"`. +Similarly, given a string argument `"\t"`, the physical representation in the display name will be `"\"\\t\""` which is printed as `"\t"` instead of a blank string or invisible tab character. +The same applies for a character argument `'\t'`, whose physical representation in the display name would be `"'\\t'"` which is printed as `'\t'`. For a concrete example, if you run the first `nullEmptyAndBlankStrings(String text)` parameterized test method from the -<> section above, the following -display names are generated. +<> section above, the following display names are generated. ---- [1] text = null @@ -2832,9 +2521,7 @@ display names are generated. [6] text = "\n" ---- -If you run the first `testWithCsvSource(String fruit, int rank)` parameterized test method -from the <> section above, the -following display names are generated. +If you run the first `testWithCsvSource(String fruit, int rank)` parameterized test method from the <> section above, the following display names are generated. ---- [1] fruit = "apple", rank = "1" @@ -2845,21 +2532,16 @@ following display names are generated. [NOTE] ==== -The original source arguments are quoted when generating a display name, and this occurs -before any implicit or explicit argument conversion is performed. +The original source arguments are quoted when generating a display name, and this occurs before any implicit or explicit argument conversion is performed. -For example, if a parameterized test accepts `3.14` as a `float` argument that was -converted from `"3.14"` as an input string, `"3.14"` will be present in the display name -instead of `3.14`. You can see the effect of this with the `rank` values in the above -example. +For example, if a parameterized test accepts `3.14` as a `float` argument that was converted from `"3.14"` as an input string, `"3.14"` will be present in the display name instead of `3.14`. +You can see the effect of this with the `rank` values in the above example. ==== [[writing-tests-parameterized-tests-display-names-default-pattern]] ===== Default Display Name Pattern -If you'd like to set a default name pattern for all parameterized classes and tests in -your project, you can declare the `junit.jupiter.params.displayname.default` configuration -parameter in the `junit-platform.properties` file as demonstrated in the following example (see +If you'd like to set a default name pattern for all parameterized classes and tests in your project, you can declare the `junit.jupiter.params.displayname.default` configuration parameter in the `junit-platform.properties` file as demonstrated in the following example (see <> for other options). [source,properties,indent=0] @@ -2870,13 +2552,12 @@ junit.jupiter.params.displayname.default = {index} [[writing-tests-parameterized-tests-display-names-precedence-rules]] ===== Precedence Rules -The display name for a parameterized class or test is determined according to the -following precedence rules: +The display name for a parameterized class or test is determined according to the following precedence rules: 1. `name` attribute in `@ParameterizedClass` or `@ParameterizedTest`, if present 2. value of the `junit.jupiter.params.displayname.default` configuration parameter, if present 3. `DEFAULT_DISPLAY_NAME` constant defined in - `org.junit.jupiter.params.ParameterizedInvocationConstants` +`org.junit.jupiter.params.ParameterizedInvocationConstants` [[writing-tests-parameterized-tests-lifecycle-interop]] ==== Lifecycle and Interoperability @@ -2885,16 +2566,15 @@ following precedence rules: ===== Parameterized Tests Each invocation of a parameterized test has the same lifecycle as a regular `@Test` -method. For example, `@BeforeEach` methods will be executed before each invocation. -Similar to <>, invocations will appear one by one in the -test tree of an IDE. You may at will mix regular `@Test` methods and `@ParameterizedTest` +method. +For example, `@BeforeEach` methods will be executed before each invocation. +Similar to <>, invocations will appear one by one in the test tree of an IDE. +You may at will mix regular `@Test` methods and `@ParameterizedTest` methods within the same test class. -You may use `ParameterResolver` extensions with `@ParameterizedTest` methods. However, -method parameters that are resolved by argument sources need to come first in the -parameter list. Since a test class may contain regular tests as well as parameterized -tests with different parameter lists, values from argument sources are not resolved for -lifecycle methods (e.g. `@BeforeEach`) and test class constructors. +You may use `ParameterResolver` extensions with `@ParameterizedTest` methods. +However, method parameters that are resolved by argument sources need to come first in the parameter list. +Since a test class may contain regular tests as well as parameterized tests with different parameter lists, values from argument sources are not resolved for lifecycle methods (e.g. `@BeforeEach`) and test class constructors. [source,java,indent=0] ---- @@ -2906,147 +2586,119 @@ include::{testDir}/example/ParameterizedTestDemo.java[tags=ParameterResolver_exa Each invocation of a parameterized class has the same lifecycle as a regular test class. For example, `@BeforeAll` methods will be executed _once_ before all invocations and -`@BeforeEach` methods will be executed before each _test method_ invocation. Similar to -<>, invocations will appear one by one in the test tree of an -IDE. +`@BeforeEach` methods will be executed before each _test method_ invocation. +Similar to +<>, invocations will appear one by one in the test tree of an IDE. You may use `ParameterResolver` extensions with `@ParameterizedClass` constructors. -However, if constructor injection is used, constructor parameters that are resolved by -argument sources need to come first in the parameter list. Values from argument sources -are not resolved for regular lifecycle methods (e.g. `@BeforeEach`). +However, if constructor injection is used, constructor parameters that are resolved by argument sources need to come first in the parameter list. +Values from argument sources are not resolved for regular lifecycle methods (e.g. `@BeforeEach`). In addition to regular lifecycle methods, parameterized classes may declare -`{BeforeParameterizedClassInvocation}` and `{AfterParameterizedClassInvocation}` lifecycle -methods that are called once before/after each invocation of the parameterized class. +`{BeforeParameterizedClassInvocation}` and `{AfterParameterizedClassInvocation}` lifecycle methods that are called once before/after each invocation of the parameterized class. These methods must be `static` unless the parameterized class is configured to use `@TestInstance(Lifecycle.PER_CLASS)` (see <>). -These lifecycle methods may optionally declare parameters that are resolved depending on -the setting of the `injectArguments` annotation attribute. If it is set to `false`, the -parameters must be resolved by other registered {ParameterResolver} extensions. If the -attribute is set to `true` (the default), the method may declare parameters that match the -arguments of the parameterized class (see the Javadoc of -`{BeforeParameterizedClassInvocation}` and `{AfterParameterizedClassInvocation}` for -details). This may, for example, be used to initialize the used arguments as demonstrated -by the following example. +These lifecycle methods may optionally declare parameters that are resolved depending on the setting of the `injectArguments` annotation attribute. +If it is set to `false`, the parameters must be resolved by other registered {ParameterResolver} extensions. +If the attribute is set to `true` (the default), the method may declare parameters that match the arguments of the parameterized class (see the Javadoc of +`{BeforeParameterizedClassInvocation}` and `{AfterParameterizedClassInvocation}` for details). +This may, for example, be used to initialize the used arguments as demonstrated by the following example. [source,java,indent=0] .Using parameterized class lifecycle methods ---- include::{testDir}/example/ParameterizedLifecycleDemo.java[tags=example] ---- + <1> Initialization of the argument _before_ each invocation of the parameterized class <2> Usage of the previously initialized argument in a test method -<3> Validation and cleanup of the argument _after_ each invocation of the parameterized - class +<3> Validation and cleanup of the argument _after_ each invocation of the parameterized class [[writing-tests-class-templates]] === Class Templates -A `{ClassTemplate}` is not a regular test class but rather a template for the contained -test cases. As such, it is designed to be invoked multiple times depending on invocation -contexts returned by the registered providers. Thus, it must be used in conjunction with a -registered `{ClassTemplateInvocationContextProvider}` extension. -Each invocation of a class template behaves like the execution of a regular test class -with full support for the same lifecycle callbacks and extensions. Please refer to +A `{ClassTemplate}` is not a regular test class but rather a template for the contained test cases. +As such, it is designed to be invoked multiple times depending on invocation contexts returned by the registered providers. +Thus, it must be used in conjunction with a registered `{ClassTemplateInvocationContextProvider}` extension. +Each invocation of a class template behaves like the execution of a regular test class with full support for the same lifecycle callbacks and extensions. +Please refer to <> for usage examples. -NOTE: <> are a built-in -specialization of class templates. +NOTE: <> are a built-in specialization of class templates. [[writing-tests-test-templates]] === Test Templates -A `{TestTemplate}` method is not a regular test case but rather a template for a test -case. As such, it is designed to be invoked multiple times depending on the number of -invocation contexts returned by the registered providers. Thus, it must be used in -conjunction with a registered `{TestTemplateInvocationContextProvider}` extension. Each -invocation of a test template method behaves like the execution of a regular `@Test` -method with full support for the same lifecycle callbacks and extensions. Please refer to +A `{TestTemplate}` method is not a regular test case but rather a template for a test case. +As such, it is designed to be invoked multiple times depending on the number of invocation contexts returned by the registered providers. +Thus, it must be used in conjunction with a registered `{TestTemplateInvocationContextProvider}` extension. +Each invocation of a test template method behaves like the execution of a regular `@Test` +method with full support for the same lifecycle callbacks and extensions. +Please refer to <> for usage examples. NOTE: <> and -<> are built-in specializations of -test templates. +<> are built-in specializations of test templates. [[writing-tests-dynamic-tests]] === Dynamic Tests The standard `@Test` annotation in JUnit Jupiter described in -<> is very similar to the `@Test` annotation in JUnit 4. Both -describe methods that implement test cases. These test cases are static in the sense that -they are fully specified at compile time, and their behavior cannot be changed by -anything happening at runtime. _Assumptions provide a basic form of dynamic behavior but -are intentionally rather limited in their expressiveness._ - -In addition to these standard tests a completely new kind of test programming model has -been introduced in JUnit Jupiter. This new kind of test is a _dynamic test_ which is -generated at runtime by a factory method that is annotated with `@TestFactory`. - -In contrast to `@Test` methods, a `@TestFactory` method is not itself a test case but -rather a factory for test cases. Thus, a dynamic test is the product of a factory. +<> is very similar to the `@Test` annotation in JUnit 4. Both describe methods that implement test cases. +These test cases are static in the sense that they are fully specified at compile time, and their behavior cannot be changed by anything happening at runtime. _Assumptions provide a basic form of dynamic behavior but are intentionally rather limited in their expressiveness._ + +In addition to these standard tests a completely new kind of test programming model has been introduced in JUnit Jupiter. +This new kind of test is a _dynamic test_ which is generated at runtime by a factory method that is annotated with `@TestFactory`. + +In contrast to `@Test` methods, a `@TestFactory` method is not itself a test case but rather a factory for test cases. +Thus, a dynamic test is the product of a factory. Technically speaking, a `@TestFactory` method must return a single `DynamicNode` or a -_stream_ of `DynamicNode` instances or any of its subclasses. In this context, a "stream" -is anything that JUnit can reliably convert into a `Stream`, such as `Stream`, +_stream_ of `DynamicNode` instances or any of its subclasses. +In this context, a "stream" is anything that JUnit can reliably convert into a `Stream`, such as `Stream`, `Collection`, `Iterator`, `Iterable`, an array of objects, or any type that provides an `iterator(): Iterator` method (such as, for example, a `kotlin.sequences.Sequence`). Instantiable subclasses of `DynamicNode` are `DynamicContainer` and `DynamicTest`. -`DynamicContainer` instances are composed of a _display name_ and a list of dynamic child -nodes, enabling the creation of arbitrarily nested hierarchies of dynamic nodes. -`DynamicTest` instances will be executed lazily, enabling dynamic and even -non-deterministic generation of test cases. +`DynamicContainer` instances are composed of a _display name_ and a list of dynamic child nodes, enabling the creation of arbitrarily nested hierarchies of dynamic nodes. +`DynamicTest` instances will be executed lazily, enabling dynamic and even non-deterministic generation of test cases. Any `Stream` returned by a `@TestFactory` will be properly closed by calling `stream.close()`, making it safe to use a resource such as `Files.lines()`. -As with `@Test` methods, `@TestFactory` methods must not be `private` or `static` and may -optionally declare parameters to be resolved by `ParameterResolvers`. +As with `@Test` methods, `@TestFactory` methods must not be `private` or `static` and may optionally declare parameters to be resolved by `ParameterResolvers`. -A `DynamicTest` is a test case generated at runtime. It is composed of a _display name_ -and an `Executable`. `Executable` is a `@FunctionalInterface` which means that the -implementations of dynamic tests can be provided as _lambda expressions_ or _method -references_. +A `DynamicTest` is a test case generated at runtime. +It is composed of a _display name_ +and an `Executable`. `Executable` is a `@FunctionalInterface` which means that the implementations of dynamic tests can be provided as _lambda expressions_ or _method references_. .Dynamic Test Lifecycle -WARNING: The execution lifecycle of a dynamic test is quite different than it is for a -standard `@Test` case. Specifically, there are no lifecycle callbacks for individual -dynamic tests. This means that `@BeforeEach` and `@AfterEach` methods and their -corresponding extension callbacks are executed for the `@TestFactory` method but not for -each _dynamic test_. In other words, if you access fields from the test instance within a -lambda expression for a dynamic test, those fields will not be reset by callback methods -or extensions between the execution of individual dynamic tests generated by the same +WARNING: The execution lifecycle of a dynamic test is quite different than it is for a standard `@Test` case. +Specifically, there are no lifecycle callbacks for individual dynamic tests. +This means that `@BeforeEach` and `@AfterEach` methods and their corresponding extension callbacks are executed for the `@TestFactory` method but not for each _dynamic test_. +In other words, if you access fields from the test instance within a lambda expression for a dynamic test, those fields will not be reset by callback methods or extensions between the execution of individual dynamic tests generated by the same `@TestFactory` method. [[writing-tests-dynamic-tests-examples]] ==== Dynamic Test Examples -The following `DynamicTestsDemo` class demonstrates several examples of test factories -and dynamic tests. +The following `DynamicTestsDemo` class demonstrates several examples of test factories and dynamic tests. -The first method returns an invalid return type and will cause a warning to be reported by -JUnit during test discovery. Such methods are not executed. +The first method returns an invalid return type and will cause a warning to be reported by JUnit during test discovery. +Such methods are not executed. -The next six methods demonstrate the generation of a `Collection`, `Iterable`, `Iterator`, -array, or `Stream` of `DynamicTest` instances. Most of these examples do not really -exhibit dynamic behavior but merely demonstrate the supported return types in principle. -However, `dynamicTestsFromStream()` and `dynamicTestsFromIntStream()` demonstrate how to -generate dynamic tests for a given set of strings or a range of input numbers. +The next six methods demonstrate the generation of a `Collection`, `Iterable`, `Iterator`, array, or `Stream` of `DynamicTest` instances. +Most of these examples do not really exhibit dynamic behavior but merely demonstrate the supported return types in principle. +However, `dynamicTestsFromStream()` and `dynamicTestsFromIntStream()` demonstrate how to generate dynamic tests for a given set of strings or a range of input numbers. The next method is truly dynamic in nature. `generateRandomNumberOfTests()` implements an -`Iterator` that generates random numbers, a display name generator, and a test executor -and then provides all three to `DynamicTest.stream()`. Although the non-deterministic -behavior of `generateRandomNumberOfTests()` is of course in conflict with test -repeatability and should thus be used with care, it serves to demonstrate the -expressiveness and power of dynamic tests. +`Iterator` that generates random numbers, a display name generator, and a test executor and then provides all three to `DynamicTest.stream()`. +Although the non-deterministic behavior of `generateRandomNumberOfTests()` is of course in conflict with test repeatability and should thus be used with care, it serves to demonstrate the expressiveness and power of dynamic tests. -The next method is similar to `generateRandomNumberOfTests()` in terms of flexibility; -however, `dynamicTestsFromStreamFactoryMethod()` generates a stream of dynamic tests from -an existing `Stream` via the `DynamicTest.stream()` factory method. +The next method is similar to `generateRandomNumberOfTests()` in terms of flexibility; however, `dynamicTestsFromStreamFactoryMethod()` generates a stream of dynamic tests from an existing `Stream` via the `DynamicTest.stream()` factory method. For demonstration purposes, the `dynamicNodeSingleTest()` method generates a single -`DynamicTest` instead of a stream, and the `dynamicNodeSingleContainer()` method generates -a nested hierarchy of dynamic tests utilizing `DynamicContainer`. +`DynamicTest` instead of a stream, and the `dynamicNodeSingleContainer()` method generates a nested hierarchy of dynamic tests utilizing `DynamicContainer`. [source,java] ---- @@ -3056,10 +2708,8 @@ include::{testDir}/example/DynamicTestsDemo.java[tags=user_guide] [[writing-tests-dynamic-tests-named-support]] ==== Dynamic Tests and Named -In some cases, it can be more natural to specify inputs together with a descriptive name -using the {Named} API and the corresponding `stream()` factory methods on `DynamicTest` as -shown in the first example below. The second example takes it one step further and allows -to provide the code block that should be executed by implementing the `Executable` +In some cases, it can be more natural to specify inputs together with a descriptive name using the {Named} API and the corresponding `stream()` factory methods on `DynamicTest` as shown in the first example below. +The second example takes it one step further and allows to provide the code block that should be executed by implementing the `Executable` interface along with `Named` via the `NamedExecutable` base class. [source,java] @@ -3070,43 +2720,42 @@ include::{testDir}/example/DynamicTestsNamedDemo.java[tags=user_guide] [[writing-tests-dynamic-tests-uri-test-source]] ==== URI Test Sources for Dynamic Tests -The JUnit Platform provides `TestSource`, a representation of the source of a test or -container used to navigate to its location by IDEs and build tools. +The JUnit Platform provides `TestSource`, a representation of the source of a test or container used to navigate to its location by IDEs and build tools. The `TestSource` for a dynamic test or dynamic container can be constructed from a `java.net.URI` which can be supplied via the `DynamicTest.dynamicTest(String, URI, -Executable)` or `DynamicContainer.dynamicContainer(String, URI, Stream)` factory method, -respectively. The `URI` will be converted to one of the following `TestSource` +Executable)` or `DynamicContainer.dynamicContainer(String, URI, Stream)` factory method, respectively. +The `URI` will be converted to one of the following `TestSource` implementations. `ClasspathResourceSource` :: - If the `URI` contains the `classpath` scheme -- for example, - `classpath:/test/foo.xml?line=20,column=2`. +If the `URI` contains the `classpath` scheme -- for example, +`classpath:/test/foo.xml?line=20,column=2`. `DirectorySource` :: - If the `URI` represents a directory present in the file system. +If the `URI` represents a directory present in the file system. `FileSource` :: - If the `URI` represents a file present in the file system. +If the `URI` represents a file present in the file system. `MethodSource` :: - If the `URI` contains the `method` scheme and the fully qualified method name (FQMN) -- - for example, `method:org.junit.Foo#bar(java.lang.String, java.lang.String[])`. Please - refer to the Javadoc for `{DiscoverySelectors}.{DiscoverySelectors_selectMethod}` for the - supported formats for a FQMN. +If the `URI` contains the `method` scheme and the fully qualified method name (FQMN) -- +for example, `method:org.junit.Foo#bar(java.lang.String, java.lang.String[])`. +Please refer to the Javadoc for `{DiscoverySelectors}.{DiscoverySelectors_selectMethod}` for the supported formats for a FQMN. `ClassSource` :: - If the `URI` contains the `class` scheme and the fully qualified class name -- - for example, `class:org.junit.Foo?line=42`. +If the `URI` contains the `class` scheme and the fully qualified class name -- +for example, `class:org.junit.Foo?line=42`. `UriSource` :: - If none of the above `TestSource` implementations are applicable. +If none of the above `TestSource` implementations are applicable. [[writing-tests-dynamic-tests-parallel-execution]] ==== Parallel Execution Dynamic tests and containers support -<>. You can configure their +<>. +You can configure their `ExecutionMode` by using the `dynamicTest(Consumer)` and `dynamicContainer(Consumer)` factory methods as illustrated by the following example. @@ -3115,8 +2764,7 @@ factory methods as illustrated by the following example. include::{testDir}/example/DynamicTestsDemo.java[tags=execution_mode] ---- -Executing the above test factory method results in the following test tree and execution -modes: +Executing the above test factory method results in the following test tree and execution modes: * dynamicTestsWithConfiguredExecutionMode() -- `CONCURRENT` (from `@Execution` annotation) ** Container A -- `CONCURRENT` (from `@Execution` annotation) @@ -3129,9 +2777,8 @@ modes: [[writing-tests-declarative-timeouts]] === Timeouts -The `@Timeout` annotation allows one to declare that a test, test factory, test template, -or lifecycle method should fail if its execution time exceeds a given duration. The time -unit for the duration defaults to seconds but is configurable. +The `@Timeout` annotation allows one to declare that a test, test factory, test template, or lifecycle method should fail if its execution time exceeds a given duration. +The time unit for the duration defaults to seconds but is configurable. The following example shows how `@Timeout` is applied to lifecycle and test methods. @@ -3141,15 +2788,15 @@ include::{testDir}/example/TimeoutDemo.java[tags=user_guide] ---- To apply the same timeout to all test methods within a test class and all of its `@Nested` -classes, you can declare the `@Timeout` annotation at the class level. It will then be -applied to all test, test factory, and test template methods within that class and its +classes, you can declare the `@Timeout` annotation at the class level. +It will then be applied to all test, test factory, and test template methods within that class and its `@Nested` classes unless overridden by a `@Timeout` annotation on a specific method or -`@Nested` class. Please note that `@Timeout` annotations declared at the class level are -not applied to lifecycle methods. +`@Nested` class. +Please note that `@Timeout` annotations declared at the class level are not applied to lifecycle methods. -Declaring `@Timeout` on a `@TestFactory` method checks that the factory method returns -within the specified duration but does not verify the execution time of each individual -`DynamicTest` generated by the factory. Please use +Declaring `@Timeout` on a `@TestFactory` method checks that the factory method returns within the specified duration but does not verify the execution time of each individual +`DynamicTest` generated by the factory. +Please use `assertTimeout()` or `assertTimeoutPreemptively()` for that purpose. If `@Timeout` is present on a `@TestTemplate` method — for example, a `@RepeatedTest` or @@ -3161,57 +2808,52 @@ If `@Timeout` is present on a `@TestTemplate` method — for example, a `@Repeat The timeout can be applied using one of the following three thread modes: `SAME_THREAD`, `SEPARATE_THREAD`, or `INFERRED`. -When `SAME_THREAD` is used, the execution of the annotated method proceeds in the main -thread of the test. If the timeout is exceeded, the main thread is interrupted from -another thread. This is done to ensure interoperability with frameworks such as Spring -that make use of mechanisms that are sensitive to the currently running thread — for -example, `ThreadLocal` transaction management. +When `SAME_THREAD` is used, the execution of the annotated method proceeds in the main thread of the test. +If the timeout is exceeded, the main thread is interrupted from another thread. +This is done to ensure interoperability with frameworks such as Spring that make use of mechanisms that are sensitive to the currently running thread — for example, `ThreadLocal` transaction management. On the contrary when `SEPARATE_THREAD` is used, like the `assertTimeoutPreemptively()` -assertion, the execution of the annotated method proceeds in a separate thread, this -can lead to undesirable side effects, see <>. +assertion, the execution of the annotated method proceeds in a separate thread, this can lead to undesirable side effects, see <>. When `INFERRED` (default) thread mode is used, the thread mode is resolved via the -`junit.jupiter.execution.timeout.thread.mode.default` configuration parameter. If the -provided configuration parameter is invalid or not present then `SAME_THREAD` is used as -fallback. +`junit.jupiter.execution.timeout.thread.mode.default` configuration parameter. +If the provided configuration parameter is invalid or not present then `SAME_THREAD` is used as fallback. [[writing-tests-declarative-timeouts-default-timeouts]] ==== Default Timeouts -The following <> can be used to -specify default timeouts for all methods of a certain category unless they or an enclosing -test class is annotated with `@Timeout`: +The following <> can be used to specify default timeouts for all methods of a certain category unless they or an enclosing test class is annotated with `@Timeout`: `junit.jupiter.execution.timeout.default`:: - Default timeout for all testable and lifecycle methods +Default timeout for all testable and lifecycle methods `junit.jupiter.execution.timeout.testable.method.default`:: - Default timeout for all testable methods +Default timeout for all testable methods `junit.jupiter.execution.timeout.test.method.default`:: - Default timeout for `@Test` methods +Default timeout for `@Test` methods `junit.jupiter.execution.timeout.testtemplate.method.default`:: - Default timeout for `@TestTemplate` methods +Default timeout for `@TestTemplate` methods `junit.jupiter.execution.timeout.testfactory.method.default`:: - Default timeout for `@TestFactory` methods +Default timeout for `@TestFactory` methods `junit.jupiter.execution.timeout.lifecycle.method.default`:: - Default timeout for all lifecycle methods +Default timeout for all lifecycle methods `junit.jupiter.execution.timeout.beforeall.method.default`:: - Default timeout for `@BeforeAll` methods +Default timeout for `@BeforeAll` methods `junit.jupiter.execution.timeout.beforeeach.method.default`:: - Default timeout for `@BeforeEach` methods +Default timeout for `@BeforeEach` methods `junit.jupiter.execution.timeout.aftereach.method.default`:: - Default timeout for `@AfterEach` methods +Default timeout for `@AfterEach` methods `junit.jupiter.execution.timeout.afterall.method.default`:: - Default timeout for `@AfterAll` methods +Default timeout for `@AfterAll` methods -More specific configuration parameters override less specific ones. For example, +More specific configuration parameters override less specific ones. +For example, `junit.jupiter.execution.timeout.test.method.default` overrides `junit.jupiter.execution.timeout.testable.method.default` which overrides `junit.jupiter.execution.timeout.default`. -The values of such configuration parameters must be in the following, case-insensitive -format: ` [ns|μs|ms|s|m|h|d]`. The space between the number and the unit may be -omitted. Specifying no unit is equivalent to using seconds. +The values of such configuration parameters must be in the following, case-insensitive format: ` [ns|μs|ms|s|m|h|d]`. +The space between the number and the unit may be omitted. +Specifying no unit is equivalent to using seconds. .Example timeout configuration parameter values [cols="20,80"] @@ -3228,93 +2870,74 @@ omitted. Specifying no unit is equivalent to using seconds. | `42 d` | `@Timeout(value = 42, unit = DAYS)` |=== - [[writing-tests-declarative-timeouts-polling]] ==== Using @Timeout for Polling Tests -When dealing with asynchronous code, it is common to write tests that poll while waiting -for something to happen before performing any assertions. In some cases you can rewrite -the logic to use a `CountDownLatch` or another synchronization mechanism, but sometimes -that is not possible — for example, if the subject under test sends a message to a channel -in an external message broker and assertions cannot be performed until the message has -been successfully sent through the channel. Asynchronous tests like these require some -form of timeout to ensure they don't hang the test suite by executing indefinitely, as -would be the case if an asynchronous message never gets successfully delivered. +When dealing with asynchronous code, it is common to write tests that poll while waiting for something to happen before performing any assertions. +In some cases you can rewrite the logic to use a `CountDownLatch` or another synchronization mechanism, but sometimes that is not possible — for example, if the subject under test sends a message to a channel in an external message broker and assertions cannot be performed until the message has been successfully sent through the channel. +Asynchronous tests like these require some form of timeout to ensure they don't hang the test suite by executing indefinitely, as would be the case if an asynchronous message never gets successfully delivered. -By configuring a timeout for an asynchronous test that polls, you can ensure that the test -does not execute indefinitely. The following example demonstrates how to achieve this with -JUnit Jupiter's `@Timeout` annotation. This technique can be used to implement "poll -until" logic very easily. +By configuring a timeout for an asynchronous test that polls, you can ensure that the test does not execute indefinitely. +The following example demonstrates how to achieve this with JUnit Jupiter's `@Timeout` annotation. +This technique can be used to implement "poll until" logic very easily. [source,java] ---- include::{testDir}/example/PollingTimeoutDemo.java[tags=user_guide,indent=0] ---- -NOTE: If you need more control over polling intervals and greater flexibility with -asynchronous tests, consider using a dedicated library such as +NOTE: If you need more control over polling intervals and greater flexibility with asynchronous tests, consider using a dedicated library such as link:https://github.com/awaitility/awaitility[Awaitility]. - [[writing-tests-declarative-timeouts-debugging]] ==== Debugging Timeouts Registered <> extensions are called prior to invoking -`Thread.interrupt()` on the thread that is executing the timed out method. This allows to -inspect the application state and output additional information that might be helpful for -diagnosing the cause of a timeout. - +`Thread.interrupt()` on the thread that is executing the timed out method. +This allows to inspect the application state and output additional information that might be helpful for diagnosing the cause of a timeout. [[writing-tests-declarative-timeouts-debugging-thread-dump]] ===== Thread Dump on Timeout JUnit registers a default implementation of the <> -extension point that dumps the stacks of all threads to `System.out` if enabled by setting -the `junit.jupiter.execution.timeout.threaddump.enabled` +extension point that dumps the stacks of all threads to `System.out` if enabled by setting the `junit.jupiter.execution.timeout.threaddump.enabled` <> to `true`. - [[writing-tests-declarative-timeouts-mode]] ==== Disable @Timeout Globally -When stepping through your code in a debug session, a fixed timeout limit may influence -the result of the test, e.g. mark the test as failed although all assertions were met. +When stepping through your code in a debug session, a fixed timeout limit may influence the result of the test, e.g. mark the test as failed although all assertions were met. -JUnit Jupiter supports the `junit.jupiter.execution.timeout.mode` configuration parameter -to configure when timeouts are applied. There are three modes: `enabled`, `disabled`, -and `disabled_on_debug`. The default mode is `enabled`. -A VM runtime is considered to run in debug mode when one of its input parameters starts -with `-agentlib:jdwp` or `-Xrunjdwp`. +JUnit Jupiter supports the `junit.jupiter.execution.timeout.mode` configuration parameter to configure when timeouts are applied. +There are three modes: `enabled`, `disabled`, and `disabled_on_debug`. +The default mode is `enabled`. +A VM runtime is considered to run in debug mode when one of its input parameters starts with `-agentlib:jdwp` or `-Xrunjdwp`. This heuristic is queried by the `disabled_on_debug` mode. - [[writing-tests-parallel-execution]] === Parallel Execution -By default, JUnit Jupiter tests are run sequentially in a single thread; however, running -tests in parallel -- for example, to speed up execution -- is available as an opt-in -feature. To enable parallel execution, set the `junit.jupiter.execution.parallel.enabled` +By default, JUnit Jupiter tests are run sequentially in a single thread; however, running tests in parallel -- for example, to speed up execution -- is available as an opt-in feature. +To enable parallel execution, set the `junit.jupiter.execution.parallel.enabled` configuration parameter to `true` -- for example, in `junit-platform.properties` (see <> for other options). -Please note that enabling this property is only the first step required to execute tests -in parallel. If enabled, test classes and methods will still be executed sequentially by -default. Whether or not a node in the test tree is executed concurrently is controlled by -its execution mode. The following two modes are available. +Please note that enabling this property is only the first step required to execute tests in parallel. +If enabled, test classes and methods will still be executed sequentially by default. +Whether or not a node in the test tree is executed concurrently is controlled by its execution mode. +The following two modes are available. `SAME_THREAD`:: - Force execution in the same thread used by the parent. For example, when used on a test - method, the test method will be executed in the same thread as any `@BeforeAll` or - `@AfterAll` methods of the containing test class. +Force execution in the same thread used by the parent. +For example, when used on a test method, the test method will be executed in the same thread as any `@BeforeAll` or +`@AfterAll` methods of the containing test class. `CONCURRENT`:: - Execute concurrently unless a resource lock forces execution in the same thread. +Execute concurrently unless a resource lock forces execution in the same thread. -By default, nodes in the test tree use the `SAME_THREAD` execution mode. You can change -the default by setting the `junit.jupiter.execution.parallel.mode.default` configuration -parameter. Alternatively, you can use the `{Execution}` annotation to change the -execution mode for the annotated element and its subelements (if any) which allows you to -activate parallel execution for individual test classes, one by one. +By default, nodes in the test tree use the `SAME_THREAD` execution mode. +You can change the default by setting the `junit.jupiter.execution.parallel.mode.default` configuration parameter. +Alternatively, you can use the `{Execution}` annotation to change the execution mode for the annotated element and its subelements (if any) which allows you to activate parallel execution for individual test classes, one by one. [source,properties] .Configuration parameters to execute all tests in parallel @@ -3323,42 +2946,31 @@ junit.jupiter.execution.parallel.enabled = true junit.jupiter.execution.parallel.mode.default = concurrent ---- -The default execution mode is applied to all nodes of the test tree with a few notable -exceptions, namely test classes that use the `Lifecycle.PER_CLASS` mode or a -`{MethodOrderer}`. In the former case, test authors have to ensure that the test class is -thread-safe; in the latter, concurrent execution might conflict with the configured -execution order. Thus, in both cases, test methods in such test classes are only executed -concurrently if the `@Execution(CONCURRENT)` annotation is present on the test class or -method. +The default execution mode is applied to all nodes of the test tree with a few notable exceptions, namely test classes that use the `Lifecycle.PER_CLASS` mode or a +`{MethodOrderer}`. +In the former case, test authors have to ensure that the test class is thread-safe; in the latter, concurrent execution might conflict with the configured execution order. +Thus, in both cases, test methods in such test classes are only executed concurrently if the `@Execution(CONCURRENT)` annotation is present on the test class or method. -You can use the `@Execution` annotation to explicitly configure the execution mode for a -test class or method: +You can use the `@Execution` annotation to explicitly configure the execution mode for a test class or method: [source,java] ---- include::{testDir}/example/ExplicitExecutionModeDemo.java[tags=user_guide] ---- -This allows test classes or methods to opt in or out of concurrent execution regardless of -the globally configured default. +This allows test classes or methods to opt in or out of concurrent execution regardless of the globally configured default. When parallel execution is enabled and a default `{ClassOrderer}` is registered (see -<> for details), top-level test classes will -initially be sorted accordingly and scheduled in that order. However, they are not -guaranteed to be started in exactly that order since the threads they are executed on are -not controlled directly by JUnit. - -All nodes of the test tree that are configured with the `CONCURRENT` execution mode will -be executed fully in parallel according to the provided -<> while observing the -declarative <> -mechanism. Please note that <> needs to be enabled -separately. - -In addition, you can configure the default execution mode for top-level classes by setting -the `junit.jupiter.execution.parallel.mode.classes.default` configuration parameter. By -combining both configuration parameters, you can configure classes to run in parallel but -their methods in the same thread: +<> for details), top-level test classes will initially be sorted accordingly and scheduled in that order. +However, they are not guaranteed to be started in exactly that order since the threads they are executed on are not controlled directly by JUnit. + +All nodes of the test tree that are configured with the `CONCURRENT` execution mode will be executed fully in parallel according to the provided +<> while observing the declarative <> +mechanism. +Please note that <> needs to be enabled separately. + +In addition, you can configure the default execution mode for top-level classes by setting the `junit.jupiter.execution.parallel.mode.classes.default` configuration parameter. +By combining both configuration parameters, you can configure classes to run in parallel but their methods in the same thread: [source,properties] .Configuration parameters to execute top-level classes in parallel but methods in same thread @@ -3368,8 +2980,7 @@ junit.jupiter.execution.parallel.mode.default = same_thread junit.jupiter.execution.parallel.mode.classes.default = concurrent ---- -The opposite combination will run all methods within one class in parallel, but top-level -classes will run sequentially: +The opposite combination will run all methods within one class in parallel, but top-level classes will run sequentially: [source,properties] .Configuration parameters to execute top-level classes sequentially but their methods in parallel @@ -3424,9 +3035,7 @@ gantt //// image::writing-tests_execution_mode.svg[caption='',title='Default execution mode configuration combinations'] -If the `junit.jupiter.execution.parallel.mode.classes.default` configuration parameter is -not explicitly set, the value for `junit.jupiter.execution.parallel.mode.default` will be -used instead. +If the `junit.jupiter.execution.parallel.mode.classes.default` configuration parameter is not explicitly set, the value for `junit.jupiter.execution.parallel.mode.default` will be used instead. [[writing-tests-parallel-execution-config]] ==== Configuration @@ -3434,178 +3043,159 @@ used instead. [[writing-tests-parallel-execution-config-executor-service]] ===== Executor Service -If parallel execution is enabled, a thread pool is used behind the scenes to execute tests -concurrently. You can configure which implementation of `HierarchicalTestExecutorService` +If parallel execution is enabled, a thread pool is used behind the scenes to execute tests concurrently. +You can configure which implementation of `HierarchicalTestExecutorService` is used be setting the `junit.jupiter.execution.parallel.config.executor-service` configuration parameter to one of the following options: `fork_join_pool` (default):: -Use an executor service that is backed by a `ForkJoinPool` from the JDK. This will cause -tests to be executed in a `ForkJoinWorkerThread`. In some cases, usages of -`ForkJoinPool` in test or production code or calls to blocking JDK APIs may cause the -number of concurrently executing tests to increase. To avoid this situation, please use +Use an executor service that is backed by a `ForkJoinPool` from the JDK. +This will cause tests to be executed in a `ForkJoinWorkerThread`. +In some cases, usages of +`ForkJoinPool` in test or production code or calls to blocking JDK APIs may cause the number of concurrently executing tests to increase. +To avoid this situation, please use `worker_thread_pool`. `worker_thread_pool` (experimental):: -Use an executor service that is backed by a regular thread pool and does not create -additional threads if test or production code uses `ForkJoinPool` or calls a blocking -API in the JDK. +Use an executor service that is backed by a regular thread pool and does not create additional threads if test or production code uses `ForkJoinPool` or calls a blocking API in the JDK. -WARNING: Using `worker_thread_pool` is currently an _experimental_ feature. You're invited -to give it a try and provide feedback to the JUnit team so they can improve and eventually +WARNING: Using `worker_thread_pool` is currently an _experimental_ feature. +You're invited to give it a try and provide feedback to the JUnit team so they can improve and eventually <> this feature. [[writing-tests-parallel-execution-config-strategies]] ===== Strategies -Properties such as the desired parallelism and the maximum pool size can be configured -using a `{ParallelExecutionConfigurationStrategy}`. The JUnit Platform provides two -implementations out of the box: `dynamic` and `fixed`. Alternatively, you may implement a +Properties such as the desired parallelism and the maximum pool size can be configured using a `{ParallelExecutionConfigurationStrategy}`. +The JUnit Platform provides two implementations out of the box: `dynamic` and `fixed`. +Alternatively, you may implement a `custom` strategy. To select a strategy, set the `junit.jupiter.execution.parallel.config.strategy` configuration parameter to one of the following options. `dynamic`:: - Computes the desired parallelism based on the number of available processors/cores - multiplied by the `junit.jupiter.execution.parallel.config.dynamic.factor` - configuration parameter (defaults to `1`). - The optional `junit.jupiter.execution.parallel.config.dynamic.max-pool-size-factor` - configuration parameter can be used to limit the maximum number of threads. +Computes the desired parallelism based on the number of available processors/cores multiplied by the `junit.jupiter.execution.parallel.config.dynamic.factor` +configuration parameter (defaults to `1`). +The optional `junit.jupiter.execution.parallel.config.dynamic.max-pool-size-factor` +configuration parameter can be used to limit the maximum number of threads. `fixed`:: - Uses the mandatory `junit.jupiter.execution.parallel.config.fixed.parallelism` - configuration parameter as the desired parallelism. - The optional `junit.jupiter.execution.parallel.config.fixed.max-pool-size` - configuration parameter can be used to limit the maximum number of threads. +Uses the mandatory `junit.jupiter.execution.parallel.config.fixed.parallelism` +configuration parameter as the desired parallelism. +The optional `junit.jupiter.execution.parallel.config.fixed.max-pool-size` +configuration parameter can be used to limit the maximum number of threads. `custom`:: - Allows you to specify a custom `{ParallelExecutionConfigurationStrategy}` - implementation via the mandatory `junit.jupiter.execution.parallel.config.custom.class` - configuration parameter to determine the desired configuration. +Allows you to specify a custom `{ParallelExecutionConfigurationStrategy}` +implementation via the mandatory `junit.jupiter.execution.parallel.config.custom.class` +configuration parameter to determine the desired configuration. -If no configuration strategy is set, JUnit Jupiter uses the `dynamic` configuration -strategy with a factor of `1`. Consequently, the desired parallelism will be equal to the -number of available processors/cores. +If no configuration strategy is set, JUnit Jupiter uses the `dynamic` configuration strategy with a factor of `1`. +Consequently, the desired parallelism will be equal to the number of available processors/cores. .Parallelism alone does not imply maximum number of concurrent threads -NOTE: By default, JUnit Jupiter does not guarantee that the number of threads used to -execute test will not exceed the configured parallelism. For example, when using one -of the synchronization mechanisms described in the next section, the executor service -implementation may spawn additional threads to ensure execution continues with sufficient -parallelism. If you require such guarantees, it is possible to limit the maximum number of -threads by configuring the maximum pool size of the `dynamic`, `fixed` and `custom` +NOTE: By default, JUnit Jupiter does not guarantee that the number of threads used to execute test will not exceed the configured parallelism. +For example, when using one of the synchronization mechanisms described in the next section, the executor service implementation may spawn additional threads to ensure execution continues with sufficient parallelism. +If you require such guarantees, it is possible to limit the maximum number of threads by configuring the maximum pool size of the `dynamic`, `fixed` and `custom` strategies. [[writing-tests-parallel-execution-config-properties]] ===== Relevant properties -The following table lists relevant properties for configuring parallel execution. See +The following table lists relevant properties for configuring parallel execution. +See <> for details on how to set such properties. ====== General `junit.jupiter.execution.parallel.enabled=true|false`:: - Enable/disable parallel test execution (defaults to `false`). +Enable/disable parallel test execution (defaults to `false`). `junit.jupiter.execution.parallel.mode.default=concurrent|same_thread`:: - Default execution mode of nodes in the test tree (defaults to `same_thread`). +Default execution mode of nodes in the test tree (defaults to `same_thread`). `junit.jupiter.execution.parallel.mode.classes.default=concurrent|same_thread`:: - Default execution mode of top-level classes (defaults to `same_thread`). +Default execution mode of top-level classes (defaults to `same_thread`). `junit.jupiter.execution.parallel.config.executor-service=fork_join_pool|worker_thread_pool`:: - Type of `HierarchicalTestExecutorService` to use for parallel execution (defaults to - `fork_join_pool`). +Type of `HierarchicalTestExecutorService` to use for parallel execution (defaults to +`fork_join_pool`). `junit.jupiter.execution.parallel.config.strategy=dynamic|fixed|custom`:: - Execution strategy for desired parallelism, maximum pool size, etc. (defaults to `dynamic`). +Execution strategy for desired parallelism, maximum pool size, etc. (defaults to `dynamic`). ====== Dynamic strategy `junit.jupiter.execution.parallel.config.dynamic.factor=decimal`:: - Factor to be multiplied by the number of available processors/cores to determine the - desired parallelism for the ```dynamic``` configuration strategy. - Must be a positive decimal number (defaults to `1.0`). +Factor to be multiplied by the number of available processors/cores to determine the desired parallelism for the ```dynamic``` configuration strategy. +Must be a positive decimal number (defaults to `1.0`). `junit.jupiter.execution.parallel.config.dynamic.max-pool-size-factor=decimal`:: - Factor to be multiplied by the number of available processors/cores and the value of - `junit.jupiter.execution.parallel.config.dynamic.factor` to determine the desired - parallelism for the ```dynamic``` configuration strategy. - Must be a positive decimal number greater than or equal to `1.0` (defaults to 256 plus - the value of `junit.jupiter.execution.parallel.config.dynamic.factor` multiplied by the - number of available processors/cores) +Factor to be multiplied by the number of available processors/cores and the value of +`junit.jupiter.execution.parallel.config.dynamic.factor` to determine the desired parallelism for the ```dynamic``` configuration strategy. +Must be a positive decimal number greater than or equal to `1.0` (defaults to 256 plus the value of `junit.jupiter.execution.parallel.config.dynamic.factor` multiplied by the number of available processors/cores) `junit.jupiter.execution.parallel.config.dynamic.saturate=true|false`:: - Enable/disable saturation of the underlying `ForkJoinPool` for the ```dynamic``` - configuration strategy (defaults to `true`). Only used if - `junit.jupiter.execution.parallel.config.executor-service` is set to `fork_join_pool`. +Enable/disable saturation of the underlying `ForkJoinPool` for the ```dynamic``` configuration strategy (defaults to `true`). +Only used if +`junit.jupiter.execution.parallel.config.executor-service` is set to `fork_join_pool`. ====== Fixed strategy `junit.jupiter.execution.parallel.config.fixed.parallelism=integer`:: - Desired parallelism for the ```fixed``` configuration strategy (no default value). Must - be a positive integer. +Desired parallelism for the ```fixed``` configuration strategy (no default value). +Must be a positive integer. `junit.jupiter.execution.parallel.config.fixed.max-pool-size=integer`:: - Desired maximum pool size of the underlying fork-join pool for the ```fixed``` - configuration strategy. Must be a positive integer greater than or equal to - `junit.jupiter.execution.parallel.config.fixed.parallelism` (defaults to 256 plus the - value of `junit.jupiter.execution.parallel.config.fixed.parallelism`). +Desired maximum pool size of the underlying fork-join pool for the ```fixed``` configuration strategy. +Must be a positive integer greater than or equal to +`junit.jupiter.execution.parallel.config.fixed.parallelism` (defaults to 256 plus the value of `junit.jupiter.execution.parallel.config.fixed.parallelism`). `junit.jupiter.execution.parallel.config.fixed.saturate=true|false`:: - Enable/disable saturation of the underlying `ForkJoinPool` for the ```fixed``` - configuration strategy (defaults to `true`). Only used if - `junit.jupiter.execution.parallel.config.executor-service` is set to `fork_join_pool`. +Enable/disable saturation of the underlying `ForkJoinPool` for the ```fixed``` configuration strategy (defaults to `true`). +Only used if +`junit.jupiter.execution.parallel.config.executor-service` is set to `fork_join_pool`. ====== Custom strategy `junit.jupiter.execution.parallel.config.custom.class=classname`:: - Fully qualified class name of the `ParallelExecutionConfigurationStrategy` to be used - for the ```custom``` configuration strategy (no default value). +Fully qualified class name of the `ParallelExecutionConfigurationStrategy` to be used for the ```custom``` configuration strategy (no default value). [[writing-tests-parallel-execution-synchronization]] ==== Synchronization -In addition to controlling the execution mode using the `{Execution}` annotation, JUnit -Jupiter provides another annotation-based declarative synchronization mechanism. The -`{ResourceLock}` annotation allows you to declare that a test class or method uses a -specific shared resource that requires synchronized access to ensure reliable test -execution. The shared resource is identified by a unique name which is a `String`. The -name can be user-defined or one of the predefined constants in `{Resources}`: +In addition to controlling the execution mode using the `{Execution}` annotation, JUnit Jupiter provides another annotation-based declarative synchronization mechanism. +The +`{ResourceLock}` annotation allows you to declare that a test class or method uses a specific shared resource that requires synchronized access to ensure reliable test execution. +The shared resource is identified by a unique name which is a `String`. +The name can be user-defined or one of the predefined constants in `{Resources}`: `SYSTEM_PROPERTIES`, `SYSTEM_OUT`, `SYSTEM_ERR`, `LOCALE`, or `TIME_ZONE`. In addition to declaring these shared resources statically, the `{ResourceLock}` annotation has a `providers` attribute that allows registering implementations of the `{ResourceLocksProvider}` interface that can add shared resources dynamically at runtime. -Note that resources declared statically with `{ResourceLock}` annotation are combined with -resources added dynamically by `{ResourceLocksProvider}` implementations. +Note that resources declared statically with `{ResourceLock}` annotation are combined with resources added dynamically by `{ResourceLocksProvider}` implementations. If the tests in the following example were run in parallel _without_ the use of -`{ResourceLock}`, they would be _flaky_. Sometimes they would pass, and at other times they -would fail due to the inherent race condition of writing and then reading the same JVM -System Property. - -When access to shared resources is declared using the `{ResourceLock}` annotation, the -JUnit Jupiter engine uses this information to ensure that no conflicting tests are run in -parallel. This guarantee extends to lifecycle methods of a test class or method. For -example, if a test method is annotated with a `{ResourceLock}` annotation, the "lock" will -be acquired before any `@BeforeEach` methods are executed and released after all +`{ResourceLock}`, they would be _flaky_. +Sometimes they would pass, and at other times they would fail due to the inherent race condition of writing and then reading the same JVM System Property. + +When access to shared resources is declared using the `{ResourceLock}` annotation, the JUnit Jupiter engine uses this information to ensure that no conflicting tests are run in parallel. +This guarantee extends to lifecycle methods of a test class or method. +For example, if a test method is annotated with a `{ResourceLock}` annotation, the "lock" will be acquired before any `@BeforeEach` methods are executed and released after all `@AfterEach` methods have been executed. [NOTE] .Running tests in isolation ==== -If most of your test classes can be run in parallel without any synchronization but you -have some test classes that need to run in isolation, you can mark the latter with the -`{Isolated}` annotation. Tests in such classes are executed sequentially without any other -tests running at the same time. +If most of your test classes can be run in parallel without any synchronization but you have some test classes that need to run in isolation, you can mark the latter with the +`{Isolated}` annotation. +Tests in such classes are executed sequentially without any other tests running at the same time. ==== -In addition to the `String` that uniquely identifies the shared resource, you may specify -an access mode. Two tests that require `READ` access to a shared resource may run in -parallel with each other but not while any other test that requires `READ_WRITE` access -to the same shared resource is running. +In addition to the `String` that uniquely identifies the shared resource, you may specify an access mode. +Two tests that require `READ` access to a shared resource may run in parallel with each other but not while any other test that requires `READ_WRITE` access to the same shared resource is running. [source,java] .Declaring shared resources "statically" with `{ResourceLock}` annotation @@ -3620,20 +3210,17 @@ include::{testDir}/example/sharedresources/DynamicSharedResourcesDemo.java[tags= ---- Also, "static" shared resources can be declared for _direct_ child nodes via the `target` -attribute in the `{ResourceLock}` annotation, the attribute accepts a value from -the `{ResourceLockTarget}` enum. +attribute in the `{ResourceLock}` annotation, the attribute accepts a value from the `{ResourceLockTarget}` enum. -Specifying `target = CHILDREN` in a class-level `{ResourceLock}` annotation -has the same semantics as adding an annotation with the same `value` and `mode` +Specifying `target = CHILDREN` in a class-level `{ResourceLock}` annotation has the same semantics as adding an annotation with the same `value` and `mode` to each test method and nested test class declared in this class. -This may improve parallelization when a test class declares a `READ` lock, -but only a few methods hold a `READ_WRITE` lock. +This may improve parallelization when a test class declares a `READ` lock, but only a few methods hold a `READ_WRITE` lock. Tests in the following example would run in the `SAME_THREAD` if the `{ResourceLock}` -didn't have `target = CHILDREN`. This is because the test class declares a `READ` -shared resource, but one test method holds a `READ_WRITE` lock, -which would force the `SAME_THREAD` execution mode for all the test methods. +didn't have `target = CHILDREN`. +This is because the test class declares a `READ` +shared resource, but one test method holds a `READ_WRITE` lock, which would force the `SAME_THREAD` execution mode for all the test methods. [source,java] .Declaring shared resources for child nodes with `target` attribute @@ -3641,28 +3228,21 @@ which would force the `SAME_THREAD` execution mode for all the test methods. include::{testDir}/example/sharedresources/ChildrenSharedResourcesDemo.java[tags=user_guide] ---- - [[writing-tests-built-in-extensions]] === Built-in Extensions -While the JUnit team encourages reusable extensions to be packaged and maintained in -separate libraries, JUnit Jupiter includes a few user-facing extension implementations -that are considered so generally useful that users shouldn't have to add another -dependency. +While the JUnit team encourages reusable extensions to be packaged and maintained in separate libraries, JUnit Jupiter includes a few user-facing extension implementations that are considered so generally useful that users shouldn't have to add another dependency. [[writing-tests-built-in-extensions-TempDirectory]] ==== The @TempDir Extension -The built-in `{TempDirectory}` extension is used to create and clean up a temporary -directory for an individual test or all tests in a test class. It is registered by -default. To use it, annotate a non-final, unassigned field of type `java.nio.file.Path` or +The built-in `{TempDirectory}` extension is used to create and clean up a temporary directory for an individual test or all tests in a test class. +It is registered by default. +To use it, annotate a non-final, unassigned field of type `java.nio.file.Path` or `java.io.File` with `{TempDir}` or add a parameter of type `java.nio.file.Path` or -`java.io.File` annotated with `@TempDir` to a test class constructor, lifecycle method, or -test method. +`java.io.File` annotated with `@TempDir` to a test class constructor, lifecycle method, or test method. -For example, the following test declares a parameter annotated with `@TempDir` for a -single test method, creates and writes to a file in the temporary directory, and checks -its content. +For example, the following test declares a parameter annotated with `@TempDir` for a single test method, creates and writes to a file in the temporary directory, and checks its content. [source,java,indent=0] .A test method that requires a temporary directory @@ -3678,10 +3258,9 @@ You can inject multiple temporary directories by specifying multiple annotated p include::{testDir}/example/TempDirectoryDemo.java[tags=user_guide_multiple_directories] ---- -The following example stores a _shared_ temporary directory in a `static` field. This -allows the same `sharedTempDir` to be used in all lifecycle methods and test methods of -the test class. For better isolation, you should use an instance field or constructor -injection so that each test method uses a separate directory. +The following example stores a _shared_ temporary directory in a `static` field. +This allows the same `sharedTempDir` to be used in all lifecycle methods and test methods of the test class. +For better isolation, you should use an instance field or constructor injection so that each test method uses a separate directory. [source,java,indent=0] .A test class that shares a temporary directory across test methods @@ -3690,11 +3269,12 @@ include::{testDir}/example/TempDirectoryDemo.java[tags=user_guide_field_injectio ---- The `@TempDir` annotation has an optional `cleanup` attribute that can be set to either -`NEVER`, `ON_SUCCESS`, or `ALWAYS`. If the cleanup mode is set to `NEVER`, the temporary -directory will not be deleted after the test completes. If it is set to `ON_SUCCESS`, the -temporary directory will only be deleted after the test if the test completed successfully. +`NEVER`, `ON_SUCCESS`, or `ALWAYS`. +If the cleanup mode is set to `NEVER`, the temporary directory will not be deleted after the test completes. +If it is set to `ON_SUCCESS`, the temporary directory will only be deleted after the test if the test completed successfully. -The default cleanup mode is `ALWAYS`. You can use the +The default cleanup mode is `ALWAYS`. +You can use the `junit.jupiter.tempdir.cleanup.mode.default` <> to override this default. @@ -3705,22 +3285,18 @@ include::{testDir}/example/TempDirectoryDemo.java[tags=user_guide_cleanup_mode] ---- `@TempDir` supports the programmatic creation of temporary directories via the optional -`factory` attribute. This is typically used to gain control over the temporary directory -creation, like defining the parent directory or the file system that should be used. +`factory` attribute. +This is typically used to gain control over the temporary directory creation, like defining the parent directory or the file system that should be used. -Factories can be created by implementing `TempDirFactory`. Implementations must provide a -no-args constructor and should not make any assumptions regarding when and how many times -they are instantiated, but they can assume that their `createTempDirectory(...)` and -`close()` methods will both be called once per instance, in this order, and from the same -thread. +Factories can be created by implementing `TempDirFactory`. +Implementations must provide a no-args constructor and should not make any assumptions regarding when and how many times they are instantiated, but they can assume that their `createTempDirectory(...)` and +`close()` methods will both be called once per instance, in this order, and from the same thread. The default implementation available in Jupiter delegates directory creation to -`java.nio.file.Files::createTempDirectory` which uses the default file system and the -system's temporary directory as the parent directory. It passes `junit-` as the prefix -string of the generated directory name to help identify it as a created by JUnit. +`java.nio.file.Files::createTempDirectory` which uses the default file system and the system's temporary directory as the parent directory. +It passes `junit-` as the prefix string of the generated directory name to help identify it as a created by JUnit. -The following example defines a factory that uses the test name as the directory name -prefix instead of the `junit` constant value. +The following example defines a factory that uses the test name as the directory name prefix instead of the `junit` constant value. [source,java,indent=0] .A test class with a temporary directory having the test name as the directory name prefix @@ -3728,8 +3304,8 @@ prefix instead of the `junit` constant value. include::{testDir}/example/TempDirectoryDemo.java[tags=user_guide_factory_name_prefix] ---- -It is also possible to use an in-memory file system like `{Jimfs}` for the creation of the -temporary directory. The following example demonstrates how to achieve that. +It is also possible to use an in-memory file system like `{Jimfs}` for the creation of the temporary directory. +The following example demonstrates how to achieve that. [source,java,indent=0] .A test class with a temporary directory created with the Jimfs in-memory file system @@ -3737,8 +3313,8 @@ temporary directory. The following example demonstrates how to achieve that. include::{testDir}/example/TempDirectoryDemo.java[tags=user_guide_factory_jimfs] ---- -`@TempDir` can also be used as a <> to -reduce repetition. The following code listing shows how to create a custom `@JimfsTempDir` +`@TempDir` can also be used as a <> to reduce repetition. +The following code listing shows how to create a custom `@JimfsTempDir` annotation that can be used as a drop-in replacement for `@TempDir(factory = JimfsTempDirFactory.class)`. @@ -3761,66 +3337,62 @@ annotation is declared on might expose additional attributes to configure the fa Such annotations and related attributes can be accessed via the `AnnotatedElementContext` parameter of the `createTempDirectory(...)` method. -You can use the `junit.jupiter.tempdir.factory.default` <> to specify the fully qualified class name of the -`TempDirFactory` you would like to use by default. Just like for factories configured via -the `factory` attribute of the `@TempDir` annotation, the supplied class has to implement -the `TempDirFactory` interface. The default factory will be used for all `@TempDir` +You can use the `junit.jupiter.tempdir.factory.default` <> to specify the fully qualified class name of the +`TempDirFactory` you would like to use by default. +Just like for factories configured via the `factory` attribute of the `@TempDir` annotation, the supplied class has to implement the `TempDirFactory` interface. +The default factory will be used for all `@TempDir` annotations unless the `factory` attribute of the annotation specifies a different factory. -In summary, the factory for a temporary directory is determined according to the following -precedence rules: +In summary, the factory for a temporary directory is determined according to the following precedence rules: 1. The `factory` attribute of the `@TempDir` annotation, if present -2. The default `TempDirFactory` configured via the configuration -parameter, if present +2. The default `TempDirFactory` configured via the configuration parameter, if present 3. Otherwise, `org.junit.jupiter.api.io.TempDirFactory$Standard` will be used. [[writing-tests-built-in-extensions-AutoClose]] ==== The @AutoClose Extension The built-in `{AutoCloseExtension}` automatically closes resources associated with fields. -It is registered by default. To use it, annotate a field in a test class with +It is registered by default. +To use it, annotate a field in a test class with `{AutoClose}`. -`@AutoClose` fields may be either `static` or non-static. If the value of an `@AutoClose` -field is `null` when it is evaluated the field will be ignored, but a warning message will -be logged to inform you. +`@AutoClose` fields may be either `static` or non-static. +If the value of an `@AutoClose` +field is `null` when it is evaluated the field will be ignored, but a warning message will be logged to inform you. By default, `@AutoClose` expects the value of the annotated field to implement a `close()` -method that will be invoked to close the resource. However, developers can customize the -name of the close method via the `value` attribute. For example, `@AutoClose("shutdown")` +method that will be invoked to close the resource. +However, developers can customize the name of the close method via the `value` attribute. +For example, `@AutoClose("shutdown")` instructs JUnit to look for a `shutdown()` method to close the resource. -`@AutoClose` fields are inherited from superclasses. Furthermore, `@AutoClose` fields from -subclasses will be closed before `@AutoClose` fields in superclasses. +`@AutoClose` fields are inherited from superclasses. +Furthermore, `@AutoClose` fields from subclasses will be closed before `@AutoClose` fields in superclasses. -When multiple `@AutoClose` fields exist within a given test class, the order in which the -resources are closed depends on an algorithm that is deterministic but intentionally -nonobvious. This ensures that subsequent runs of a test suite close resources in the same -order, thereby allowing for repeatable builds. +When multiple `@AutoClose` fields exist within a given test class, the order in which the resources are closed depends on an algorithm that is deterministic but intentionally nonobvious. +This ensures that subsequent runs of a test suite close resources in the same order, thereby allowing for repeatable builds. The `AutoCloseExtension` implements the `AfterAllCallback` and -`TestInstancePreDestroyCallback` extension APIs. Consequently, a `static` `@AutoClose` -field will be closed after all tests in the current test class have completed, effectively -after `@AfterAll` methods have executed for the test class. A non-static `@AutoClose` -field will be closed before the current test class instance is destroyed. Specifically, if -the test class is configured with `@TestInstance(Lifecycle.PER_METHOD)` semantics, a -non-static `@AutoClose` field will be closed after the execution of each test method, test -factory method, or test template method. However, if the test class is configured with -`@TestInstance(Lifecycle.PER_CLASS)` semantics, a non-static `@AutoClose` field will not -be closed until the current test class instance is no longer needed, which means after +`TestInstancePreDestroyCallback` extension APIs. +Consequently, a `static` `@AutoClose` +field will be closed after all tests in the current test class have completed, effectively after `@AfterAll` methods have executed for the test class. +A non-static `@AutoClose` +field will be closed before the current test class instance is destroyed. +Specifically, if the test class is configured with `@TestInstance(Lifecycle.PER_METHOD)` semantics, a non-static `@AutoClose` field will be closed after the execution of each test method, test factory method, or test template method. +However, if the test class is configured with +`@TestInstance(Lifecycle.PER_CLASS)` semantics, a non-static `@AutoClose` field will not be closed until the current test class instance is no longer needed, which means after `@AfterAll` methods and after all `static` `@AutoClose` fields have been closed. -The following example demonstrates how to annotate an instance field with `@AutoClose` so -that the resource is automatically closed after test execution. In this example, we assume -that the default `@TestInstance(Lifecycle.PER_METHOD)` semantics apply. +The following example demonstrates how to annotate an instance field with `@AutoClose` so that the resource is automatically closed after test execution. +In this example, we assume that the default `@TestInstance(Lifecycle.PER_METHOD)` semantics apply. [source,java,indent=0] .A test class using `@AutoClose` to close a resource ---- include::{testDir}/example/AutoCloseDemo.java[tags=user_guide_example] ---- + <1> Annotate an instance field with `@AutoClose`. <2> `WebClient` implements `java.lang.AutoCloseable` which defines a `close()` method that will be invoked after each `@Test` method. @@ -3938,3 +3510,120 @@ locale or time zone need to be annotated with the respective annotation: Tests annotated in this way will never execute in parallel with tests annotated with `@DefaultLocale` or `@DefaultTimeZone`. +<2> `WebClient` implements `java.lang.AutoCloseable` which defines a `close()` method that will be invoked after each `@Test` method. + +[[writing-tests-built-in-extensions-SystemProperty]] +==== `@ClearSystemProperty` and `@SetSystemProperty` + +The `@ClearSystemProperty` and `@SetSystemProperty` annotations can be used to clear and set, respectively, the values of system properties for a test execution. +Both annotations work on the test method and class level, are repeatable, combinable, and inherited from higher-level containers. +After the annotated method has been executed, the properties mentioned in the annotation will be restored to their original value or the value of the higher-level container, or will be cleared if they didn't have one before. +Other system properties that are changed during the test, are *not* restored (unless the `@RestoreSystemProperties` is used). + +For example, clearing a system property for a test execution can be done as follows: + +[source,java,indent=0] +---- +include::{testDir}/example/SystemPropertyExtensionDemo.java[tag=systemproperty_clear_simple] +---- + +And setting a system property for a test execution: + +[source,java,indent=0] +---- +include::{testDir}/example/SystemPropertyExtensionDemo.java[tag=systemproperty_set_simple] +---- + +As mentioned before, both annotations are repeatable, and they can also be combined: + +[source,java,indent=0] +---- +include::{testDir}/example/SystemPropertyExtensionDemo.java[tag=systemproperty_using_set_and_clear] + +---- + +Note that class-level configurations are overwritten by method-level configurations: + +[source,java,indent=0] +---- +include::{testDir}/example/SystemPropertyExtensionDemo.java[tag=systemproperty_using_at_class_level] +---- + +[NOTE] +==== +Method-level configurations are visible in both `@BeforeEach` setup methods and `@AfterEach` teardown methods (see <>). + +A class-level configuration means that the specified system properties are cleared/set before and reset after each individual test in the annotated class. +==== + +== `@RestoreSystemProperties` + +`@RestoreSystemProperties` can be used to restore changes to system properties made directly in code. +While `@ClearSystemProperty` and `@SetSystemProperty` set or clear specific properties and values, they don't allow property values to be calculated or parameterized, thus there are times you may want to directly set properties in your test code. +`@RestoreSystemProperties` can be placed on test methods or test classes and will completely restore all system properties to their original state after a test or test class is complete. + +In this example, `@RestoreSystemProperties` is used on a test method, ensuring any changes made in that method are restored: + +[source,java,indent=0] +---- +include::{testDir}/example/SystemPropertyExtensionDemo.java[tag=systemproperty_restore_test] +---- + +When `@RestoreSystemProperties` is used on a test class, any system properties changes made during the entire lifecycle of the test class, including test methods, `@BeforeAll`, `@BeforeEach` and 'after' methods, are restored after the test class' lifecycle is complete. +In addition, the annotation is inherited by each test method just as if each one was annotated with `@RestoreSystemProperties`. + +In the following example, both test methods see the system property changes made in `@BeforeAll` and `@BeforeEach`, however, the test methods are isolated from each other (`isolatedTest2` does not 'see' changes made in `isolatedTest1`). +As shown in the second example below, the class-level `@RestoreSystemProperties` ensures that system property changes made within the annotated class are completely restored after the class's lifecycle, ensuring that changes are not visible to `SomeOtherTestClass`. +Note that `SomeOtherTestClass` uses the `@ReadsSystemProperty` annotation: This ensures that JUnit does not schedule the class to run during any test known to modify system properties (see <>). + +[source,java,indent=0] +---- +include::{testDir}/example/SystemPropertyExtensionDemo.java[tag=systemproperty_class_restore_setup] +---- + +Some other test class, running later: + +[source,java,indent=0] +---- +include::{testDir}/example/SystemPropertyExtensionDemo.java[tag=systemproperty_class_restore_isolated_class] +---- + +== Using `@ClearSystemProperty`, `@SetSystemProperty`, and `@RestoreSystemProperties` together + +All three annotations can be combined, which could be used when some system properties are parameterized (i.e. need to be set in code) and others are not. +For instance, imagine testing an image generation utility that takes configuration from system properties. +Basic configuration can be specified using `Set` and `Clear` and the image size parameterized: + +[source,java,indent=0] +---- +include::{testDir}/example/SystemPropertyExtensionDemo.java[tag=systemproperty_method_combine_all_test] +---- + +[NOTE] +==== +Using `@RestoreSystemProperties` is not necessary to restore system properties modified via `@ClearSystemProperty` or `@SetSystemProperty` - they each automatically restore the referenced properties. +'Restore', is only needed if system properties are modified in some way _other than_ Clear and Set during a test. +==== + +=== `@RestoreSystemProperties` Limitations + +The system `Properties` object is normally just a hashmap of strings, however, it is technically possible to store non-string values and create {jdk-javadoc-base-url}/java.base/java/util/Properties.html#%3Cinit%3E(java.util.Properties)[nested `Properties` with inherited default values]. +`@RestoreSystemProperties` restores the original `Properties` object with all of its potential richness _after_ the annotated scope is complete. +However, for use during the test _within_ the test scope it provides a cloned `Properties` object with these limitations: + +- Properties with non-string values are removed +- Nested `Properties` are flattened into a non-nested instance that has the same effective values, but not necessarily the same structure + +== Thread-Safety + +Since system properties are global state, reading and writing them during <> can lead to unpredictable results and flaky tests. +The system property extension is prepared for that and tests annotated with `@ClearSystemProperty`, `@SetSystemProperty`, or `@RestoreSystemProperties` will never execute in parallel (thanks to https://docs.junit.org/current/api[resource locks]) to guarantee correct test results. + +However, this does not cover all possible cases. +Tested code that reads or writes system properties _independently_ of the extension can still run in parallel to it and may thus behave erratically when, for example, it unexpectedly reads a property set by the extension in another thread. +Tests that cover code that reads or writes system properties need to be annotated with the respective annotation: + +* `@ReadsSystemProperty` +* `@WritesSystemProperty` (though consider using `@RestoreSystemProperties` instead) + +Tests annotated in this way will never execute in parallel with tests annotated with `@ClearSystemProperty`, `@SetSystemProperty`, or `@RestoreSystemProperties`. diff --git a/documentation/src/test/java/example/SystemPropertyExtensionDemo.java b/documentation/src/test/java/example/SystemPropertyExtensionDemo.java new file mode 100644 index 000000000000..2edf62d17dba --- /dev/null +++ b/documentation/src/test/java/example/SystemPropertyExtensionDemo.java @@ -0,0 +1,153 @@ +/* + * Copyright 2015-2025 the original author or authors. + * + * All rights reserved. This program and the accompanying materials are + * made available under the terms of the Eclipse Public License v2.0 which + * accompanies this distribution and is available at + * + * https://www.eclipse.org/legal/epl-v20.html + */ + +package example; + +import static org.assertj.core.api.Assertions.assertThat; + +import org.junit.jupiter.api.BeforeAll; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.ClassOrderer; +import org.junit.jupiter.api.Nested; +import org.junit.jupiter.api.Order; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.TestClassOrder; +import org.junit.jupiter.api.TestInstance; +import org.junit.jupiter.api.util.ClearSystemProperty; +import org.junit.jupiter.api.util.ReadsSystemProperty; +import org.junit.jupiter.api.util.RestoreSystemProperties; +import org.junit.jupiter.api.util.SetSystemProperty; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.ValueSource; + +public class SystemPropertyExtensionDemo { + + // tag::systemproperty_clear_simple[] + @Test + @ClearSystemProperty(key = "some property") + void testClearingProperty() { + assertThat(System.getProperty("some property")).isNull(); + } + // end::systemproperty_clear_simple[] + + // tag::systemproperty_set_simple[] + @Test + @SetSystemProperty(key = "some property", value = "new value") + void testSettingProperty() { + assertThat(System.getProperty("some property")).isEqualTo("new value"); + } + // end::systemproperty_set_simple[] + + // tag::systemproperty_using_set_and_clear[] + @Test + @ClearSystemProperty(key = "1st property") + @ClearSystemProperty(key = "2nd property") + @SetSystemProperty(key = "3rd property", value = "new value") + void testClearingAndSettingProperty() { + assertThat(System.getProperty("1st property")).isNull(); + assertThat(System.getProperty("2nd property")).isNull(); + assertThat(System.getProperty("3rd property")).isEqualTo("new value"); + } + // end::systemproperty_using_set_and_clear[] + + @Nested + // tag::systemproperty_using_at_class_level[] + @ClearSystemProperty(key = "some property") + class MySystemPropertyTest { + + @Test + @SetSystemProperty(key = "some property", value = "new value") + void clearedAtClasslevel() { + assertThat(System.getProperty("some property")).isEqualTo("new value"); + } + + } + // end::systemproperty_using_at_class_level[] + + // tag::systemproperty_restore_test[] + @ParameterizedTest + @ValueSource(strings = { "foo", "bar" }) + @RestoreSystemProperties + void parameterizedTest(String value) { + System.setProperty("some parameterized property", value); + System.setProperty("some other dynamic property", "my code calculates somehow"); + } + // end::systemproperty_restore_test[] + + @Nested + @TestClassOrder(ClassOrderer.OrderAnnotation.class) + class SystemPropertyRestoreExample { + + @Nested + @Order(1) + @TestInstance(TestInstance.Lifecycle.PER_CLASS) + // tag::systemproperty_class_restore_setup[] + @RestoreSystemProperties + class MySystemPropertyRestoreTest { + + @BeforeAll + void beforeAll() { + System.setProperty("A", "A value"); + } + + @BeforeEach + void beforeEach() { + System.setProperty("B", "B value"); + } + + @Test + void isolatedTest1() { + System.setProperty("C", "C value"); + } + + @Test + void isolatedTest2() { + assertThat(System.getProperty("A")).isEqualTo("A value"); + assertThat(System.getProperty("B")).isEqualTo("B value"); + + // Class-level @RestoreSystemProperties restores "C" to original state + assertThat(System.getProperty("C")).isNull(); + } + + } + // end::systemproperty_class_restore_setup[] + + @Nested + @Order(2) + // tag::systemproperty_class_restore_isolated_class[] + @ReadsSystemProperty + class SomeOtherTestClass { + + @Test + void isolatedTest() { + assertThat(System.getProperty("A")).isNull(); + assertThat(System.getProperty("B")).isNull(); + assertThat(System.getProperty("C")).isNull(); + } + + } + + // end::systemproperty_class_restore_isolated_class[] + } + + // tag::systemproperty_method_combine_all_test[] + @ParameterizedTest + @ValueSource(ints = { 100, 500, 1000 }) + @RestoreSystemProperties + @SetSystemProperty(key = "DISABLE_CACHE", value = "TRUE") + @ClearSystemProperty(key = "COPYWRITE_OVERLAY_TEXT") + void imageGenerationTest(int imageSize) { + System.setProperty("IMAGE_SIZE", String.valueOf(imageSize)); // Requires restore + + // Test your image generation utility with the current system properties + } + // end::systemproperty_method_combine_all_test[] + +} diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/util/AbstractEntryBasedExtension.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/util/AbstractEntryBasedExtension.java new file mode 100644 index 000000000000..d55688233c38 --- /dev/null +++ b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/util/AbstractEntryBasedExtension.java @@ -0,0 +1,333 @@ +/* + * Copyright 2015-2025 the original author or authors. + * + * All rights reserved. This program and the accompanying materials are + * made available under the terms of the Eclipse Public License v2.0 which + * accompanies this distribution and is available at + * + * https://www.eclipse.org/legal/epl-v20.html + */ + +package org.junit.jupiter.api.util; + +import static java.util.stream.Collectors.joining; +import static java.util.stream.Collectors.toMap; +import static org.junit.jupiter.api.util.SystemPropertyExtensionUtils.findAllContexts; + +import java.lang.annotation.Annotation; +import java.lang.reflect.AnnotatedElement; +import java.lang.reflect.ParameterizedType; +import java.lang.reflect.Type; +import java.util.Collection; +import java.util.Collections; +import java.util.HashMap; +import java.util.HashSet; +import java.util.List; +import java.util.Map; +import java.util.Properties; +import java.util.Set; +import java.util.function.Function; +import java.util.stream.Stream; + +import org.junit.jupiter.api.extension.AfterAllCallback; +import org.junit.jupiter.api.extension.AfterEachCallback; +import org.junit.jupiter.api.extension.BeforeAllCallback; +import org.junit.jupiter.api.extension.BeforeEachCallback; +import org.junit.jupiter.api.extension.ExtensionConfigurationException; +import org.junit.jupiter.api.extension.ExtensionContext; +import org.junit.jupiter.api.extension.ExtensionContext.Namespace; +import org.junit.jupiter.api.extension.ExtensionContext.Store; +import org.junit.platform.commons.support.AnnotationSupport; + +/** + * An abstract base class for entry-based extensions, where entries (key-value + * pairs) can be cleared, set, or restored. + * + * @param The entry key type. + * @param The entry value type. + * @param The clear annotation type. + * @param The set annotation type. + * @param The restore annotation type. + */ +abstract class AbstractEntryBasedExtension + implements BeforeEachCallback, AfterEachCallback, BeforeAllCallback, AfterAllCallback { + + /** + * Key to indicate storage is for an incremental backup object. + */ + private static final String INCREMENTAL_KEY = "inc"; + + /** + * Key to indicate storage is for a complete backup object. + */ + private static final String COMPLETE_KEY = "full"; + + @Override + public void beforeAll(ExtensionContext context) { + applyForAllContexts(context); + } + + @Override + public void beforeEach(ExtensionContext context) { + applyForAllContexts(context); + } + + private void applyForAllContexts(ExtensionContext originalContext) { + AnnotatedElement element = originalContext.getElement().orElse(null); + boolean fullRestore = AnnotationSupport.findAnnotation(element, getRestoreAnnotationType()).isPresent(); + + if (fullRestore) { + Properties bulk = this.prepareToEnterRestorableContext(); + storeOriginalCompleteEntries(originalContext, bulk); + } + + /* + * We cannot use PioneerAnnotationUtils#findAllEnclosingRepeatableAnnotations(ExtensionContext, Class) or the + * like as clearing and setting might interfere. Therefore, we have to apply the extension from the outermost + * to the innermost ExtensionContext. + */ + List contexts = findAllContexts(originalContext); + Collections.reverse(contexts); + contexts.forEach(currentContext -> clearAndSetEntries(currentContext, originalContext, !fullRestore)); + } + + private void clearAndSetEntries(ExtensionContext currentContext, ExtensionContext originalContext, + boolean doIncrementalBackup) { + currentContext.getElement().ifPresent(element -> { + Set entriesToClear; + Map entriesToSet; + + try { + entriesToClear = findEntriesToClear(element); + entriesToSet = findEntriesToSet(element); + preventClearAndSetSameEntries(entriesToClear, entriesToSet.keySet()); + } + catch (IllegalStateException ex) { + throw new ExtensionConfigurationException("Don't clear/set the same entry more than once.", ex); + } + + if (entriesToClear.isEmpty() && entriesToSet.isEmpty()) + return; + + reportWarning(currentContext); + + // Only backup original values if we didn't already do bulk storage of the original state + if (doIncrementalBackup) { + storeOriginalIncrementalEntries(originalContext, entriesToClear, entriesToSet.keySet()); + } + + clearEntries(entriesToClear); + setEntries(entriesToSet); + }); + } + + private Set findEntriesToClear(AnnotatedElement element) { + return findAnnotations(element, getClearAnnotationType()).map(clearKeyMapper()).collect( + SystemPropertyExtensionUtils.distinctToSet()); + } + + private Map findEntriesToSet(AnnotatedElement element) { + return findAnnotations(element, getSetAnnotationType()).collect(toMap(setKeyMapper(), setValueMapper())); + } + + private Stream findAnnotations(AnnotatedElement element, Class clazz) { + return AnnotationSupport.findRepeatableAnnotations(element, clazz).stream(); + } + + @SuppressWarnings("unchecked") + private Class getClearAnnotationType() { + return (Class) getActualTypeArgumentAt(2); + } + + @SuppressWarnings("unchecked") + private Class getSetAnnotationType() { + return (Class) getActualTypeArgumentAt(3); + } + + @SuppressWarnings("unchecked") + private Class getRestoreAnnotationType() { + return (Class) getActualTypeArgumentAt(4); + } + + private Type getActualTypeArgumentAt(int index) { + ParameterizedType abstractEntryBasedExtensionType = (ParameterizedType) getClass().getGenericSuperclass(); + Type type = abstractEntryBasedExtensionType.getActualTypeArguments()[index]; + if (type instanceof ParameterizedType parameterizedType) { + return parameterizedType.getRawType(); + } + else { + return type; + } + } + + private void preventClearAndSetSameEntries(Collection entriesToClear, Collection entriesToSet) { + String duplicateEntries = entriesToClear.stream().filter(entriesToSet::contains).map(Object::toString).collect( + joining(", ")); + if (!duplicateEntries.isEmpty()) + throw new IllegalStateException( + "Cannot clear and set the following entries at the same time: " + duplicateEntries); + } + + private void storeOriginalIncrementalEntries(ExtensionContext context, Collection entriesToClear, + Collection entriesToSet) { + getStore(context).put(getStoreKey(context, INCREMENTAL_KEY), new EntriesBackup(entriesToClear, entriesToSet)); + } + + private void storeOriginalCompleteEntries(ExtensionContext context, Properties originalEntries) { + getStore(context).put(getStoreKey(context, COMPLETE_KEY), originalEntries); + } + + /** + * Restore the complete original state of the entries as they were prior to this {@code ExtensionContext}, + * if the complete state was initially stored in a before all/each event. + * + * @param context The {@code ExtensionContext} which may have a bulk backup stored. + * @return true if a complete backup exists and was used to restore, false if not. + */ + private boolean restoreOriginalCompleteEntries(ExtensionContext context) { + Properties bulk = getStore(context).get(getStoreKey(context, COMPLETE_KEY), Properties.class); + + if (bulk == null) { + // No complete backup - false will let the caller know to continue w/ an incremental restore + return false; + } + else { + this.prepareToExitRestorableContext(bulk); + return true; + } + } + + private void clearEntries(Collection entriesToClear) { + entriesToClear.forEach(this::clearEntry); + } + + private void setEntries(Map entriesToSet) { + entriesToSet.forEach(this::setEntry); + } + + @Override + public void afterEach(ExtensionContext context) { + restoreForAllContexts(context); + } + + @Override + public void afterAll(ExtensionContext context) { + restoreForAllContexts(context); + } + + private void restoreForAllContexts(ExtensionContext originalContext) { + // Try a complete restore first + if (!restoreOriginalCompleteEntries(originalContext)) { + // A complete backup is not available, so restore incrementally from innermost to outermost + findAllContexts(originalContext).forEach(__ -> restoreOriginalIncrementalEntries(originalContext)); + } + } + + private void restoreOriginalIncrementalEntries(ExtensionContext originalContext) { + getStore(originalContext).getOrDefault(getStoreKey(originalContext, INCREMENTAL_KEY), EntriesBackup.class, + new EntriesBackup()).restoreBackup(); + } + + private Store getStore(ExtensionContext context) { + return context.getStore(Namespace.create(getClass())); + } + + private String getStoreKey(ExtensionContext context, String discriminator) { + return context.getUniqueId() + "-" + this.getClass().getSimpleName() + "-" + discriminator; + } + + private class EntriesBackup { + + private final Set entriesToClear = new HashSet<>(); + private final Map entriesToSet = new HashMap<>(); + + EntriesBackup() { + // empty backup + } + + EntriesBackup(Collection entriesToClear, Collection entriesToSet) { + Stream.concat(entriesToClear.stream(), entriesToSet.stream()).forEach(entry -> { + V backup = AbstractEntryBasedExtension.this.getEntry(entry); + if (backup == null) + this.entriesToClear.add(entry); + else + this.entriesToSet.put(entry, backup); + }); + } + + void restoreBackup() { + entriesToClear.forEach(AbstractEntryBasedExtension.this::clearEntry); + entriesToSet.forEach(AbstractEntryBasedExtension.this::setEntry); + } + + } + + /** + * @return Mapper function to get the key from a clear annotation. + */ + protected abstract Function clearKeyMapper(); + + /** + * @return Mapper function to get the key from a set annotation. + */ + protected abstract Function setKeyMapper(); + + /** + * @return Mapper function to get the value from a set annotation. + */ + protected abstract Function setValueMapper(); + + /** + * Removes the entry indicated by the specified key. + */ + protected abstract void clearEntry(K key); + + /** + * Gets the entry indicated by the specified key. + */ + protected abstract V getEntry(K key); + + /** + * Sets the entry indicated by the specified key. + */ + protected abstract void setEntry(K key, V value); + + /** + * Reports a warning about potentially unsafe practices. + */ + protected void reportWarning(ExtensionContext context) { + // nothing reported by default + } + + /** + * Prepare the entry-based environment for entering a context that must be restorable. + * + *

Implementations may choose one of two strategies:

+ * + *
    + *
  • Post swap, where the original entry-based environment is left in place and a clone is returned. + * In this case {@link #prepareToExitRestorableContext} will restore the clone. + *
  • Preemptive swap, where the current entry-based environment is replaced with a clone and the + * original is returned. + * In this case the {@link #prepareToExitRestorableContext} will restore the original environment.
    • + *
+ * + *

The returned {@code Properties} must not be null and its key-value pairs must follow the rules for + * entries of its type. E.g., environment variables contain only Strings while System {@code Properties} + * may contain Objects.

+ * + * @return A non-null {@code Properties} that contains all entries of the entry environment. + */ + protected abstract Properties prepareToEnterRestorableContext(); + + /** + * Prepare to exit a restorable context for the entry based environment. + * + *

The entry environment will be restored to the state passed in as {@code Properties}. + * The {@code Properties} entries must follow the rules for entries of this environment, + * e.g., environment variables contain only Strings while System {@code Properties} may contain Objects.

+ * + * @param entries A non-null {@code Properties} that contains all entries of the entry environment. + */ + protected abstract void prepareToExitRestorableContext(Properties entries); +} diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/util/ClearSystemProperty.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/util/ClearSystemProperty.java new file mode 100644 index 000000000000..b0db6a4ffa8f --- /dev/null +++ b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/util/ClearSystemProperty.java @@ -0,0 +1,72 @@ +/* + * Copyright 2015-2025 the original author or authors. + * + * All rights reserved. This program and the accompanying materials are + * made available under the terms of the Eclipse Public License v2.0 which + * accompanies this distribution and is available at + * + * https://www.eclipse.org/legal/epl-v20.html + */ + +package org.junit.jupiter.api.util; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Inherited; +import java.lang.annotation.Repeatable; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +import org.apiguardian.api.API; + +/** + * {@code @ClearSystemProperty} is a JUnit Jupiter extension to clear the value + * of a system property for a test execution. + * + *

The key of the system property to be cleared must be specified via {@link #key()}. + * After the annotated element has been executed, the original value or the value of the + * higher-level container is restored.

+ * + *

{@code ClearSystemProperty} can be used on the method and on the class level. + * It is repeatable and inherited from higher-level containers. If a class is + * annotated, the configured property will be cleared before every test inside that + * class.

+ * + * + * + *

For more details and examples, see + * the documentation on @ClearSystemProperty and @SetSystemProperty.

+ * + * @since 6.1.0 + */ +@Retention(RetentionPolicy.RUNTIME) +@Target({ ElementType.METHOD, ElementType.TYPE }) +@Inherited +@Repeatable(ClearSystemProperty.ClearSystemProperties.class) +@WritesSystemProperty +@API(status = API.Status.STABLE, since = "6.1") +public @interface ClearSystemProperty { + + /** + * The key of the system property to be cleared. + */ + String key(); + + /** + * Containing annotation of repeatable {@code @ClearSystemProperty}. + */ + @Retention(RetentionPolicy.RUNTIME) + @Target({ ElementType.METHOD, ElementType.TYPE }) + @Inherited + @WritesSystemProperty + @API(status = API.Status.STABLE, since = "6.1") + @interface ClearSystemProperties { + + ClearSystemProperty[] value(); + + } + +} diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/util/ReadsSystemProperty.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/util/ReadsSystemProperty.java new file mode 100644 index 000000000000..c74050909748 --- /dev/null +++ b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/util/ReadsSystemProperty.java @@ -0,0 +1,43 @@ +/* + * Copyright 2015-2025 the original author or authors. + * + * All rights reserved. This program and the accompanying materials are + * made available under the terms of the Eclipse Public License v2.0 which + * accompanies this distribution and is available at + * + * https://www.eclipse.org/legal/epl-v20.html + */ + +package org.junit.jupiter.api.util; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Inherited; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +import org.apiguardian.api.API; +import org.junit.jupiter.api.parallel.ResourceAccessMode; +import org.junit.jupiter.api.parallel.ResourceLock; +import org.junit.jupiter.api.parallel.Resources; + +/** + * Marks tests that read system properties but don't use the system property extension themselves. + * + *

During + * parallel test execution, + * all tests annotated with {@link ClearSystemProperty}, {@link SetSystemProperty}, {@link ReadsSystemProperty}, and {@link WritesSystemProperty} + * are scheduled in a way that guarantees correctness under mutation of shared global state.

+ * + *

For more details and examples, see + * the documentation on @ClearSystemProperty and @SetSystemProperty.

+ * + * @since 6.1.0 + */ +@Retention(RetentionPolicy.RUNTIME) +@Target({ ElementType.CONSTRUCTOR, ElementType.METHOD, ElementType.PACKAGE, ElementType.TYPE }) +@Inherited +@ResourceLock(value = Resources.SYSTEM_PROPERTIES, mode = ResourceAccessMode.READ) +@API(status = API.Status.STABLE, since = "6.1") +public @interface ReadsSystemProperty { +} diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/util/RestoreSystemProperties.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/util/RestoreSystemProperties.java new file mode 100644 index 000000000000..3de1b2487847 --- /dev/null +++ b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/util/RestoreSystemProperties.java @@ -0,0 +1,71 @@ +/* + * Copyright 2015-2025 the original author or authors. + * + * All rights reserved. This program and the accompanying materials are + * made available under the terms of the Eclipse Public License v2.0 which + * accompanies this distribution and is available at + * + * https://www.eclipse.org/legal/epl-v20.html + */ + +package org.junit.jupiter.api.util; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Inherited; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +import org.apiguardian.api.API; + +/** + * {@code @RestoreSystemProperties} is a JUnit Jupiter extension to restore the entire set of + * system properties to the original value, or the value of the higher-level container, after the + * annotated element is complete. + * + *

Use this annotation when there is a need programmatically modify system properties in a test + * method or in {@code @BeforeAll} / {@code @BeforeEach} blocks. + * To simply set or clear a system property, consider {@link SetSystemProperty @SetSystemProperty} or + * {@link ClearSystemProperty @ClearSystemProperty} instead.

+ * + *

{@code RestoreSystemProperties} can be used on the method and on the class level. + * When placed on a test method, a snapshot of system properties is stored prior to that test. + * The snapshot is created before any {@code @BeforeEach} blocks in scope and before any + * {@link SetSystemProperty @SetSystemProperty} or {@link ClearSystemProperty @ClearSystemProperty} + * annotations on that method. After the test, system properties are restored from the + * snapshot after any {@code @AfterEach} have completed. + * + *

When placed on a test class, a snapshot of system properties is stored prior to any + * {@code @BeforeAll} blocks in scope and before any {@link SetSystemProperty @SetSystemProperty} + * or {@link ClearSystemProperty @ClearSystemProperty} annotations on that class. + * After the test class completes, system properties are restored from the snapshot after any + * {@code @AfterAll} blocks have completed. + * In addition, a class level annotation is inherited by each test method just as if each one was + * annotated with {@code RestoreSystemProperties}. + * + *

During + * parallel test execution, + * all tests annotated with {@link RestoreSystemProperties}, {@link SetSystemProperty}, + * {@link ReadsSystemProperty}, and {@link WritesSystemProperty} + * are scheduled in a way that guarantees correctness under mutation of shared global state.

+ * + *

For more details and examples, see + * the documentation on + * @ClearSystemProperty, @SetSystemProperty, and @RestoreSystemProperties.

+ * + *

Note: System properties are normally just a hashmap of strings, however, it is + * technically possible to store non-string values and create nested {@code Properties} with inherited / + * default values. Within the context of an element annotated with {@link RestoreSystemProperties}, + * non-String values are not preserved and the structure of nested defaults are flattened. + * After the annotated context is exited, the original Properties object is restored with + * all its potential (non-standard) richness.

+ * + * @since 6.1.0 + */ +@Retention(RetentionPolicy.RUNTIME) +@Target({ ElementType.METHOD, ElementType.TYPE }) +@Inherited +@WritesSystemProperty +@API(status = API.Status.STABLE, since = "6.1") +public @interface RestoreSystemProperties { +} diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/util/SetSystemProperty.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/util/SetSystemProperty.java new file mode 100644 index 000000000000..93565323ce94 --- /dev/null +++ b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/util/SetSystemProperty.java @@ -0,0 +1,80 @@ +/* + * Copyright 2015-2025 the original author or authors. + * + * All rights reserved. This program and the accompanying materials are + * made available under the terms of the Eclipse Public License v2.0 which + * accompanies this distribution and is available at + * + * https://www.eclipse.org/legal/epl-v20.html + */ + +package org.junit.jupiter.api.util; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Inherited; +import java.lang.annotation.Repeatable; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +import org.apiguardian.api.API; + +/** + * {@code @SetSystemProperty} is a JUnit Jupiter extension to set the value of a + * system property for a test execution. + * + *

The key and value of the system property to be set must be specified via + * {@link #key()} and {@link #value()}. After the annotated method has been + * executed, the original value or the value of the higher-level container is + * restored.

+ * + *

{@code SetSystemProperty} can be used on the method and on the class level. + * It is repeatable and inherited from higher-level containers. If a class is + * annotated, the configured property will be set before every test inside that + * class. Any method-level configurations will override the class-level + * configurations.

+ * + *

During + * parallel test execution, + * all tests annotated with {@link ClearSystemProperty}, {@link SetSystemProperty}, {@link ReadsSystemProperty}, + * and {@link WritesSystemProperty} are scheduled in a way that guarantees correctness under mutation of shared global + * state.

+ * + *

For more details and examples, see + * the documentation on @ClearSystemProperty and @SetSystemProperty.

+ * + * @since 6.1.0 + */ +@Retention(RetentionPolicy.RUNTIME) +@Target({ ElementType.METHOD, ElementType.TYPE }) +@Inherited +@Repeatable(SetSystemProperty.SetSystemProperties.class) +@WritesSystemProperty +@API(status = API.Status.STABLE, since = "6.1") +public @interface SetSystemProperty { + + /** + * The key of the system property to be set. + */ + String key(); + + /** + * The value of the system property to be set. + */ + String value(); + + /** + * Containing annotation of repeatable {@code @SetSystemProperty}. + */ + @Retention(RetentionPolicy.RUNTIME) + @Target({ ElementType.METHOD, ElementType.TYPE }) + @Inherited + @WritesSystemProperty + @API(status = API.Status.STABLE, since = "6.1") + @interface SetSystemProperties { + + SetSystemProperty[] value(); + + } + +} diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/util/SystemPropertyExtension.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/util/SystemPropertyExtension.java new file mode 100644 index 000000000000..b0fceefd3f5a --- /dev/null +++ b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/util/SystemPropertyExtension.java @@ -0,0 +1,115 @@ +/* + * Copyright 2015-2025 the original author or authors. + * + * All rights reserved. This program and the accompanying materials are + * made available under the terms of the Eclipse Public License v2.0 which + * accompanies this distribution and is available at + * + * https://www.eclipse.org/legal/epl-v20.html + */ + +package org.junit.jupiter.api.util; + +import java.util.Properties; +import java.util.function.Function; + +import org.apiguardian.api.API; + +@API(status = API.Status.STABLE, since = "6.1") +public class SystemPropertyExtension extends + AbstractEntryBasedExtension { + + @Override + protected Function clearKeyMapper() { + return ClearSystemProperty::key; + } + + @Override + protected Function setKeyMapper() { + return SetSystemProperty::key; + } + + @Override + protected Function setValueMapper() { + return SetSystemProperty::value; + } + + @Override + protected void clearEntry(String key) { + System.clearProperty(key); + } + + @Override + protected String getEntry(String key) { + return System.getProperty(key); + } + + @Override + protected void setEntry(String key, String value) { + System.setProperty(key, value); + } + + /** + * This implementation uses the "Preemptive swap" strategy. + * + *

Since {@link Properties} allows a wrapped default instance and Object values, + * cloning is difficult:

+ * + *
    + *
  • It is difficult to tell which values are defaults and which are "top level", + * thus a clone might contain the same effective values, but be flattened without defaults.
    • + *
  • Object values in a wrapped default instance cannot be accessed without reflection.
    • + *
+ * + *

The "Preemptive swap" strategy ensure that the original Properties are restored, however + * complex they were. Any artifacts resulting from a flattened default structure are limited + * to the context of the test.

+ * + *

See {@link AbstractEntryBasedExtension#prepareToEnterRestorableContext} for more details.

+ * + * @return The original {@link System#getProperties} object + */ + @Override + protected Properties prepareToEnterRestorableContext() { + Properties current = System.getProperties(); + Properties clone = createEffectiveClone(current); + + System.setProperties(clone); + + return current; + } + + @Override + protected void prepareToExitRestorableContext(Properties properties) { + System.setProperties(properties); + } + + /** + * A clone of the String values of the passed {@code Properties}, including defaults. + * + *

The clone will have the same effective values, but may not use the same nested + * structure as the original. Object values, which are technically possible, + * are not included in the clone.

+ * + * @param original {@code Properties} to be cloned. + * @return A new {@code Properties} instance containing the same effective entries as the original. + */ + static Properties createEffectiveClone(Properties original) { + Properties clone = new Properties(); + + // This implementation is used because: + // System.getProperties() returns the actual Properties object, not a copy. + // Clone doesn't include nested defaults, but propertyNames() does. + original.propertyNames().asIterator().forEachRemaining(k -> { + String v = original.getProperty(k.toString()); + + if (v != null) { + // v will be null if the actual value was an object + clone.put(k, original.getProperty(k.toString())); + } + }); + + return clone; + } + +} diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/util/SystemPropertyExtensionUtils.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/util/SystemPropertyExtensionUtils.java new file mode 100644 index 000000000000..2febac6876d3 --- /dev/null +++ b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/util/SystemPropertyExtensionUtils.java @@ -0,0 +1,62 @@ +/* + * Copyright 2015-2025 the original author or authors. + * + * All rights reserved. This program and the accompanying materials are + * made available under the terms of the Eclipse Public License v2.0 which + * accompanies this distribution and is available at + * + * https://www.eclipse.org/legal/epl-v20.html + */ + +package org.junit.jupiter.api.util; + +import java.util.ArrayList; +import java.util.HashSet; +import java.util.List; +import java.util.Set; +import java.util.stream.Collector; + +import org.junit.jupiter.api.extension.ExtensionContext; + +/** + * Utility methods for the SystemPropertiesExtension. + */ +class SystemPropertyExtensionUtils { + + private SystemPropertyExtensionUtils() { + // private constructor to prevent instantiation of utility class + } + + /** + * A {@link java.util.stream.Collectors#toSet() toSet} collector that throws an {@link IllegalStateException} + * on duplicate elements (according to {@link Object#equals(Object) equals}). + */ + public static Collector, Set> distinctToSet() { + return Collector.of(HashSet::new, SystemPropertyExtensionUtils::addButThrowIfDuplicate, (left, right) -> { + right.forEach(element -> addButThrowIfDuplicate(left, element)); + return left; + }); + } + + private static void addButThrowIfDuplicate(Set set, T element) { + boolean newElement = set.add(element); + if (!newElement) { + throw new IllegalStateException("Duplicate element '" + element + "'."); + } + } + + /** + * Find all (parent) {@code ExtensionContext}s via {@link ExtensionContext#getParent()}. + * + * @param context the context for which to find all (parent) contexts; never {@code null} + * @return a list of all contexts, "outwards" in the {@link ExtensionContext#getParent() getParent}-order, + * beginning with the given context; never {@code null} or empty + */ + public static List findAllContexts(ExtensionContext context) { + List allContexts = new ArrayList<>(); + for (var c = context; c != null; c = c.getParent().orElse(null)) { + allContexts.add(c); + } + return allContexts; + } +} diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/util/WritesSystemProperty.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/util/WritesSystemProperty.java new file mode 100644 index 000000000000..0f36d10897f8 --- /dev/null +++ b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/util/WritesSystemProperty.java @@ -0,0 +1,43 @@ +/* + * Copyright 2015-2025 the original author or authors. + * + * All rights reserved. This program and the accompanying materials are + * made available under the terms of the Eclipse Public License v2.0 which + * accompanies this distribution and is available at + * + * https://www.eclipse.org/legal/epl-v20.html + */ + +package org.junit.jupiter.api.util; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Inherited; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +import org.apiguardian.api.API; +import org.junit.jupiter.api.parallel.ResourceAccessMode; +import org.junit.jupiter.api.parallel.ResourceLock; +import org.junit.jupiter.api.parallel.Resources; + +/** + * Marks tests that write system properties but don't use the system property extension themselves. + * + *

During + * parallel test execution, + * all tests annotated with {@link ClearSystemProperty}, {@link SetSystemProperty}, {@link ReadsSystemProperty}, and {@link WritesSystemProperty} + * are scheduled in a way that guarantees correctness under mutation of shared global state.

+ * + *

For more details and examples, see + * the documentation on @ClearSystemProperty and @SetSystemProperty.

+ * + * @since 6.1.0 + */ +@Retention(RetentionPolicy.RUNTIME) +@Target({ ElementType.CONSTRUCTOR, ElementType.METHOD, ElementType.PACKAGE, ElementType.TYPE }) +@Inherited +@ResourceLock(value = Resources.SYSTEM_PROPERTIES, mode = ResourceAccessMode.READ_WRITE) +@API(status = API.Status.STABLE, since = "6.1") +public @interface WritesSystemProperty { +} diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/util/package-info.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/util/package-info.java index 2106ecf7df7c..7779e53db48f 100644 --- a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/util/package-info.java +++ b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/util/package-info.java @@ -3,6 +3,7 @@ * * @see org.junit.jupiter.api.util.DefaultLocale * @see org.junit.jupiter.api.util.DefaultTimeZone + * @see org.junit.jupiter.api.util.SetSystemProperty */ @NullMarked diff --git a/jupiter-tests/src/test/java/org/junit/jupiter/api/util/PropertiesAssertions.java b/jupiter-tests/src/test/java/org/junit/jupiter/api/util/PropertiesAssertions.java new file mode 100644 index 000000000000..7b5e8230ef11 --- /dev/null +++ b/jupiter-tests/src/test/java/org/junit/jupiter/api/util/PropertiesAssertions.java @@ -0,0 +1,210 @@ +/* + * Copyright 2015-2025 the original author or authors. + * + * All rights reserved. This program and the accompanying materials are + * made available under the terms of the Eclipse Public License v2.0 which + * accompanies this distribution and is available at + * + * https://www.eclipse.org/legal/epl-v20.html + */ + +package org.junit.jupiter.api.util; + +import java.lang.reflect.Field; +import java.util.Properties; + +import org.assertj.core.api.AbstractAssert; +import org.jspecify.annotations.Nullable; +import org.junit.platform.commons.support.HierarchyTraversalMode; +import org.junit.platform.commons.support.ReflectionSupport; + +/** + * Allows comparison of {@link Properties} with optional awareness of their structure, + * rather than just treating them as Maps. Object values, which are marginally supported + * by {@code Properties}, are supported in assertions as much as possible. + */ +public class PropertiesAssertions extends AbstractAssert { + + /** + * Make an assertion on a {@link Properties} instance. + * + * @param actual The {@link Properties} instance the assertion is made with respect to + * @return Assertion instance + */ + public static PropertiesAssertions assertThat(Properties actual) { + return new PropertiesAssertions(actual); + } + + PropertiesAssertions(Properties actual) { + super(actual, PropertiesAssertions.class); + } + + /** + * Assert Properties has the same effective values as the passed instance, but not + * the same nested default structure. + * + *

Properties are considered effectively equal if they have the same property + * names returned by {@code Properties.propertyNames()} and the same values returned by + * {@code getProperty(name)}. Properties may come from the properties instance itself, + * or from a nested default instance, indiscriminately. + * + *

Properties partially supports object values, but return null for {@code getProperty(name)} + * when the value is a non-string. This assertion follows the same rules: Any non-String + * value is considered null for comparison purposes. + * + * @param expected The actual is expected to be effectively the same as this Properties + * @return Assertion instance + */ + public PropertiesAssertions isEffectivelyEqualsTo(Properties expected) { + + // Compare values present in actual + actual.propertyNames().asIterator().forEachRemaining(k -> { + + String kStr = k.toString(); + + String actValue = actual.getProperty(kStr); + String expValue = expected.getProperty(kStr); + + if (actValue == null) { + if (expValue != null) { + // An object value is the only way to get a null from getProperty() + throw failure("For the property '<%s>', " + + "the actual value was an object but the expected the string '<%s>'.", + k, expValue); + } + } + else if (!actValue.equals(expValue)) { + throw failure("For the property '<%s>', the actual value was <%s> but <%s> was expected", k, actValue, + expValue); + } + }); + + // Compare values present in expected - Anything not matching must not have been present in actual + expected.propertyNames().asIterator().forEachRemaining(k -> { + + String kStr = k.toString(); + + String actValue = actual.getProperty(kStr); + String expValue = expected.getProperty(kStr); + + if (expValue == null) { + if (actValue != null) { + + // An object value is the only way to get a null from getProperty() + throw failure("For the property '<%s>', " + + "the actual value was the string '<%s>', but an object was expected.", + k, actValue); + } + } + else if (!expValue.equals(actValue)) { + throw failure("The property <%s> was expected to be <%s>, but was missing", k, expValue); + } + }); + + return this; + } + + /** + * The converse of isEffectivelyEqualTo. + * + * @param expected The actual is expected to NOT be effectively equal to this Properties + * @return Assertion instance + */ + public PropertiesAssertions isNotEffectivelyEqualTo(Properties expected) { + try { + isEffectivelyEqualsTo(expected); + } + catch (AssertionError ae) { + return this; // Expected + } + + throw failure("The actual Properties should not be effectively equal to the expected one."); + } + + /** + * Compare values directly present in Properties and recursively into default Properties. + * + * @param expected The actual is expected to be strictly equal to this Properties + * @return Assertion instance + */ + public PropertiesAssertions isStrictlyEqualTo(Properties expected) { + + // Compare values present in actual + actual.keySet().forEach(k -> { + + // not null check only added, because "compileTestJava"-goal does not recognize that they can't be null + if (null != actual.get(k) && null != expected.get(k)) { + if (!actual.get(k).equals(expected.get(k))) { + throw failure("For the property <%s> the actual value was <%s> but <%s> was expected", k, + actual.get(k), expected.get(k)); + } + } + }); + + // Compare values present in expected - Anything not matching must not have been present in actual + expected.keySet().forEach(k -> { + // not null check only added, because "compileTestJava"-goal does not recognize that they can't be null + if (null != actual.get(k) && null != expected.get(k)) { + if (!expected.get(k).equals(actual.get(k))) { + throw failure("The property <%s> was expected to be <%s>, but was missing", k, expected.get(k)); + } + } + }); + + // Dig down into the nested defaults + Properties actualDefault = getDefaultFieldValue(actual); + Properties expectedDefault = getDefaultFieldValue(expected); + + if (actualDefault != null && expectedDefault != null) { + return new PropertiesAssertions(actualDefault).isStrictlyEqualTo(expectedDefault); + } + else if (actualDefault != null) { + throw failure("The actual Properties had non-null defaults, but none were expected"); + } + else if (expectedDefault != null) { + throw failure("The expected Properties had non-null defaults, but none were in actual"); + } + + return this; + } + + /** + * Simple converse of isStrictlyEqualTo. + * + * @param expected The actual is expected to NOT be strictly equal to this Properties + * @return Assertion instance + */ + public PropertiesAssertions isNotStrictlyEqualTo(Properties expected) { + try { + isStrictlyEqualTo(expected); + } + catch (AssertionError ae) { + return this; // Expected + } + + throw failure("The actual Properties should not be strictly the same as the expected one."); + } + + /** + * Use reflection to grab the {@code defaults} field from a java.utils.Properties instance. + * + * @param parent The Properties to fetch default values from + * @return The Properties instance that was stored as defaults in the parent. + */ + protected @Nullable Properties getDefaultFieldValue(Properties parent) { + Field field = ReflectionSupport.findFields(Properties.class, f -> f.getName().equals("defaults"), + HierarchyTraversalMode.BOTTOM_UP).stream().findFirst().get(); + + field.setAccessible(true); + + try { + return (Properties) ReflectionSupport.tryToReadFieldValue(field, parent).get(); + } + catch (Exception e) { + throw new RuntimeException("Unable to access the java.util.Properties.defaults field by reflection. " + + "Please adjust your local environment to allow this.", + e); + } + } + +} diff --git a/jupiter-tests/src/test/java/org/junit/jupiter/api/util/SystemPropertyExtensionTests.java b/jupiter-tests/src/test/java/org/junit/jupiter/api/util/SystemPropertyExtensionTests.java new file mode 100644 index 000000000000..347a451bdb4f --- /dev/null +++ b/jupiter-tests/src/test/java/org/junit/jupiter/api/util/SystemPropertyExtensionTests.java @@ -0,0 +1,727 @@ +/* + * Copyright 2015-2025 the original author or authors. + * + * All rights reserved. This program and the accompanying materials are + * made available under the terms of the Eclipse Public License v2.0 which + * accompanies this distribution and is available at + * + * https://www.eclipse.org/legal/epl-v20.html + */ + +package org.junit.jupiter.api.util; + +import static org.assertj.core.api.Assertions.assertThat; +import static org.junit.jupiter.api.parallel.ExecutionMode.SAME_THREAD; +import static org.junit.jupiter.api.util.PropertiesAssertions.assertThat; +import static org.junit.platform.engine.discovery.DiscoverySelectors.selectMethod; +import static org.junit.platform.testkit.engine.EventConditions.finishedWithFailure; +import static org.junit.platform.testkit.engine.TestExecutionResultConditions.instanceOf; +import static org.junit.platform.testkit.engine.TestExecutionResultConditions.message; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Inherited; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; +import java.util.Properties; + +import org.junit.jupiter.api.AfterAll; +import org.junit.jupiter.api.AfterEach; +import org.junit.jupiter.api.BeforeAll; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.ClassOrderer; +import org.junit.jupiter.api.Disabled; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.MethodOrderer.OrderAnnotation; +import org.junit.jupiter.api.Nested; +import org.junit.jupiter.api.Order; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.TestClassOrder; +import org.junit.jupiter.api.TestInstance; +import org.junit.jupiter.api.TestMethodOrder; +import org.junit.jupiter.api.extension.ExtensionConfigurationException; +import org.junit.jupiter.api.parallel.Execution; +import org.junit.jupiter.engine.AbstractJupiterTestEngineTests; +import org.junit.platform.testkit.engine.EngineExecutionResults; + +@DisplayName("SystemProperty extension") +class SystemPropertyExtensionTests extends AbstractJupiterTestEngineTests { + + @BeforeAll + static void globalSetUp() { + System.setProperty("A", "old A"); + System.setProperty("B", "old B"); + System.setProperty("C", "old C"); + + System.clearProperty("clear prop D"); + System.clearProperty("clear prop E"); + System.clearProperty("clear prop F"); + } + + @AfterAll + static void globalTearDown() { + System.clearProperty("A"); + System.clearProperty("B"); + System.clearProperty("C"); + + assertThat(System.getProperty("clear prop D")).isNull(); + assertThat(System.getProperty("clear prop E")).isNull(); + assertThat(System.getProperty("clear prop F")).isNull(); + } + + @Nested + @DisplayName("used with ClearSystemProperty") + @ClearSystemProperty(key = "A") + class ClearSystemPropertyTests { + + @Test + @DisplayName("should clear system property") + @ClearSystemProperty(key = "B") + void shouldClearSystemProperty() { + assertThat(System.getProperty("A")).isNull(); + assertThat(System.getProperty("B")).isNull(); + assertThat(System.getProperty("C")).isEqualTo("old C"); + + assertThat(System.getProperty("clear prop D")).isNull(); + assertThat(System.getProperty("clear prop E")).isNull(); + assertThat(System.getProperty("clear prop F")).isNull(); + } + + @Test + @DisplayName("should be repeatable") + @ClearSystemProperty(key = "B") + @ClearSystemProperty(key = "C") + void shouldBeRepeatable() { + assertThat(System.getProperty("A")).isNull(); + assertThat(System.getProperty("B")).isNull(); + assertThat(System.getProperty("C")).isNull(); + + assertThat(System.getProperty("clear prop D")).isNull(); + assertThat(System.getProperty("clear prop E")).isNull(); + assertThat(System.getProperty("clear prop F")).isNull(); + } + + } + + @Nested + @DisplayName("used with SetSystemProperty") + @SetSystemProperty(key = "A", value = "new A") + class SetSystemPropertyTests { + + @Test + @DisplayName("should set system property to value") + @SetSystemProperty(key = "B", value = "new B") + void shouldSetSystemPropertyToValue() { + assertThat(System.getProperty("A")).isEqualTo("new A"); + assertThat(System.getProperty("B")).isEqualTo("new B"); + assertThat(System.getProperty("C")).isEqualTo("old C"); + + assertThat(System.getProperty("clear prop D")).isNull(); + assertThat(System.getProperty("clear prop E")).isNull(); + assertThat(System.getProperty("clear prop F")).isNull(); + } + + @Test + @DisplayName("should be repeatable") + @SetSystemProperty(key = "B", value = "new B") + @SetSystemProperty(key = "clear prop D", value = "new D") + void shouldBeRepeatable() { + assertThat(System.getProperty("A")).isEqualTo("new A"); + assertThat(System.getProperty("B")).isEqualTo("new B"); + assertThat(System.getProperty("C")).isEqualTo("old C"); + + assertThat(System.getProperty("clear prop D")).isEqualTo("new D"); + assertThat(System.getProperty("clear prop E")).isNull(); + assertThat(System.getProperty("clear prop F")).isNull(); + } + + } + + @Nested + @DisplayName("used with both ClearSystemProperty and SetSystemProperty") + @ClearSystemProperty(key = "A") + @SetSystemProperty(key = "clear prop D", value = "new D") + class CombinedClearAndSetTests { + + @Test + @DisplayName("should be combinable") + @ClearSystemProperty(key = "B") + @SetSystemProperty(key = "clear prop E", value = "new E") + void clearAndSetSystemPropertyShouldBeCombinable() { + assertThat(System.getProperty("A")).isNull(); + assertThat(System.getProperty("B")).isNull(); + assertThat(System.getProperty("C")).isEqualTo("old C"); + + assertThat(System.getProperty("clear prop D")).isEqualTo("new D"); + assertThat(System.getProperty("clear prop E")).isEqualTo("new E"); + assertThat(System.getProperty("clear prop F")).isNull(); + } + + @Test + @DisplayName("method level should overwrite class level") + @ClearSystemProperty(key = "clear prop D") + @SetSystemProperty(key = "A", value = "new A") + void methodLevelShouldOverwriteClassLevel() { + assertThat(System.getProperty("A")).isEqualTo("new A"); + assertThat(System.getProperty("B")).isEqualTo("old B"); + assertThat(System.getProperty("C")).isEqualTo("old C"); + + assertThat(System.getProperty("clear prop D")).isNull(); + assertThat(System.getProperty("clear prop E")).isNull(); + assertThat(System.getProperty("clear prop F")).isNull(); + } + + @Test + @DisplayName("method level should not clash (in terms of duplicate entries) with class level") + @SetSystemProperty(key = "A", value = "new A") + void methodLevelShouldNotClashWithClassLevel() { + assertThat(System.getProperty("A")).isEqualTo("new A"); + assertThat(System.getProperty("B")).isEqualTo("old B"); + assertThat(System.getProperty("C")).isEqualTo("old C"); + assertThat(System.getProperty("clear prop D")).isEqualTo("new D"); + + assertThat(System.getProperty("clear prop E")).isNull(); + assertThat(System.getProperty("clear prop F")).isNull(); + } + + } + + @Nested + @DisplayName("used with Clear, Set and Restore") + @WritesSystemProperty // Many of these tests write, many also access + @Execution(SAME_THREAD) // Uses instance state + @TestInstance(TestInstance.Lifecycle.PER_CLASS) // Uses instance state + @TestClassOrder(ClassOrderer.OrderAnnotation.class) + class CombinedClearSetRestoreTests { + + Properties initialState; // Stateful + + @BeforeAll + void beforeAll() { + initialState = System.getProperties(); + } + + @Nested + @Order(1) + @DisplayName("Set, Clear & Restore on class") + @ClearSystemProperty(key = "A") + @SetSystemProperty(key = "clear prop D", value = "new D") + @RestoreSystemProperties + @TestMethodOrder(OrderAnnotation.class) + @TestInstance(TestInstance.Lifecycle.PER_CLASS) // Uses instance state + class SetClearRestoreOnClass { + + @AfterAll + void afterAll() { + System.setProperties(new Properties()); // Really blow it up after this class + } + + @Test + @Order(1) + @DisplayName("Set, Clear on method w/ direct set Sys Prop") + @ClearSystemProperty(key = "B") + @SetSystemProperty(key = "clear prop E", value = "new E") + void clearSetRestoreShouldBeCombinable() { + assertThat(System.getProperties()).withFailMessage( + "Restore should swap out the Sys Properties instance").isNotSameAs(initialState); + + // Direct modification - shouldn't be visible in next test + System.setProperty("Restore", "Restore Me"); + System.getProperties().put("XYZ", this); + + assertThat(System.getProperty("Restore")).isEqualTo("Restore Me"); + assertThat(System.getProperties().get("XYZ")).isSameAs(this); + + // All the others + assertThat(System.getProperty("A")).isNull(); + assertThat(System.getProperty("B")).isNull(); + assertThat(System.getProperty("C")).isEqualTo("old C"); + + assertThat(System.getProperty("clear prop D")).isEqualTo("new D"); + assertThat(System.getProperty("clear prop E")).isEqualTo("new E"); + assertThat(System.getProperty("clear prop F")).isNull(); + } + + @Test + @DisplayName("Restore from class should restore direct mods") + @Order(2) + void restoreShouldHaveRevertedDirectModification() { + assertThat(System.getProperty("Restore")).isNull(); + assertThat(System.getProperties().get("XYZ")).isNull(); + } + + } + + @Nested + @Order(2) + @DisplayName("Prior nested class changes should be restored}") + class priorNestedChangesRestored { + + @Test + @DisplayName("Restore from class should restore direct mods") + void restoreShouldHaveRevertedDirectModification() { + assertThat(System.getProperties()).isStrictlyEqualTo(initialState); + } + + } + + @Nested + @Order(3) + @DisplayName("Set & Clear on class, Restore on method") + @ClearSystemProperty(key = "A") + @SetSystemProperty(key = "clear prop D", value = "new D") + @TestMethodOrder(OrderAnnotation.class) + @TestInstance(TestInstance.Lifecycle.PER_CLASS) // Uses instance state + class SetAndClearOnClass { + + Properties initialState; // Stateful + + @BeforeAll + void beforeAll() { + initialState = System.getProperties(); + } + + @Test + @Order(1) + @DisplayName("Set, Clear & Restore on method w/ direct set Sys Prop") + @ClearSystemProperty(key = "B") + @SetSystemProperty(key = "clear prop E", value = "new E") + @RestoreSystemProperties + void clearSetRestoreShouldBeCombinable() { + assertThat(System.getProperties()).withFailMessage( + "Restore should swap out the Sys Properties instance").isNotSameAs(initialState); + + // Direct modification - shouldn't be visible in the next test + System.setProperty("Restore", "Restore Me"); + System.getProperties().put("XYZ", this); + + // All the others + assertThat(System.getProperty("A")).isNull(); + assertThat(System.getProperty("B")).isNull(); + assertThat(System.getProperty("C")).isEqualTo("old C"); + + assertThat(System.getProperty("clear prop D")).isEqualTo("new D"); + assertThat(System.getProperty("clear prop E")).isEqualTo("new E"); + assertThat(System.getProperty("clear prop F")).isNull(); + } + + @Test + @DisplayName("Restore from prior method should restore direct mods") + @Order(2) + void restoreShouldHaveRevertedDirectModification() { + assertThat(System.getProperty("Restore")).isNull(); + assertThat(System.getProperties().get("XYZ")).isNull(); + assertThat(System.getProperties()).isStrictlyEqualTo(initialState); + } + + } + + } + + @Nested + @DisplayName("RestoreSystemProperties individual methods tests") + @WritesSystemProperty // Many of these tests write, many also access + class RestoreSystemPropertiesUnitTests { + + SystemPropertyExtension spe; + + @BeforeEach + void beforeEach() { + spe = new SystemPropertyExtension(); + } + + @Nested + @DisplayName("Attributes of RestoreSystemProperties Annotation") + class BasicAttributesOfRestoreSystemProperties { + + @Test + @DisplayName("Restore annotation has correct markers") + void restoreHasCorrectMarkers() { + assertThat(RestoreSystemProperties.class).hasAnnotations(Inherited.class, WritesSystemProperty.class); + } + + @Test + @DisplayName("Restore annotation has correct retention") + void restoreHasCorrectRetention() { + assertThat(RestoreSystemProperties.class.getAnnotation(Retention.class).value()).isEqualTo( + RetentionPolicy.RUNTIME); + } + + @Test + @DisplayName("Restore annotation has correct targets") + void restoreHasCorrectTargets() { + assertThat(RestoreSystemProperties.class.getAnnotation(Target.class).value()).containsExactlyInAnyOrder( + ElementType.METHOD, ElementType.TYPE); + } + + } + + @Nested + @DisplayName("cloneProperties Tests") + class ClonePropertiesTests { + + Properties inner; + Properties outer; //Created w/ inner as nested defaults + + @BeforeEach + void beforeEach() { + inner = new Properties(); + outer = new Properties(inner); + + inner.setProperty("A", "is A"); + outer.setProperty("B", "is B"); + } + + @Test + @DisplayName("Nested defaults handled") + void nestedDefaultsHandled() { + Properties cloned = SystemPropertyExtension.createEffectiveClone(outer); + assertThat(cloned).isEffectivelyEqualsTo(outer); + } + + @Test + @DisplayName("Object values are skipped") + void objectValuesAreSkipped() { + inner.put("inner_obj", new Object()); + outer.put("outer_obj", new Object()); + Properties cloned = SystemPropertyExtension.createEffectiveClone(outer); + + assertThat(cloned).isEffectivelyEqualsTo(outer); + assertThat(cloned.contains("inner_obj")).isFalse(); + assertThat(cloned.contains("outer_obj")).isFalse(); + } + + } + + @Nested + @DisplayName("RestorableContext Workflow Tests") + class RestorableContextWorkflowTests { + + @Test + @DisplayName("Workflow of RestorableContext") + void workflowOfRestorableContexts() { + Properties initialState = System.getProperties(); //This is a live reference + + try { + Properties returnedFromPrepareToEnter = spe.prepareToEnterRestorableContext(); + Properties postPrepareToEnterSysProps = System.getProperties(); + spe.prepareToExitRestorableContext(initialState); + Properties postPrepareToExitSysProps = System.getProperties(); + + assertThat(returnedFromPrepareToEnter).withFailMessage( + "prepareToEnterRestorableContext should return actual original or deep copy").isStrictlyEqualTo( + initialState); + + assertThat(returnedFromPrepareToEnter).withFailMessage( + "prepareToEnterRestorableContext should replace the actual Sys Props").isNotSameAs( + postPrepareToEnterSysProps); + + assertThat(postPrepareToEnterSysProps).isEffectivelyEqualsTo(initialState); + + // Could assert isSameAs, but a deep copy would also be allowed + assertThat(postPrepareToExitSysProps).isStrictlyEqualTo(initialState); + + } + finally { + System.setProperties(initialState); // Ensure complete recovery + } + } + + } + + } + + @Nested + @DisplayName("with nested classes") + @ClearSystemProperty(key = "A") + @SetSystemProperty(key = "B", value = "new B") + class NestedSystemPropertyTests { + + @Nested + @TestMethodOrder(OrderAnnotation.class) + @DisplayName("without SystemProperty annotations") + class NestedClass { + + @Test + @Order(1) + @ReadsSystemProperty + @DisplayName("system properties should be set from enclosed class when they are not provided in nested") + void shouldSetSystemPropertyFromEnclosedClass() { + assertThat(System.getProperty("A")).isNull(); + assertThat(System.getProperty("B")).isEqualTo("new B"); + } + + @Test + @Order(2) + @ReadsSystemProperty + @DisplayName("system properties should be set from enclosed class after restore") + void shouldSetSystemPropertyFromEnclosedClassAfterRestore() { + assertThat(System.getProperty("A")).isNull(); + assertThat(System.getProperty("B")).isEqualTo("new B"); + } + + } + + @Nested + @SetSystemProperty(key = "B", value = "newer B") + @DisplayName("with SetSystemProperty annotation") + class AnnotatedNestedClass { + + @Test + @ReadsSystemProperty + @DisplayName("system property should be set from nested class when it is provided") + void shouldSetSystemPropertyFromNestedClass() { + assertThat(System.getProperty("B")).isEqualTo("newer B"); + } + + @Test + @SetSystemProperty(key = "B", value = "newest B") + @DisplayName("system property should be set from method when it is provided") + void shouldSetSystemPropertyFromMethodOfNestedClass() { + assertThat(System.getProperty("B")).isEqualTo("newest B"); + } + + } + + } + + @Nested + @SetSystemProperty(key = "A", value = "new A") + @TestInstance(TestInstance.Lifecycle.PER_CLASS) + class ResettingSystemPropertyTests { + + @Nested + @SetSystemProperty(key = "A", value = "newer A") + @TestInstance(TestInstance.Lifecycle.PER_CLASS) + class ResettingSystemPropertyAfterEachNestedTests { + + @BeforeEach + void changeShouldBeVisible() { + // We already see "newest A" because BeforeEachCallBack is invoked before @BeforeEach + // See https://junit.org/junit5/docs/current/user-guide/#extensions-execution-order-overview + assertThat(System.getProperty("A")).isEqualTo("newest A"); + } + + @Test + @SetSystemProperty(key = "A", value = "newest A") + void setForTestMethod() { + assertThat(System.getProperty("A")).isEqualTo("newest A"); + } + + @AfterEach + @ReadsSystemProperty + void resetAfterTestMethodExecution() { + // We still see "newest A" because AfterEachCallBack is invoked after @AfterEach + // See https://junit.org/junit5/docs/current/user-guide/#extensions-execution-order-overview + assertThat(System.getProperty("A")).isEqualTo("newest A"); + } + + } + + @Nested + @SetSystemProperty(key = "A", value = "newer A") + @TestInstance(TestInstance.Lifecycle.PER_CLASS) + class ResettingSystemPropertyAfterAllNestedTests { + + @BeforeAll + void changeShouldBeVisible() { + assertThat(System.getProperty("A")).isEqualTo("newer A"); + } + + @Test + @SetSystemProperty(key = "A", value = "newest A") + void setForTestMethod() { + assertThat(System.getProperty("A")).isEqualTo("newest A"); + } + + @AfterAll + @ReadsSystemProperty + void resetAfterTestMethodExecution() { + assertThat(System.getProperty("A")).isEqualTo("newer A"); + } + + } + + @AfterAll + @ReadsSystemProperty + void resetAfterTestContainerExecution() { + assertThat(System.getProperty("A")).isEqualTo("new A"); + } + + } + + @Nested + @DisplayName("used with incorrect configuration") + class ConfigurationFailureTests { + + @Test + @DisplayName("should fail when clear and set same system property") + void shouldFailWhenClearAndSetSameSystemProperty() { + EngineExecutionResults results = executeTests(selectMethod(MethodLevelInitializationFailureTestCases.class, + "shouldFailWhenClearAndSetSameSystemProperty")); + results.testEvents().assertThatEvents().haveAtMost(1, + finishedWithFailure(instanceOf(ExtensionConfigurationException.class), + message(it -> it.contains("@DefaultTimeZone not configured correctly.")))); + } + + @Test + @DisplayName("should fail when clear same system property twice") + @Disabled("This can't happen at the moment, because Jupiter's annotation tooling " + + "deduplicates identical annotations like the ones required for this test: " + + "https://github.com/junit-team/junit5/issues/2131") + void shouldFailWhenClearSameSystemPropertyTwice() { + EngineExecutionResults results = executeTests(selectMethod(MethodLevelInitializationFailureTestCases.class, + "shouldFailWhenClearSameSystemPropertyTwice")); + + results.testEvents().assertThatEvents().haveAtMost(1, + finishedWithFailure(instanceOf(ExtensionConfigurationException.class))); + } + + @Test + @DisplayName("should fail when set same system property twice") + void shouldFailWhenSetSameSystemPropertyTwice() { + EngineExecutionResults results = executeTests(selectMethod(MethodLevelInitializationFailureTestCases.class, + "shouldFailWhenSetSameSystemPropertyTwice")); + results.testEvents().assertThatEvents().haveAtMost(1, + finishedWithFailure(instanceOf(ExtensionConfigurationException.class))); + } + + } + + static class MethodLevelInitializationFailureTestCases { + + @Test + @DisplayName("clearing and setting the same property") + @ClearSystemProperty(key = "A") + @SetSystemProperty(key = "A", value = "new A") + void shouldFailWhenClearAndSetSameSystemProperty() { + } + + @Test + @ClearSystemProperty(key = "A") + @ClearSystemProperty(key = "A") + void shouldFailWhenClearSameSystemPropertyTwice() { + } + + @Test + @SetSystemProperty(key = "A", value = "new A") + @SetSystemProperty(key = "A", value = "new B") + void shouldFailWhenSetSameSystemPropertyTwice() { + } + + } + + @Nested + @DisplayName("used with inheritance") + class InheritanceClearAndSetTests extends InheritanceClearAndSetBaseTest { + + @Test + @DisplayName("should inherit clear and set annotations") + void shouldInheritClearAndSetProperty() { + assertThat(System.getProperty("A")).isNull(); + assertThat(System.getProperty("B")).isNull(); + assertThat(System.getProperty("clear prop D")).isEqualTo("new D"); + assertThat(System.getProperty("clear prop E")).isEqualTo("new E"); + } + + } + + @Nested + @DisplayName("used with inheritance") + @TestMethodOrder(OrderAnnotation.class) + @TestClassOrder(ClassOrderer.OrderAnnotation.class) + @Execution(SAME_THREAD) // Uses instance state + @TestInstance(TestInstance.Lifecycle.PER_CLASS) // Uses instance state + class InheritanceClearSetRestoreTests extends InheritanceClearSetRestoreBaseTest { + + Properties initialState; // Stateful + + @BeforeAll + void beforeAll() { + initialState = System.getProperties(); + } + + @Test + @Order(1) + @DisplayName("should inherit clear and set annotations") + void shouldInheritClearSetRestore() { + // Direct modification - shouldn't be visible in the next test + System.setProperty("Restore", "Restore Me"); + System.getProperties().put("XYZ", this); + + assertThat(System.getProperty("A")).isNull(); // The rest are checked elsewhere + } + + @Test + @Order(2) + @DisplayName("Restore from class should restore direct mods") + void restoreShouldHaveRevertedDirectModification() { + assertThat(System.getProperty("Restore")).isNull(); + assertThat(System.getProperties().get("XYZ")).isNull(); + assertThat(System.getProperties()).isStrictlyEqualTo(initialState); + } + + @Nested + @Order(1) + @DisplayName("Set props to ensure inherited restore") + @TestMethodOrder(OrderAnnotation.class) + @TestInstance(TestInstance.Lifecycle.PER_CLASS) + class SetSomeValuesToRestore { + + @AfterAll + void afterAll() { + System.setProperty("RestoreAll", "Restore Me"); // This should also be restored + } + + @Test + @Order(1) + @DisplayName("Inherit values and restore behavior") + void shouldInheritInNestedClass() { + assertThat(System.getProperty("A")).isNull(); + + // Shouldn't be visible in the next test + System.setProperty("Restore", "Restore Me"); + } + + @Test + @Order(2) + @DisplayName("Verify restore behavior bt methods") + void verifyRestoreBetweenMethods() { + assertThat(System.getProperty("Restore")).isNull(); + } + + } + + @Nested + @Order(2) + @DisplayName("Verify props are restored") + @TestInstance(TestInstance.Lifecycle.PER_CLASS) + class VerifyValuesAreRestored { + + @Test + @DisplayName("Inherit values and restore behavior") + void shouldInheritInNestedClass() { + assertThat(System.getProperty("RestoreAll")).isNull(); // Should be restored + } + + } + + } + + @ClearSystemProperty(key = "A") + @ClearSystemProperty(key = "B") + @SetSystemProperty(key = "clear prop D", value = "new D") + @SetSystemProperty(key = "clear prop E", value = "new E") + static class InheritanceClearAndSetBaseTest { + + } + + @ClearSystemProperty(key = "A") + @ClearSystemProperty(key = "B") + @SetSystemProperty(key = "clear prop D", value = "new D") + @SetSystemProperty(key = "clear prop E", value = "new E") + @RestoreSystemProperties + static class InheritanceClearSetRestoreBaseTest { + } + +} From a25a71b85821a46dc292c573766e1bb0b5540797 Mon Sep 17 00:00:00 2001 From: "M.P. Korstanje" Date: Wed, 10 Dec 2025 20:09:22 +0100 Subject: [PATCH 2/4] Make checkstyle and friends happy --- .../junit/jupiter/api/util/SystemPropertyExtension.java | 8 ++++---- .../jupiter/api/util/SystemPropertyExtensionUtils.java | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/util/SystemPropertyExtension.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/util/SystemPropertyExtension.java index b0fceefd3f5a..02c92399ef80 100644 --- a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/util/SystemPropertyExtension.java +++ b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/util/SystemPropertyExtension.java @@ -13,10 +13,10 @@ import java.util.Properties; import java.util.function.Function; -import org.apiguardian.api.API; - -@API(status = API.Status.STABLE, since = "6.1") -public class SystemPropertyExtension extends +/** + * @since 6.1 + */ +final class SystemPropertyExtension extends AbstractEntryBasedExtension { @Override diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/util/SystemPropertyExtensionUtils.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/util/SystemPropertyExtensionUtils.java index 2febac6876d3..1f0ca1e72a9d 100644 --- a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/util/SystemPropertyExtensionUtils.java +++ b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/util/SystemPropertyExtensionUtils.java @@ -21,7 +21,7 @@ /** * Utility methods for the SystemPropertiesExtension. */ -class SystemPropertyExtensionUtils { +final class SystemPropertyExtensionUtils { private SystemPropertyExtensionUtils() { // private constructor to prevent instantiation of utility class From 392916b7afab6938e34dc70f814e48e51e02ed08 Mon Sep 17 00:00:00 2001 From: "M.P. Korstanje" Date: Wed, 10 Dec 2025 20:15:02 +0100 Subject: [PATCH 3/4] Make Antorra happy after merge --- .../pages/writing-tests/built-in-extensions.adoc | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/documentation/modules/ROOT/pages/writing-tests/built-in-extensions.adoc b/documentation/modules/ROOT/pages/writing-tests/built-in-extensions.adoc index bd007c05eca0..19abd0ab2526 100644 --- a/documentation/modules/ROOT/pages/writing-tests/built-in-extensions.adoc +++ b/documentation/modules/ROOT/pages/writing-tests/built-in-extensions.adoc @@ -305,21 +305,21 @@ For example, clearing a system property for a test execution can be done as foll [source,java,indent=0] ---- -include::{testDir}/example/SystemPropertyExtensionDemo.java[tag=systemproperty_clear_simple] +include::example$java/example/SystemPropertyExtensionDemo.java[tag=systemproperty_clear_simple] ---- And setting a system property for a test execution: [source,java,indent=0] ---- -include::{testDir}/example/SystemPropertyExtensionDemo.java[tag=systemproperty_set_simple] +include::example$java/example/SystemPropertyExtensionDemo.java[tag=systemproperty_set_simple] ---- As mentioned before, both annotations are repeatable, and they can also be combined: [source,java,indent=0] ---- -include::{testDir}/example/SystemPropertyExtensionDemo.java[tag=systemproperty_using_set_and_clear] +include::example$java/example/SystemPropertyExtensionDemo.java[tag=systemproperty_using_set_and_clear] ---- @@ -327,7 +327,7 @@ Note that class-level configurations are overwritten by method-level configurati [source,java,indent=0] ---- -include::{testDir}/example/SystemPropertyExtensionDemo.java[tag=systemproperty_using_at_class_level] +include::example$java/example/SystemPropertyExtensionDemo.java[tag=systemproperty_using_at_class_level] ---- [NOTE] @@ -347,7 +347,7 @@ In this example, `@RestoreSystemProperties` is used on a test method, ensuring a [source,java,indent=0] ---- -include::{testDir}/example/SystemPropertyExtensionDemo.java[tag=systemproperty_restore_test] +include::example$java/example/SystemPropertyExtensionDemo.java[tag=systemproperty_restore_test] ---- When `@RestoreSystemProperties` is used on a test class, any system properties changes made during the entire lifecycle of the test class, including test methods, `@BeforeAll`, `@BeforeEach` and 'after' methods, are restored after the test class' lifecycle is complete. @@ -359,14 +359,14 @@ Note that `SomeOtherTestClass` uses the `@ReadsSystemProperty` annotation: This [source,java,indent=0] ---- -include::{testDir}/example/SystemPropertyExtensionDemo.java[tag=systemproperty_class_restore_setup] +include::example$java/example/SystemPropertyExtensionDemo.java[tag=systemproperty_class_restore_setup] ---- Some other test class, running later: [source,java,indent=0] ---- -include::{testDir}/example/SystemPropertyExtensionDemo.java[tag=systemproperty_class_restore_isolated_class] +include::example$java/example/SystemPropertyExtensionDemo.java[tag=systemproperty_class_restore_isolated_class] ---- == Using `@ClearSystemProperty`, `@SetSystemProperty`, and `@RestoreSystemProperties` together @@ -377,7 +377,7 @@ Basic configuration can be specified using `Set` and `Clear` and the image size [source,java,indent=0] ---- -include::{testDir}/example/SystemPropertyExtensionDemo.java[tag=systemproperty_method_combine_all_test] +include::example$java/example/SystemPropertyExtensionDemo.java[tag=systemproperty_method_combine_all_test] ---- [NOTE] From a18d1721372fcf2fe253f06e6f6f359e777bfa7d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matthias=20B=C3=BCnger?= Date: Sat, 13 Dec 2025 19:05:07 +0100 Subject: [PATCH 4/4] ka mehr --- .../junit/jupiter/api/util/AbstractEntryBasedExtension.java | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/util/AbstractEntryBasedExtension.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/util/AbstractEntryBasedExtension.java index d55688233c38..a3143f7877d3 100644 --- a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/util/AbstractEntryBasedExtension.java +++ b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/util/AbstractEntryBasedExtension.java @@ -73,8 +73,8 @@ public void beforeEach(ExtensionContext context) { } private void applyForAllContexts(ExtensionContext originalContext) { - AnnotatedElement element = originalContext.getElement().orElse(null); - boolean fullRestore = AnnotationSupport.findAnnotation(element, getRestoreAnnotationType()).isPresent(); + boolean fullRestore = AnnotationSupport.findAnnotation(originalContext.getElement(), + getRestoreAnnotationType()).isPresent(); if (fullRestore) { Properties bulk = this.prepareToEnterRestorableContext();

During + * parallel test execution, + * all tests annotated with {@link ClearSystemProperty}, {@link SetSystemProperty}, {@link ReadsSystemProperty}, and {@link WritesSystemProperty} + * are scheduled in a way that guarantees correctness under mutation of shared global state.