使用TestContainers+Redis的Spring Boot JUnit5集成测试批量运行超时单测正常

核心触发原因 #

• 每个测试类独立注册RedisTestContainerExtension，每跑完一个测试类就执行一次Redis容器停止逻辑，下一个测试类启动新的Redis容器时，会生成新的随机映射宿主机端口
• Spring TestContext框架默认缓存已初始化的Spring上下文，当测试类的上下文配置相同时，不会重新读取环境变量、重建Redis连接工厂，导致连接始终指向已经被销毁的旧容器端口
• Lettuce客户端默认维护长连接与自动重连机制，即使旧端口无服务监听，客户端也会持续尝试重连，直到触发1分钟的命令超时阈值抛出异常
• 单独运行测试时流程串行无上下文复用、无旧连接残留，因此不会触发上述问题

具体修复步骤 #

1. 改造Redis容器为全局单例模式 #

取消单个测试类执行完成后就停止容器的逻辑，将Redis容器改为JVM级别的全局单例，仅在整个测试套件启动时初始化一次，所有测试类共享同一个容器实例，避免随机端口频繁变化。
修改后的扩展类参考代码：

public class RedisTestContainerExtension implements BeforeAllCallback {
    // 全局静态单例容器，仅初始化一次
    private static final GenericContainer<?> REDIS_CONTAINER = new GenericContainer<>(
            DockerImageName.parse("redis:5.0.3-alpine"))
            .withCommand("redis-server", "--requirepass", "password")
            .waitingFor(Wait.forListeningPort())
            .withStartupTimeout(Duration.ofMinutes(2))
            .withExposedPorts(6379);

    static {
        // 容器首次被引用时启动，仅执行一次
        REDIS_CONTAINER.start();
        // 全局写入连接参数，所有测试上下文通用
        System.setProperty("APP_REDIS_CONVERSATIONS_HOST", REDIS_CONTAINER.getHost());
        System.setProperty("APP_REDIS_CONVERSATIONS_PORT", REDIS_CONTAINER.getFirstMappedPort().toString());
        System.setProperty("APP_REDIS_CONVERSATIONS_PASSWORD", "password");
        System.setProperty("APP_REDIS_CONVERSATIONS_TTL", "600m");
        // 注册JVM关闭钩子，所有测试执行完成后再统一停止容器
        Runtime.getRuntime().addShutdownHook(new Thread(REDIS_CONTAINER::stop));
    }

    @Override
    public void beforeAll(ExtensionContext extensionContext) {
        // 仅校验容器运行状态，不做启停操作
        if (!REDIS_CONTAINER.isRunning()) {
            throw new IllegalStateException("共享Redis容器未正常启动");
        }
    }
}

2. 匹配Spring上下文缓存规则 #

使用全局固定的容器连接参数后，所有测试类的Spring上下文配置签名一致，TestContext框架可正常复用缓存的上下文，不会出现连接参数与实际容器不匹配的问题。
测试类可以保留原有@ExtendWith注解，无需额外修改，因为扩展类现在的逻辑不会再触发容器的频繁启停。

3. 优化Lettuce连接配置 #

针对测试场景调整Lettuce客户端参数，缩短异常感知时间，避免连接残留导致的超时阻塞，参考测试环境配置：

@Configuration
public class TestRedisConfiguration {
    @Bean
    public LettuceConnectionFactory redisConnectionFactory() {
        RedisStandaloneConfiguration serverConfig = new RedisStandaloneConfiguration();
        serverConfig.setHostName(System.getProperty("APP_REDIS_CONVERSATIONS_HOST"));
        serverConfig.setPort(Integer.parseInt(System.getProperty("APP_REDIS_CONVERSATIONS_PORT")));
        serverConfig.setPassword(RedisPassword.of(System.getProperty("APP_REDIS_CONVERSATIONS_PASSWORD")));

        LettuceClientConfiguration clientConfig = LettuceClientConfiguration.builder()
                // 缩短命令超时时间，快速暴露连接问题
                .commandTimeout(Duration.ofSeconds(10))
                // 上下文销毁时快速关闭连接，避免残留
                .shutdownTimeout(Duration.ofSeconds(2))
                .build();
        return new LettuceConnectionFactory(serverConfig, clientConfig);
    }
}

4. 测试数据隔离方案 #

因为所有测试类共享同一个Redis容器，需要在每个测试方法执行前主动清空Redis中的测试数据，避免用例之间的数据污染，无需通过重启容器实现数据隔离。

内容的提问来源于stack exchange，提问作者Dimitri