Test Result Processing

TestWatcher defines the API for extensions that wish to process the results of test method executions. Specifically, a TestWatcher will be invoked with contextual information for the following events.

  • testDisabled: invoked after a disabled test method has been skipped

  • testSuccessful: invoked after a test method has completed successfully

  • testAborted: invoked after a test method has been aborted

  • testFailed: invoked after a test method has failed

In contrast to the definition of "test method" presented in 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 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.

Any instances of ExtensionContext.Store.CloseableResource stored in the Store of the 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.