Spring TestExecutionListener 详解

1. 概述

我们通常使用 JUnit 提供的 @BeforeEach、@AfterEach、@BeforeAll 和 @AfterAll 等注解来管理测试的生命周期。但在 Spring 项目中，这些基础机制往往不够用——尤其是当你需要与 Spring 容器深度交互时。

这时候，Spring 的 TestExecutionListener 就派上用场了。

本文将带你搞清楚：

✅ TestExecutionListener 到底是什么
✅ Spring 默认提供了哪些监听器
✅ 如何实现并注册一个自定义监听器

掌握这些，能让你在写集成测试时更加游刃有余，比如自动注入上下文、动态切换数据源、甚至埋点监控测试执行流程。

2. `TestExecutionListener` 接口详解

先来看核心接口定义：

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 {};
}

这个接口允许你在测试执行的各个阶段插入自定义逻辑。每个方法都会接收到一个 TestContext 对象，它包含了：

当前 Spring 应用上下文（ApplicationContext）
正在执行的测试类和方法信息
测试实例本身

你可以基于这些信息做各种扩展，比如：

在测试前动态修改 Bean 定义
记录每个测试方法的执行耗时
自动清理缓存或重置数据库状态

各方法触发时机一览

方法	触发时机
`beforeTestClass`	在整个测试类执行前（所有 `@Test` 方法运行之前）✅
`prepareTestInstance`	测试实例创建后，依赖注入前 ⚠️
`beforeTestMethod`	在 `@BeforeEach` 之前执行 ❗注意顺序
`beforeTestExecution`	紧挨着测试方法执行前（`@BeforeEach` 之后）✅
`afterTestExecution`	紧挨着测试方法执行后（`@AfterEach` 之前）✅
`afterTestMethod`	在 `@AfterEach` 执行完毕后 ❗注意顺序
`afterTestClass`	整个测试类所有方法执行完之后 ✅

💡 提示：Java 8 接口默认方法特性让实现类只需覆盖关心的方法，不用全写一遍，设计很贴心。

3. Spring 默认提供的监听器

Spring 框架默认内置了多个 TestExecutionListener 实现，并按固定顺序注册。以下是关键实现及其作用：

✅ DependencyInjectionTestExecutionListener
负责自动装配测试类中的 @Autowired 字段，没它你就不能在测试里用依赖注入。

✅ TransactionalTestExecutionListener
开启事务支持，默认测试结束后自动回滚，避免污染数据库。经典“写测试不脏库”机制就靠它。

✅ DirtiesContextTestExecutionListener
处理 @DirtiesContext 注解，标记当前测试会破坏应用上下文状态，后续测试需重建上下文。

✅ SqlScriptsTestExecutionListener
自动执行 @Sql 注解指定的 SQL 脚本，常用于准备测试数据。

✅ ServletTestExecutionListener
为 Web 环境测试初始化 Mock Servlet API 支持，比如 MockHttpServletRequest。

这些监听器在底层是有序注册的，顺序很重要。例如依赖注入必须早于事务初始化，否则 Bean 都没注入谈何事务？

4. 自定义 `TestExecutionListener`

有时候默认功能不够用，比如你想：

统计每个测试类的执行时间
打印测试方法入参日志
集成 APM 埋点

这时就得自己写监听器了。

示例：一个简单的日志监听器

public class CustomTestExecutionListener 
    implements TestExecutionListener, Ordered {

    private static final Logger logger = 
        LoggerFactory.getLogger(CustomTestExecutionListener.class);

    @Override
    public void beforeTestClass(TestContext testContext) throws Exception {
        logger.info("▶️ 开始执行测试类: {}", testContext.getTestClass().getSimpleName());
    }

    @Override
    public void prepareTestInstance(TestContext testContext) throws Exception {
        logger.info("🔧 准备测试实例: {}", testContext.getTestClass().getName());
    }

    @Override
    public void beforeTestMethod(TestContext testContext) throws Exception {
        logger.info("🏃 即将执行方法: {}.{}()", 
            testContext.getTestClass().getSimpleName(),
            testContext.getTestMethod().getName());
    }

    @Override
    public void afterTestMethod(TestContext testContext) throws Exception {
        logger.info("✅ 方法执行完成: {}.{}()", 
            testContext.getTestClass().getSimpleName(),
            testContext.getTestMethod().getName());
    }

    @Override
    public void afterTestClass(TestContext testContext) throws Exception {
        logger.info("🏁 测试类执行结束: {}", testContext.getTestClass().getSimpleName());
    }

    @Override
    public int getOrder() {
        return Integer.MAX_VALUE; // 最低优先级
    }
}

这个监听器会在测试各个阶段输出日志，方便排查问题。

4.1 使用 `@TestExecutionListeners` 注册

最直接的方式是在测试类上使用 @TestExecutionListeners 注解：

@RunWith(SpringRunner.class)
@TestExecutionListeners({
    CustomTestExecutionListener.class,
    DependencyInjectionTestExecutionListener.class
})
@ContextConfiguration(classes = AdditionService.class)
public class AdditionServiceUnitTest {
    
    @Autowired
    private AdditionService additionService;

    @Test
    public void whenValidNumbersPassed_thenReturnSum() {
        int result = additionService.add(2, 3);
        assertEquals(5, result);
    }
}

⚠️ 踩坑提醒：
使用 @TestExecutionListeners 会覆盖所有默认监听器！
上面例子中如果不手动加上 DependencyInjectionTestExecutionListener，@Autowired 就失效了。

合并模式：保留默认 + 添加自定义

解决覆盖问题的优雅方式是启用合并模式：

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

这样你的自定义监听器会和 Spring 默认的合并注册，无需重复列出所有默认项，省心又安全。

4.2 自动发现机制（推荐）

如果项目里多个测试都需要同一个监听器，每个类都加注解太麻烦。这时候可以用 Spring 的自动发现机制。

只需要在 src/main/resources/META-INF/spring.factories 中添加：

org.springframework.test.context.TestExecutionListener=\
com.example.listener.CustomTestExecutionListener

Spring 启动时会通过 SpringFactoriesLoader 自动加载这个配置，全局生效。

🎯 场景建议：

团队级通用监听器（如性能监控、审计日志）→ 用 spring.factories

单个测试特殊需求 → 用 @TestExecutionListeners

4.3 监听器执行顺序控制

当多个监听器存在时，执行顺序至关重要。比如：

你不能在 Bean 注入前就尝试访问它们
清理操作必须在事务提交/回滚之后

Spring 使用 AnnotationAwareOrderComparator 对监听器排序，支持两种方式指定顺序：

方式一：实现 `Ordered` 接口

public class CustomTestExecutionListener implements TestExecutionListener, Ordered {
    @Override
    public int getOrder() {
        return 10000; // 数值越小优先级越高
    }
}

方式二：使用 `@Order` 注解（更简洁）

@Order(10000)
public class CustomTestExecutionListener implements TestExecutionListener {
    // ...
}

📌 建议：
Spring 内置监听器的 order 值通常在 Ordered.LOWEST_PRECEDENCE 附近，自定义监听器设为 Integer.MAX_VALUE 可确保最后执行，避免干扰核心流程。

5. 总结

TestExecutionListener 是 Spring 测试框架的底层钩子机制，虽然平时不常直接接触，但它是很多高级测试功能的基础。

关键点回顾：

✅ 它让你能在测试生命周期的任意阶段插入逻辑
✅ 默认监听器提供了 DI、事务、SQL 脚本等核心能力
✅ 自定义监听器可通过注解或 spring.factories 注册
✅ 使用 mergeMode = MERGE_WITH_DEFAULTS 避免覆盖默认行为
✅ 注意监听器顺序，必要时通过 @Order 控制

掌握这套机制后，你可以轻松实现：

测试性能分析
自动化测试报告生成
多数据源切换
Mock 动态配置

💬 小贴士：源码已托管至 GitHub，建议结合实际项目调试体验。
👉 https://github.com/your-repo/spring-testing-demo

Persistence

REST

Security