The Spring TestExecutionListener

 1. Overview

Typically, we use the JUnit annotations like @BeforeEach, @AfterEach, @BeforeAll, and @AfterAll, to orchestrate tests' lifecycle, but sometimes that's not enough — especially when we're working with the Spring framework.

This is where Spring TestExecutionListener comes in handy.

In this tutorial, we'll see what the TestExecutionListener offers, the default listeners provided by Spring, and how to implement a custom TestExecutionListener.

2. The TestExecutionListener Interface

First, let's visit the TestExecutionListener interface:

public interface TestExecutionListener {
    default void beforeTestClass(TestContext testContext) throws Exception {};
    default void prepareTestInstance(TestContext testContext) throws Exception {};
    default void beforeTestMethod(TestContext testContext) throws Exception {};
    default void afterTestMethod(TestContext testContext) throws Exception {};
    default void afterTestClass(TestContext testContext) throws Exception {};
}

The implementations of this interface can receive events during different test execution stages. Consequently, each of the methods in the interface is passed a TestContext object.

This TestContext object contains information of the Spring context and of the target test class and methods. This information can be used to alter the behavior of the tests or to extend their functionality.

Now, let's take a quick look at each of these methods:

• afterTestClass – post-processes a test class after execution of all tests within the class
• afterTestExecution – post-processes a test immediately after execution of the test method in the supplied test context
• afterTestMethod – post-processes a test after execution of after-lifecycle callbacks of the underlying test framework
• beforeTestClass – pre-processes a test class before execution of all tests within the class
• beforeTestExecution – pre-processes a test immediately before execution of the test method in the supplied test context
• beforeTestMethod – pre-processes a test before execution of before-lifecycle callbacks of the underlying test framework
• prepareTestInstance – prepares the test instance of the supplied test context

It's worth noting that this interface provides empty default implementations for all the methods. Consequently, concrete implementations can choose to override only those methods that are suitable for the task at hand.

3. Spring's Default TestExecutionListeners

By default, Spring provides some TestExecutionListener implementations out-of-the-box.

Let's quickly look at each of these:

• ServletTestExecutionListener – configures Servlet API mocks for a WebApplicationContext
• DirtiesContextBeforeModesTestExecutionListener – handles the @DirtiesContext annotation for “before” modes
• DependencyInjectionTestExecutionListener – provides dependency injection for the test instance
• DirtiesContextTestExecutionListener – handles the @DirtiesContext annotation for “after” modes
• TransactionalTestExecutionListener – provides transactional test execution with default rollback semantics
• SqlScriptsTestExecutionListener – runs SQL scripts configured using the @Sql annotation

These listeners are pre-registered exactly in the order listed. We'll see more about the order when we create a custom TestExecutionListener.

4. Using a Custom TestExecutionListener

Now, let's define a custom TestExecutionListener:

public class CustomTestExecutionListener implements TestExecutionListener, Ordered {
    private static final Logger logger = LoggerFactory.getLogger(CustomTestExecutionListener.class);
    
    public void beforeTestClass(TestContext testContext) throws Exception {
        logger.info("beforeTestClass : {}", testContext.getTestClass());
    }; 
    
    public void prepareTestInstance(TestContext testContext) throws Exception {
        logger.info("prepareTestInstance : {}", testContext.getTestClass());
    }; 
    
    public void beforeTestMethod(TestContext testContext) throws Exception {
        logger.info("beforeTestMethod : {}", testContext.getTestMethod());
    }; 
    
    public void afterTestMethod(TestContext testContext) throws Exception {
        logger.info("afterTestMethod : {}", testContext.getTestMethod());
    }; 
    
    public void afterTestClass(TestContext testContext) throws Exception {
        logger.info("afterTestClass : {}", testContext.getTestClass());
    }

    @Override
    public int getOrder() {
        return Integer.MAX_VALUE;
    };
}

For simplicity, all this class does is log some of the TestContext information.

4.1. Registering the Custom Listener Using @TestExecutionListeners

Now, let's use this listener in our test class. To do this, we'll register it by using the @TestExecutionListeners annotation:

@RunWith(SpringRunner.class)
@TestExecutionListeners(value = {
  CustomTestExecutionListener.class,
  DependencyInjectionTestExecutionListener.class
})
@ContextConfiguration(classes = AdditionService.class)
public class AdditionServiceUnitTest {
    // ...
}

It's important to note that using the annotation will de-register all default listeners. Hence, we've added DependencyInjectionTestExecutionListener explicitly so that we can use autowiring in our test class.

If we need any of the other default listeners, we'll have to specify each of them. But, we can also use the mergeMode property of the annotation:

@TestExecutionListeners(
  value = { CustomTestExecutionListener.class }, 
  mergeMode = MergeMode.MERGE_WITH_DEFAULTS)

Here, MERGE_WITH_DEFAULTS indicates that the locally declared listeners should be merged with the default listeners.

Now, when we run the above test, the listener will log each event it receives:

[main] INFO  o.s.t.c.s.DefaultTestContextBootstrapper - Using TestExecutionListeners: 
[com.baeldung.testexecutionlisteners.CustomTestExecutionListener@38364841, 
org.springframework.test.context.support.DependencyInjectionTestExecutionListener@28c4711c]
[main] INFO  c.b.t.CustomTestExecutionListener - beforeTestClass : 
class com.baeldung.testexecutionlisteners.TestExecutionListenersWithoutMergeModeUnitTest
[main] INFO  c.b.t.CustomTestExecutionListener - prepareTestInstance : 
class com.baeldung.testexecutionlisteners.TestExecutionListenersWithoutMergeModeUnitTest
[main] INFO  o.s.c.s.GenericApplicationContext - 
Refreshing org.springframework.context.support.GenericApplicationContext@7d68ef40: startup date [XXX]; 
root of context hierarchy
[main] INFO  c.b.t.CustomTestExecutionListener - beforeTestMethod : 
public void com.baeldung.testexecutionlisteners.TestExecutionListenersWithoutMergeModeUnitTest
.whenValidNumbersPassed_thenReturnSum()
[main] INFO  c.b.t.CustomTestExecutionListener - afterTestMethod : 
public void com.baeldung.testexecutionlisteners.TestExecutionListenersWithoutMergeModeUnitTest
.whenValidNumbersPassed_thenReturnSum()
[main] INFO  c.b.t.CustomTestExecutionListener - afterTestClass : 
class com.baeldung.testexecutionlisteners.TestExecutionListenersWithoutMergeModeUnitTest

4.2. Automatic Discovery of Default TestExecutionListener Implementations

Using @TestExecutionListener to register listeners is suitable if it's used in a limited number of test classes. But, it can become cumbersome to add it to an entire test suite.

We can address this problem by taking advantage of the support provided by the SpringFactoriesLoader mechanism for the automatic discovery of TestExecutionListener implementations.

The spring-test module declares all core default listeners under the org.springframework.test.context.TestExecutionListener key in its META-INF/spring.factories properties file. Similarly, we can register our custom listener by using the above key in our own META-INF/spring.factories properties file:

org.springframework.test.context.TestExecutionListener=\
com.baeldung.testexecutionlisteners.CustomTestExecutionListener

4.3. Ordering Default TestExecutionListener Implementations

When Spring discovers default TestExecutionListener implementations through the SpringFactoriesLoader mechanism, it'll sort them by using Spring’s AnnotationAwareOrderComparator. This honors Spring’s Ordered interface and @Order annotation for ordering.

Note that all default TestExecutionListener implementations provided by Spring implement Ordered with appropriate values. Therefore, we have to make sure that our custom TestExecutionListener implementation is registered with the proper order. Consequently, we've implemented Ordered in our custom listener:

public class CustomTestExecutionListener implements TestExecutionListener, Ordered {
    // ...
    @Override
    public int getOrder() {
        return Integer.MAX_VALUE;
    };
}

But, we can use the @Order annotation instead.

5. Conclusion

In this article, we saw how to implement a custom TestExecutionListener. We also looked at the default listeners provided by the Spring framework.

And, of course, the code accompanying this article is available over on GitHub.