-
- All Superinterfaces:
Extension
- All Known Implementing Classes:
RepetitionExtension
@API(status=STABLE, since="5.7") public interface TestWatcher extends Extension
TestWatcher
defines the API forExtensions
that wish to process test results.The methods in this API are called after a test has been skipped or executed. Any
CloseableResource
objects stored in theStore
of the suppliedExtensionContext
will have already been closed before methods in this API are invoked.Please note that this API is currently only used to report the results of
@Test
methods and@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. Similarly, if the test class is disabled via anExecutionCondition
— for example,@Disabled
— no test results will be reported.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, aTestWatcher
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), theTestWatcher
will not be invoked with events for@TestTemplate
methods (such as@RepeatedTest
and@ParameterizedTest
). To ensure that aTestWatcher
is invoked for all test methods in a given class, it is therefore recommended that theTestWatcher
be registered at the class level with@ExtendWith
or via astatic
field with@RegisterExtension
or@ExtendWith
.Exception Handling
In contrast to other
Extension
APIs, aTestWatcher
is not permitted to adversely influence the execution of tests. Consequently, any exception thrown by a method in theTestWatcher
API will be logged atWARNING
level and will not be allowed to propagate or fail test execution.- Since:
- 5.4
-
-
Method Summary
All Methods Instance Methods Default Methods Modifier and Type Method Description default void
testAborted(ExtensionContext context, java.lang.Throwable cause)
Invoked after a test has been aborted.default void
testDisabled(ExtensionContext context, java.util.Optional<java.lang.String> reason)
Invoked after a disabled test has been skipped.default void
testFailed(ExtensionContext context, java.lang.Throwable cause)
Invoked after a test has failed.default void
testSuccessful(ExtensionContext context)
Invoked after a test has completed successfully.
-
-
-
Method Detail
-
testDisabled
default void testDisabled(ExtensionContext context, java.util.Optional<java.lang.String> reason)
Invoked after a disabled test has been skipped.The default implementation does nothing. Concrete implementations can override this method as appropriate.
- Parameters:
context
- the current extension context; nevernull
reason
- the reason the test is disabled; nevernull
but potentially empty
-
testSuccessful
default void testSuccessful(ExtensionContext context)
Invoked after a test has completed successfully.The default implementation does nothing. Concrete implementations can override this method as appropriate.
- Parameters:
context
- the current extension context; nevernull
-
testAborted
default void testAborted(ExtensionContext context, java.lang.Throwable cause)
Invoked after a test has been aborted.The default implementation does nothing. Concrete implementations can override this method as appropriate.
- Parameters:
context
- the current extension context; nevernull
cause
- the throwable responsible for the test being aborted; may benull
-
testFailed
default void testFailed(ExtensionContext context, java.lang.Throwable cause)
Invoked after a test has failed.The default implementation does nothing. Concrete implementations can override this method as appropriate.
- Parameters:
context
- the current extension context; nevernull
cause
- the throwable that caused test failure; may benull
-
-