Interface testExecutionListener

All Known Subinterfaces:
AottestExecutionListener
All Known Implementing Classes:
AbstractDirtiesContexttestExecutionListener, AbstracttestExecutionListener, ApplicationEventstestExecutionListener, BeanOverridetestExecutionListener, CommonCachestestExecutionListener, DependencyInjectiontestExecutionListener, DirtiesContextBeforeModestestExecutionListener, DirtiesContexttestExecutionListener, EventPublishingtestExecutionListener, MockitoResettestExecutionListener, ServlettestExecutionListener, SqlScriptstestExecutionListener, TransactionaltestExecutionListener
public interface testExecutionListener
testExecutionListener defines a listener API for reacting to test execution events published by the testContextManager with which the listener is registered.

Note that not all testing frameworks support all lifecycle callbacks defined in this API. For example, the beforetestExecution and aftertestExecution callbacks are not supported in conjunction with JUnit 4 when using the SpringMethodRule.

This interface provides empty default implementations for all methods. Concrete implementations can therefore choose to override only those methods suitable for the task at hand.

Concrete implementations must provide a public no-args constructor, so that listeners can be instantiated transparently by tools and configuration mechanisms.

Implementations may optionally declare the position in which they should be ordered among the chain of default listeners via the Ordered interface or @Order annotation. See testContextBootstrapper.gettestExecutionListeners() for details.

Wrapping Behavior for Listeners

The testContextManager guarantees wrapping behavior for multiple registered listeners that implement lifecycle callbacks such as beforetestClass, aftertestClass, beforetestMethod, aftertestMethod, beforetestExecution, and aftertestExecution. This means that, given two listeners Listener1 and Listener2 with Listener1 registered before Listener2, any before callbacks implemented by Listener1 are guaranteed to be invoked before any before callbacks implemented by Listener2. Similarly, given the same two listeners registered in the same order, any after callbacks implemented by Listener1 are guaranteed to be invoked after any after callbacks implemented by Listener2. Listener1 is therefore said to wrap Listener2.

For a concrete example, consider the relationship between the TransactionaltestExecutionListener and the SqlScriptstestExecutionListener. The SqlScriptstestExecutionListener is registered after the TransactionaltestExecutionListener, so that SQL scripts are executed within a transaction managed by the TransactionaltestExecutionListener.

Registering testExecutionListener Implementations

A testExecutionListener can be registered explicitly for a test class, its subclasses, and its nested classes by using the @testExecutionListeners annotation. Explicit registration is suitable for custom listeners that are used in limited testing scenarios. However, it can become cumbersome if a custom listener needs to be used across an entire test suite. This issue is addressed through support for automatic discovery of default testExecutionListener implementations through the SpringFactoriesLoader mechanism. Specifically, default testExecutionListener implementations can be registered under the org.springframework.test.context.testExecutionListener key in a META-INF/spring.factories properties file.

Spring provides the following implementations. Each of these implements Ordered and is registered automatically by default.

Since:
2.5
Author:
Sam Brannen, Juergen Hoeller
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    default void
    aftertestClass(testContext testContext)
    Post-processes a test class after execution of all tests within the class.
    default void
    aftertestExecution(testContext testContext)
    Post-processes a test immediately after execution of the test method in the supplied test context — for example, for timing or logging purposes.
    default void
    aftertestMethod(testContext testContext)
    Post-processes a test after execution of after lifecycle callbacks of the underlying test framework — for example, by tearing down test fixtures.
    default void
    beforetestClass(testContext testContext)
    Pre-processes a test class before execution of all tests within the class.
    default void
    beforetestExecution(testContext testContext)
    Pre-processes a test immediately before execution of the test method in the supplied test context — for example, for timing or logging purposes.
    default void
    beforetestMethod(testContext testContext)
    Pre-processes a test before execution of before lifecycle callbacks of the underlying test framework — for example, by setting up test fixtures.
    default void
    preparetestInstance(testContext testContext)
    Prepares the test instance of the supplied test context — for example, to inject dependencies.

  • Method Details

    • beforetestClass

      default void beforetestClass(testContext testContext) throws Exception
      Pre-processes a test class before execution of all tests within the class.

      This method should be called immediately before framework-specific before class lifecycle callbacks.

      See the class-level documentation for details on wrapping behavior for lifecycle callbacks.

      The default implementation is empty. Can be overridden by concrete classes as necessary.

      Parameters:
      testContext - the test context for the test; never null
      Throws:
      Exception - allows any exception to propagate
      Since:
      3.0

    • preparetestInstance

      default void preparetestInstance(testContext testContext) throws Exception
      Prepares the test instance of the supplied test context — for example, to inject dependencies.

      This method should be called immediately after instantiation of the test class or as soon after instantiation as possible (as is the case with the SpringMethodRule). In any case, this method must be called prior to any framework-specific lifecycle callbacks.

      Since JUnit Jupiter 5.12, if the SpringExtension is used with a test-method scoped ExtensionContext, the Class returned from testContext.gettestClass() may refer to the test class for the current test method, which may be a @Nested test class within the class for the test instance. Thus, if you need consistent access to the class for the current test instance, you should invoke testContext.gettestInstance().getClass() instead of testContext.gettestClass().

      See the class-level documentation for details on wrapping behavior for listeners.

      The default implementation is empty. Can be overridden by concrete classes as necessary.

      Parameters:
      testContext - the test context for the test; never null
      Throws:
      Exception - allows any exception to propagate
      See Also:

    • beforetestMethod

      default void beforetestMethod(testContext testContext) throws Exception
      Pre-processes a test before execution of before lifecycle callbacks of the underlying test framework — for example, by setting up test fixtures.

      This method must be called immediately prior to framework-specific before lifecycle callbacks. For historical reasons, this method is named beforetestMethod. Since the introduction of beforetestExecution(testContext), a more suitable name for this method might be something like beforetestSetUp or beforeEach; however, it is unfortunately impossible to rename this method due to backward compatibility concerns.

      See the class-level documentation for details on wrapping behavior for lifecycle callbacks.

      The default implementation is empty. Can be overridden by concrete classes as necessary.

      Parameters:
      testContext - the test context in which the test method will be executed; never null
      Throws:
      Exception - allows any exception to propagate
      See Also:

    • beforetestExecution

      default void beforetestExecution(testContext testContext) throws Exception
      Pre-processes a test immediately before execution of the test method in the supplied test context — for example, for timing or logging purposes.

      This method must be called after framework-specific before lifecycle callbacks.

      See the class-level documentation for details on wrapping behavior for lifecycle callbacks.

      The default implementation is empty. Can be overridden by concrete classes as necessary.

      Parameters:
      testContext - the test context in which the test method will be executed; never null
      Throws:
      Exception - allows any exception to propagate
      Since:
      5.0
      See Also:

    • aftertestExecution

      default void aftertestExecution(testContext testContext) throws Exception
      Post-processes a test immediately after execution of the test method in the supplied test context — for example, for timing or logging purposes.

      This method must be called before framework-specific after lifecycle callbacks.

      See the class-level documentation for details on wrapping behavior for lifecycle callbacks.

      The default implementation is empty. Can be overridden by concrete classes as necessary.

      Parameters:
      testContext - the test context in which the test method will be executed; never null
      Throws:
      Exception - allows any exception to propagate
      Since:
      5.0
      See Also:

    • aftertestMethod

      default void aftertestMethod(testContext testContext) throws Exception
      Post-processes a test after execution of after lifecycle callbacks of the underlying test framework — for example, by tearing down test fixtures.

      This method must be called immediately after framework-specific after lifecycle callbacks. For historical reasons, this method is named aftertestMethod. Since the introduction of aftertestExecution(testContext), a more suitable name for this method might be something like aftertestTearDown or afterEach; however, it is unfortunately impossible to rename this method due to backward compatibility concerns.

      See the class-level documentation for details on wrapping behavior for lifecycle callbacks.

      The default implementation is empty. Can be overridden by concrete classes as necessary.

      Parameters:
      testContext - the test context in which the test method was executed; never null
      Throws:
      Exception - allows any exception to propagate
      See Also:

    • aftertestClass

      default void aftertestClass(testContext testContext) throws Exception
      Post-processes a test class after execution of all tests within the class.

      This method should be called immediately after framework-specific after class lifecycle callbacks.

      See the class-level documentation for details on wrapping behavior for lifecycle callbacks.

      The default implementation is empty. Can be overridden by concrete classes as necessary.

      Parameters:
      testContext - the test context for the test; never null
      Throws:
      Exception - allows any exception to propagate
      Since:
      3.0