Spring Boot 3.1 ImportTestContainers使用失败求助

问题说明 #

已经给项目添加了test作用域的spring-boot-testcontainers依赖，先后尝试三种容器声明方式均未成功：

• 接口字段声明容器
• 类中静态字段声明容器
• 带DynamicPropertyRegistry参数的方法返回容器

几个排查要点 #

1. 依赖版本必须严格匹配 #

spring-boot-testcontainers的版本要和Spring Boot 3.1的版本完全一致，避免版本不兼容。检查项目依赖配置（pom.xml或build.gradle）：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-testcontainers</artifactId>
    <scope>test</scope>
    <version>3.1.x</version> <!-- 此处x需与你使用的Spring Boot小版本完全对应 -->
</dependency>

2. 注解使用要规范 #

• @ImportTestContainers需标注在测试类或配置类上，对应的容器声明类要被正确导入
• 用接口字段声明容器时，接口必须添加@TestConfiguration注解，测试类还要通过@Import导入该接口
• 静态字段声明容器时，字段需用@Container标记，部分场景下测试类还需配合@Testcontainers注解使用

3. 容器属性绑定要正确 #

使用带DynamicPropertyRegistry参数的方法时，要确保容器连接属性绑定无误，以PostgreSQL为例：

@TestConfiguration
public class TestContainerConfig {
    @Bean
    public PostgreSQLContainer<?> postgresContainer(DynamicPropertyRegistry registry) {
        PostgreSQLContainer<?> container = new PostgreSQLContainer<>("postgres:15-alpine");
        registry.add("spring.r2dbc.url", () -> String.format("r2dbc:postgresql://%s:%s/%s",
                container.getHost(), container.getMappedPort(PostgreSQLContainer.POSTGRESQL_PORT), container.getDatabaseName()));
        registry.add("spring.r2dbc.username", container::getUsername);
        registry.add("spring.r2dbc.password", container::getPassword);
        return container;
    }
}

测试类需通过@ImportTestContainers(TestContainerConfig.class)导入该配置类。

4. 测试类注解组合不能少 #

测试类要添加必要的上下文启动注解，比如：

@SpringBootTest
@ImportTestContainers(TestContainerConfig.class)
public class MyRepositoryTest {
    // 测试逻辑代码
}

不要遗漏@SpringBootTest这类触发Spring上下文加载的注解。

5. 检查Testcontainers核心依赖 #

部分场景下spring-boot-testcontainers不会自动引入testcontainers-core，如果缺失会导致容器无法启动，需手动添加test作用域的依赖：

<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>testcontainers</artifactId>
    <scope>test</scope>
</dependency>

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