SpringBoot TestContainers测试HikariPool超时及容器复用问题

现有配置存在3个核心问题，直接触发两类报错：

• 变量名拼写错误：定义的容器静态变量名为postgreSQLContainer，但静态代码块、上下文初始化器中引用的变量名是postgreDBContainer，会直接触发空指针或编译错误。
• 生命周期配置冲突：@Testcontainers配合@Container注解使用时，默认会在每个测试类执行完成后清理关联的容器资源，即使配置了withReuse(true)，也会出现Spring测试上下文刷新后，Hikari连接池指向已被释放的旧端口的问题，触发连接拒绝、获取连接超时错误。
• 初始化脚本重复执行：withInitScript只会在容器首次创建启动时执行，如果配置不当导致容器重复创建、未命中复用逻辑，就会重复执行建表语句，抛出表已存在的错误。

1. 开启Testcontainers全局复用开关 #

在测试资源目录src/test/resources下新建testcontainers.properties文件，添加如下配置开启全局复用支持：

testcontainers.reuse.enable=true

2. 重写抽象测试基类 #

移除类上的@Testcontainers注解、字段上的@Container注解，避免Testcontainers默认的生命周期管理干扰容器复用逻辑，手动维护全局单例容器，保证所有测试类共用同一个容器实例：

@ActiveProfiles("test")
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)
@ContextConfiguration(initializers = AbstractIT.DockerPostgreDataSourceInitializer.class)
public abstract class AbstractIT {

    // JVM加载类时初始化一次，所有测试类共用该实例
    @SuppressWarnings("resource")
    static final PostgreSQLContainer<?> POSTGRES_CONTAINER;

    static {
        POSTGRES_CONTAINER = new PostgreSQLContainer<>("postgres:14")
                .withUsername("postgres")
                .withPassword("postgres")
                .withInitScript("sql/init.sql")
                .withDatabaseName("test")
                .withReuse(true);
        // 复用模式下多次调用start()不会重复创建容器，只会复用已运行的实例
        POSTGRES_CONTAINER.start();
    }

    public static class DockerPostgreDataSourceInitializer implements ApplicationContextInitializer<ConfigurableApplicationContext> {
        @Override
        public void initialize(ConfigurableApplicationContext applicationContext) {
            TestPropertySourceUtils.addInlinedPropertiesToEnvironment(
                    applicationContext,
                    "spring.datasource.url=" + POSTGRES_CONTAINER.getJdbcUrl(),
                    "spring.datasource.username=" + POSTGRES_CONTAINER.getUsername(),
                    "spring.datasource.password=" + POSTGRES_CONTAINER.getPassword()
            );
        }
    }
}

3. 测试数据隔离配置 #

不要使用@DirtiesContext注解重建上下文：该注解会销毁并重建Spring应用上下文，触发Hikari连接池重建，反而容易引发连接异常。测试数据隔离推荐两种方案实现：

• 给测试类加@Transactional注解，测试方法执行完成后自动回滚所有事务操作，不会残留测试数据
• 对于不支持事务回滚的测试场景，在@BeforeEach/@AfterEach生命周期方法中编写清理SQL，手动清空表数据

• 复用模式下测试容器不会在测试执行结束后自动停止，后续执行测试会直接复用已运行的容器，初始化脚本仅在容器第一次创建时执行一次，不会出现表重复创建的问题。需要重置数据库时，手动在Docker中删除对应的PostgreSQL容器即可。
• 所有集成测试类必须统一继承AbstractIT基类，不要单独定义其他Testcontainers配置，避免出现多容器实例、连接信息不一致的问题。
• 不需要额外调大Hikari连接超时时间，容器正常运行的情况下默认30秒超时完全足够。

报错参考：
SqlExceptionHelper : HikariPool-1 - Connection is not available, request timed out after 30000ms.
o.h.engine.jdbc.spi.SqlExceptionHelper : Connection to localhost:49168 refused. Check that the hostname and port are correct and that the postmaster is accepting TCP/IP connections.

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