Spring Boot 3.1.4集成Testcontainers批量测试时连接超时问题

核心原因 #

批量执行测试时连接超时的根本原因是Spring Test上下文缓存与Testcontainers容器生命周期的冲突，结合你的代码细节具体分析：

1. 你将MySQL容器定义在companion object中，属于静态全局单例，理论上JVM运行期间只会启动一次，端口固定。但批量测试时端口发生变化，说明容器被重复启动，大概率是因为：
   • 部分测试类触发了Spring上下文销毁（如使用@DirtiesContext），导致后续测试重新初始化上下文，但Testcontainers重启了容器并使用新端口；
   • @Testcontainers注解未被继承（该注解本身没有@Inherited元注解），若子类未显式标注该注解，Testcontainers无法正确管理抽象类中的静态容器，导致每个子类都启动新容器。
2. Spring上下文缓存机制会复用之前初始化的DataSource配置（包含旧容器端口），而新容器使用了新端口，最终导致Hikari连接池用旧端口连接新容器，触发超时。

解决方案 #

方案1：固定容器端口（快速解决） #

给MySQL容器指定固定的主机映射端口，确保每次启动都使用同一个端口，从根源避免端口变化：

companion object {
    @Container
    @ServiceConnection(type = [JdbcConnectionDetails::class])
    val mysql = MySQLContainer("mysql:latest")
        .withInitScript("test.sql")
        .withFixedExposedPort(3306, 3306) // 绑定主机3306端口到容器3306端口
}

⚠️ 注意：如果测试是并行执行的，固定端口会导致容器启动冲突，需改为串行执行测试。

方案2：禁用Spring上下文缓存（确保端口重新绑定） #

在抽象测试类上添加@DirtiesContext，让每个测试类执行完毕后销毁上下文，重新初始化时@ServiceConnection会自动绑定当前容器的最新端口：

@Testcontainers
@Transactional
@ActiveProfiles("test")
@SpringBootTest
@TestConstructor(autowireMode = TestConstructor.AutowireMode.ALL)
@DirtiesContext(classMode = DirtiesContext.ClassMode.AFTER_CLASS) // 每个测试类执行后销毁上下文
abstract class AbstractITest : AbstractTest() {
    // 容器代码保持不变
}

⚠️ 缺点：测试执行速度会变慢，因为每次测试都要重新启动Spring上下文。

方案3：使用实例级容器（独立隔离） #

将容器从静态companion object移到类的实例字段，让每个测试类都启动独立的容器，Spring会为每个测试类创建独立的上下文，@ServiceConnection会绑定对应容器的端口：

@Testcontainers
@Transactional
@ActiveProfiles("test")
@SpringBootTest
@TestConstructor(autowireMode = TestConstructor.AutowireMode.ALL)
abstract class AbstractITest : AbstractTest() {

    @Container
    @ServiceConnection(type = [JdbcConnectionDetails::class])
    val mysql = MySQLContainer("mysql:latest").withInitScript("test.sql")

}

⚠️ 注意：由于@Testcontainers注解不支持继承，每个子类需要显式标注@Testcontainers才能让Testcontainers管理容器。这种方式会增加测试总时间，但能彻底解决端口冲突问题。

方案4：确保@Testcontainers被正确识别 #

如果坚持使用静态容器，需确保所有子类都显式标注@Testcontainers，或者自定义一个带@Inherited的注解替代原生@Testcontainers：

@Target(AnnotationTarget.CLASS)
@Retention(AnnotationRetention.RUNTIME)
@Inherited
@Testcontainers
annotation class InheritedTestcontainers

然后在抽象类上使用这个自定义注解：

@InheritedTestcontainers
@Transactional
@ActiveProfiles("test")
@SpringBootTest
@TestConstructor(autowireMode = TestConstructor.AutowireMode.ALL)
abstract class AbstractITest : AbstractTest() {
    // 容器代码保持不变
}

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