diff --git a/docs/snapshot/api/org.junit.jupiter.api/org/junit/jupiter/api/extension/TestWatcher.html b/docs/snapshot/api/org.junit.jupiter.api/org/junit/jupiter/api/extension/TestWatcher.html index 57cda62e13d5..5582155d1c54 100644 --- a/docs/snapshot/api/org.junit.jupiter.api/org/junit/jupiter/api/extension/TestWatcher.html +++ b/docs/snapshot/api/org.junit.jupiter.api/org/junit/jupiter/api/extension/TestWatcher.html @@ -100,9 +100,29 @@

Interface TestWatcher

@TestTemplate methods (e.g., @RepeatedTest and @ParameterizedTest). Moreover, if there is a failure at the class level — for example, an exception thrown by a - @BeforeAll method — no test results will be reported. + @BeforeAll method — no test results will be reported. Similarly, + if the test class is disabled via an ExecutionCondition — for + example, @Disabled — no test results will be reported. -

Extensions implementing this API can be registered at any level. +

Extensions implementing this interface can be registered at the class level, + instance level, or method level. When registered at the class level, a + TestWatcher will be invoked for any contained test method including + those in @Nested classes. When registered + at the method level, a TestWatcher will only be invoked for the test + method for which it was registered. + +

WARNING: If a TestWatcher is registered via a + non-static (instance) field — for example, using + @RegisterExtension — and the test class is + configured with + @TestInstance(Lifecycle.PER_METHOD) + semantics (which is the default lifecycle mode), the TestWatcher will + not be invoked with events for @TestTemplate methods + (such as @RepeatedTest and @ParameterizedTest). To ensure that + a TestWatcher is invoked for all test methods in a given class, it is + therefore recommended that the TestWatcher be registered at the class + level with @ExtendWith or via a static field with + @RegisterExtension or @ExtendWith.

Exception Handling

diff --git a/docs/snapshot/published-checksum.txt b/docs/snapshot/published-checksum.txt index e5b0756f8d8c..8b696d5485ce 100644 --- a/docs/snapshot/published-checksum.txt +++ b/docs/snapshot/published-checksum.txt @@ -57,6 +57,7 @@ 112012410d193c0d9ccdfee9262df766 junit-platform-console/src/main/java/org/junit/platform/console/options/Theme.java 1204b968c0f6e2a77a5182e93ca40850 documentation/src/test/java/example/testinterface/TimeExecutionLogger.java 12e6cede69d624681253faf7f4e7dc72 junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/Extension.java +1384cd1694204c7d8f3ecd75923fa29d junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/TestWatcher.java 13ac972a60f544ea62f381731d18990c documentation/src/docs/asciidoc/release-notes/release-notes-5.9.3.adoc 13b704e483d5aebff444f2f2617d6d13 junit-platform-launcher/src/main/java/org/junit/platform/launcher/listeners/UniqueIdTrackingListener.java 13c76a7853cbb65c8d2f2330aac9495d documentation/src/docs/asciidoc/user-guide/api-evolution.adoc @@ -112,7 +113,6 @@ 27be2636edd19cfe69859dd625d8428e junit-jupiter-engine/src/main/java/org/junit/jupiter/engine/discovery/MethodSelectorResolver.java 28729167f2f8c799b1adcf791b6eb8c5 junit-platform-launcher/src/main/java/org/junit/platform/launcher/listeners/discovery/LoggingLauncherDiscoveryListener.java 29057d19138e6a1789282dab10852068 documentation/src/test/java/org/junit/api/tools/ApiReportWriter.java -292f0c98757dae9a6a851fab43269b09 documentation/src/docs/asciidoc/user-guide/writing-tests.adoc 29c26ee04d42ebbf571e649ec73efd38 junit-jupiter-api/src/main/java/org/junit/jupiter/api/function/Executable.java 2a6a22322d0d2efe52021bc0bd99ec62 junit-jupiter-api/src/main/java/org/junit/jupiter/api/condition/DisabledIf.java 2a7cd23c9bfc98f69fb16e08258d68cd documentation/src/test/java/example/callbacks/Extension2.java @@ -431,7 +431,6 @@ 886cf74e6f1023545a05b0bc90e50895 junit-platform-commons/src/main/java/org/junit/platform/commons/util/BlacklistedExceptions.java 89406f40f711e284ed7587f18cca0c3d junit-platform-suite-api/src/main/java/org/junit/platform/suite/api/SelectPackages.java 894cd93bbd1a6429c6436f2a42dcdac2 junit-platform-console/src/main/java/org/junit/platform/console/tasks/TreePrintingListener.java -894d4fdfd675fd5c16deff22988327ac documentation/src/docs/asciidoc/release-notes/release-notes-5.10.0-RC1.adoc 89718e551cfe40a123823f221bebaa67 documentation/src/docs/asciidoc/resources/themes/junit-pdf-theme.yml 8a6fdf2c7fa46f893c68582f17f13899 documentation/src/test/java/example/callbacks/Extension1.java 8ab93885ec7ce9ba1cb478868a626df2 junit-platform-suite-api/src/main/java/org/junit/platform/suite/api/ConfigurationParameter.java @@ -453,6 +452,7 @@ 8e55271e059d61a358c47b14d1f7d37d junit-platform-console/src/main/java/org/junit/platform/console/tasks/TreePrinter.java 8e7a61177333442cc4091cb0120cac2b junit-jupiter-migrationsupport/src/main/java/org/junit/jupiter/migrationsupport/rules/adapter/ExpectedExceptionAdapter.java 8e8c9ec287e466507d377a1e21c6da05 junit-jupiter-engine/src/main/java/org/junit/jupiter/engine/extension/MutableExtensionRegistry.java +8f07b10063d7990c34d34064d70da1cb documentation/src/docs/asciidoc/user-guide/extensions.adoc 8f357407fbea6d14e5d5bfc06cd2ba91 junit-platform-launcher/src/main/java/org/junit/platform/launcher/core/LauncherDiscoveryRequestBuilder.java 8f3fd10378f55fad8e1375dc0d5036a0 documentation/src/main/java/example/registration/WebClient.java 8fd8ad2e0c863f13e264f6b909cc853a junit-jupiter-api/src/main/java/org/junit/jupiter/api/Assertions.java @@ -672,7 +672,6 @@ d28b3e91877ea7fbf00d9da522ddbe62 junit-platform-commons/src/main/java/org/junit d2be4fa991bbe0384ec7634181fb9a39 junit-vintage-engine/src/main/java/org/junit/vintage/engine/discovery/DefensiveAllDefaultPossibilitiesBuilder.java d2cd75e732ece74152936ee110ae8aae junit-jupiter-engine/src/main/java/org/junit/jupiter/engine/config/DefaultJupiterConfiguration.java d326da5d0e593b5edfa469bb74775852 junit-platform-commons/src/main/java/org/junit/platform/commons/logging/LoggerFactory.java -d3627eb81c5a050982ac1601a5b41c21 junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/TestWatcher.java d3a42f95383f057d5f44fe3598bd3832 junit-jupiter-engine/src/main/java/org/junit/jupiter/engine/extension/TimeoutExtension.java d3cc17a3f4c29efd2bc18717bf4e87a9 junit-jupiter-engine/src/main/java/org/junit/jupiter/engine/descriptor/ClassBasedTestDescriptor.java d3f72638028afd38f7788243c955d035 junit-jupiter-params/src/main/java/org/junit/jupiter/params/provider/Arguments.java @@ -682,6 +681,7 @@ d48ca497e27808531a970f7782107993 junit-vintage-engine/src/main/java/org/junit/v d492c4ceae12bdb9bc72d7aed56dd848 junit-jupiter-api/src/main/java/org/junit/jupiter/api/RepetitionInfo.java d4ce47495afb2233161e3f4241bc9f98 junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/package-info.java d4fe811c167b6bbaf3f427b4a26faa0b junit-jupiter-api/src/main/java/org/junit/jupiter/api/package-info.java +d5667831a21d08e0076e10c6af2e743c documentation/src/docs/asciidoc/user-guide/writing-tests.adoc d57aa7f36c6865c8bed7dd85c0d7d817 junit-jupiter-api/src/main/java/org/junit/jupiter/api/condition/AbstractOsBasedExecutionCondition.java d5a5df4157565c26820a164f93d92d17 documentation/src/docs/asciidoc/release-notes/release-notes-5.9.1.adoc d60c79c8a58652feb53122397b0d138b junit-jupiter-api/src/main/java/org/junit/jupiter/api/parallel/Isolated.java @@ -701,7 +701,6 @@ d8bd8a82228a73deaf1be8317da6e6e5 junit-vintage-engine/src/main/java/org/junit/v d8de75eb134ac62780487423cf8f837e junit-jupiter-engine/src/main/java/org/junit/jupiter/engine/descriptor/MethodSourceSupport.java d8f765cdaae86ca58de5ebf87d38ef59 junit-platform-suite-api/src/main/java/org/junit/platform/suite/api/ExcludeClassNamePatterns.java d9c4b2ecfd40ab714e5f249ab1d1641a documentation/src/docs/asciidoc/user-guide/advanced-topics/testkit.adoc -d9c99fb6f5075437d1f58af91c3a9a0c documentation/src/docs/asciidoc/user-guide/extensions.adoc d9d5c16c9edfc6011816243e3099211b junit-platform-launcher/src/main/java/org/junit/platform/launcher/package-info.java da369510c5511b2e45b273e801ebfb7e junit-platform-commons/src/main/java/org/junit/platform/commons/logging/LogRecordListener.java da3c11f05b4ff820a370b533f787a5ad documentation/src/test/java/example/callbacks/BrokenLifecycleMethodConfigDemo.java @@ -798,6 +797,7 @@ f242b37228066e16d01bb991cb8f3984 documentation/src/test/resources/two-column.cs f2abd6914fa1388f41e838d36c992bf7 junit-platform-launcher/src/main/java/org/junit/platform/launcher/listeners/session/CompositeLauncherSessionListener.java f2bd8b13217a0bfcf9eea994cc985146 documentation/src/test/java/example/RepeatedTestsDemo.java f2d749426e057a52ef1c9012ea02ddb9 documentation/src/test/java/example/SuiteDemo.java +f41369d2988b830604d4c3fb9e02c6cc documentation/src/docs/asciidoc/release-notes/release-notes-5.10.0-RC1.adoc f56706c8fb3402050810d3b98a2dab4b junit-jupiter-params/src/main/java/org/junit/jupiter/params/provider/CsvFileSource.java f64807b6069430b9144c0c35f791f663 junit-platform-launcher/src/main/java/org/junit/platform/launcher/core/OutcomeDelayingEngineExecutionListener.java f660db4c94a92103ab602456dea90e6f documentation/src/test/java/org/junit/api/tools/AbstractApiReportWriter.java diff --git a/docs/snapshot/release-notes/index.html b/docs/snapshot/release-notes/index.html index 86f7d87b939c..c6cb77facb8c 100644 --- a/docs/snapshot/release-notes/index.html +++ b/docs/snapshot/release-notes/index.html @@ -630,6 +630,10 @@

5 diff --git a/docs/snapshot/user-guide/images/component-diagram.svg b/docs/snapshot/user-guide/images/component-diagram.svg deleted file mode 100644 index 1c62c93d3237..000000000000 --- a/docs/snapshot/user-guide/images/component-diagram.svg +++ /dev/null @@ -1 +0,0 @@ -org.junit.jupiterorg.junit.vintageorg.junit.platformJUnit 4org.opentest4jorg.apiguardianjunit-jupiterjunit-jupiter-apijunit-jupiter-enginejunit-jupiter-paramsjunit-jupiter-migrationsupportjunit-vintage-enginejunit-platform-commonsjunit-platform-consolejunit-platform-enginejunit-platform-jfrjunit-platform-launcherjunit-platform-reportingjunit-platform-runnerjunit-platform-suitejunit-platform-suite-apijunit-platform-suite-commonsjunit-platform-suite-enginejunit-platform-testkitjunit:junitopentest4japiguardian-apiAll artifacts exceptopentest4j and junit:junithave a dependency on thisartifact. The edges havebeen omitted from thisdiagram for the sake ofreadability. \ No newline at end of file diff --git a/docs/snapshot/user-guide/index.html b/docs/snapshot/user-guide/index.html index 73881363c50b..2666d2d29b20 100644 --- a/docs/snapshot/user-guide/index.html +++ b/docs/snapshot/user-guide/index.html @@ -2611,8 +2611,7 @@

-See Test Classes and Methods for a definition of test method and -test class. +See Definitions for a definition of test method and test class. @@ -2868,8 +2867,8 @@

Test Classes and Methods). This "per-method" test instance lifecycle is the -default behavior in JUnit Jupiter and is analogous to all previous versions of JUnit.

+Definitions). This "per-method" test instance lifecycle is the default +behavior in JUnit Jupiter and is analogous to all previous versions of JUnit.

@@ -3122,8 +3121,8 @@

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 Test Classes and Methods) accepts a parameter, the -parameter must be resolved at runtime by a registered ParameterResolver.

+lifecycle method (see Definitions) 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.

@@ -9363,11 +9362,11 @@

If a test class constructor, test method, or lifecycle method (see -Test Classes and Methods) declares a parameter, the parameter must be -resolved at runtime by a ParameterResolver. A ParameterResolver can either be -built-in (see TestInfoParameterResolver) or registered by -the user. Generally speaking, parameters may be resolved by name, type, -annotation, or any combination thereof.

+Definitions) declares a parameter, the parameter must be resolved at +runtime by a ParameterResolver. A ParameterResolver can either be built-in (see +TestInfoParameterResolver) or registered by the user. +Generally speaking, parameters may be resolved by name, type, annotation, or any +combination thereof.

If you wish to implement a custom ParameterResolver that resolves parameters based @@ -9462,17 +9461,53 @@

In contrast to the definition of "test method" presented in -Test Classes and Methods, in this context test method refers to any -@Test method or @TestTemplate method (for example, a @RepeatedTest or -@ParameterizedTest). +Definitions, in this context test method refers to any @Test method +or @TestTemplate method (for example, a @RepeatedTest or @ParameterizedTest).

-

Extensions implementing this interface can be registered at the method level or at the -class level. In the latter case they will be invoked for any contained test method -including those in @Nested classes.

+

Extensions implementing this interface can be registered at the class level, instance +level, or method level. When registered at the class level, a TestWatcher will be +invoked for any contained test method including those in @Nested classes. When +registered at the method level, a TestWatcher will only be invoked for the test method +for which it was registered.

+
+
+ + + + + +
+ + +
+

If a TestWatcher is registered via a non-static (instance) field – for example, using +@RegisterExtension – and the test class is configured with +@TestInstance(Lifecycle.PER_METHOD) semantics (which is the default lifecycle mode), the +TestWatcher will not be invoked with events for @TestTemplate methods (for +example, @RepeatedTest or @ParameterizedTest).

+
+
+

To ensure that a TestWatcher is invoked for all test methods in a given class, it is +therefore recommended that the TestWatcher be registered at the class level with +@ExtendWith or via a static field with @RegisterExtension or @ExtendWith.

+
+
+
+
+

If there is a failure at the class level — for example, an exception thrown by a +@BeforeAll method — no test results will be reported. Similarly, if the test class is +disabled via an ExecutionCondition — for example, @Disabled — no test results will be +reported.

+
+
+

In contrast to other Extension APIs, a TestWatcher is not permitted to adversely +influence the execution of tests. Consequently, any exception thrown by a method in the +TestWatcher API will be logged at WARNING level and will not be allowed to propagate +or fail test execution.

@@ -9483,9 +9518,9 @@

Any instances of ExtensionContext.Store.CloseableResource stored in the Store of the -provided ExtensionContext will be closed before methods in this API are invoked (see -Keeping State in Extensions). You can use the parent context’s Store to work with such -resources.

+provided ExtensionContext will be closed before methods in the TestWatcher API are +invoked (see Keeping State in Extensions). You can use the parent context’s Store to +work with such resources.

@@ -10112,7 +10147,7 @@

JUnit Jupiter also guarantees wrapping behavior within class and interface hierarchies -for user-supplied lifecycle methods (see Test Classes and Methods).

+for user-supplied lifecycle methods (see Definitions).