|
对于最新的稳定版本，请使用 Spring Boot 3.5.5！ |
测试容器
Testcontainers 库提供了一种管理在 Docker 容器内运行的服务的方法。它与 JUnit 集成，允许您编写一个测试类，该类可以在任何测试运行之前启动容器。Testcontainers 对于编写与实际后端服务（如 MySQL、MongoDB、Cassandra 等）通信的集成测试特别有用。
在以下部分中，我们将描述一些可用于将 Testcontainers 与测试集成的方法。
使用 Spring Beans
Testcontainers 提供的容器可以作为 Bean 进行 Spring Boot 管理。
要将容器声明为 bean，请添加一个@Bean方法添加到您的测试配置中：
-
Java
-
Kotlin
import org.testcontainers.containers.MongoDBContainer;
import org.testcontainers.utility.DockerImageName;
import org.springframework.boot.test.context.TestConfiguration;
import org.springframework.context.annotation.Bean;
@TestConfiguration(proxyBeanMethods = false)
class MyTestConfiguration {
@Bean
MongoDBContainer mongoDbContainer() {
return new MongoDBContainer(DockerImageName.parse("mongo:5.0"));
}
}import org.springframework.boot.test.context.TestConfiguration
import org.springframework.context.annotation.Bean
import org.testcontainers.containers.MongoDBContainer
import org.testcontainers.utility.DockerImageName
@TestConfiguration(proxyBeanMethods = false)
class MyTestConfiguration {
@Bean
fun mongoDbContainer(): MongoDBContainer {
return MongoDBContainer(DockerImageName.parse("mongo:5.0"))
}
}然后，您可以通过在测试类中导入配置类来注入和使用容器：
-
Java
-
Kotlin
import org.junit.jupiter.api.Test;
import org.testcontainers.containers.MongoDBContainer;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.context.annotation.Import;
@SpringBootTest
@Import(MyTestConfiguration.class)
class MyIntegrationTests {
@Autowired
private MongoDBContainer mongo;
@Test
void myTest() {
...
}
}import org.junit.jupiter.api.Test
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.boot.test.context.SpringBootTest
import org.springframework.context.annotation.Import
import org.testcontainers.containers.MongoDBContainer
@SpringBootTest
@Import(MyTestConfiguration::class)
class MyIntegrationTests {
@Autowired
private val mongo: MongoDBContainer? = null
@Test
fun myTest() {
...
}
}| 这种管理容器的方法通常与服务连接注释结合使用。 |
使用 JUnit 扩展
Testcontainers 提供了一个 JUnit 扩展，可用于管理测试中的容器。通过应用@Testcontainers将 Testcontainers 注释到测试类。
然后，您可以使用@Container静态容器字段上的注释。
这@Testcontainers注释可用于普通 JUnit 测试，或与@SpringBootTest:
-
Java
-
Kotlin
import org.junit.jupiter.api.Test;
import org.testcontainers.containers.Neo4jContainer;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;
import org.springframework.boot.test.context.SpringBootTest;
@Testcontainers
@SpringBootTest
class MyIntegrationTests {
@Container
static Neo4jContainer<?> neo4j = new Neo4jContainer<>("neo4j:5");
@Test
void myTest() {
...
}
}import org.junit.jupiter.api.Test;
import org.testcontainers.containers.Neo4jContainer;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;
import org.springframework.boot.test.context.SpringBootTest;
@Testcontainers
@SpringBootTest
class MyIntegrationTests {
@Test
fun myTest() {
...
}
companion object {
@Container
@JvmStatic
val neo4j = Neo4jContainer("neo4j:5");
}
}上面的示例将在运行任何测试之前启动一个 Neo4j 容器。容器实例的生命周期由 Testcontainers 管理，如其官方文档中所述。
| 在大多数情况下，您还需要配置应用程序以连接到容器中运行的服务。 |
导入容器配置接口
Testcontainers 的常见模式是将容器实例声明为接口中的静态字段。
例如，以下接口声明两个容器，一个名为mongo类型MongoDBContainer另一个名为neo4j类型Neo4jContainer:
-
Java
-
Kotlin
import org.testcontainers.containers.MongoDBContainer;
import org.testcontainers.containers.Neo4jContainer;
import org.testcontainers.junit.jupiter.Container;
interface MyContainers {
@Container
MongoDBContainer mongoContainer = new MongoDBContainer("mongo:5.0");
@Container
Neo4jContainer<?> neo4jContainer = new Neo4jContainer<>("neo4j:5");
}import org.testcontainers.containers.MongoDBContainer
import org.testcontainers.containers.Neo4jContainer
import org.testcontainers.junit.jupiter.Container
interface MyContainers {
companion object {
@Container
val mongoContainer: MongoDBContainer = MongoDBContainer("mongo:5.0")
@Container
val neo4jContainer: Neo4jContainer<*> = Neo4jContainer("neo4j:5")
}
}当您以这种方式声明容器时，您可以通过让测试类实现接口在多个测试中重用它们的配置。
也可以在 Spring Boot 测试中使用相同的接口配置。为此，请添加@ImportTestcontainers到测试配置类：
-
Java
-
Kotlin
import org.springframework.boot.test.context.TestConfiguration;
import org.springframework.boot.testcontainers.context.ImportTestcontainers;
@TestConfiguration(proxyBeanMethods = false)
@ImportTestcontainers(MyContainers.class)
class MyTestConfiguration {
}import org.springframework.boot.test.context.TestConfiguration
import org.springframework.boot.testcontainers.context.ImportTestcontainers
@TestConfiguration(proxyBeanMethods = false)
@ImportTestcontainers(MyContainers::class)
class MyTestConfiguration {
}托管容器的生命周期
如果您使用了 Testcontainers 提供的注解和扩展，那么容器实例的生命周期完全由 Testcontainers 管理。有关信息，请参阅官方 Testcontainers 文档。
当容器由 Spring 作为 bean 管理时，它们的生命周期由 Spring 管理：
-
容器 Bean 在所有其他 Bean 之前创建和启动。
-
容器 bean 在销毁所有其他 bean 后停止。
此过程确保任何依赖于容器提供的功能的 Bean 都可以使用这些功能。 它还确保在容器仍然可用时将它们清理干净。
| 当您的应用程序 Bean 依赖于容器的功能时，最好将容器配置为 Spring Bean 以确保正确的生命周期行为。 |
| 将容器由 Testcontainers 而不是作为 Spring Bean 管理并不能保证 Bean 和容器的关闭顺序。 在清理依赖容器功能的 Bean 之前，容器可能会被关闭。 这可能导致客户端 Bean 抛出异常，例如，由于连接丢失。 |
容器 bean 在由 Spring 的 TestContext 框架管理的每个应用程序上下文中创建和启动一次。 有关 TestContext Framework 如何管理其中的底层应用程序上下文和 bean 的详细信息，请参阅 Spring Framework 文档。
容器 Bean 作为 TestContext 框架标准应用程序上下文关闭过程的一部分停止。 当应用程序上下文关闭时，容器也会关闭。 这通常发生在使用该特定缓存应用程序上下文的所有测试执行完毕后。 它也可能更早发生，具体取决于在 TestContext 框架中配置的缓存行为。
| 单个测试容器实例可以而且通常在执行来自多个测试类的测试时保留。 |
服务连接
服务连接是与任何远程服务的连接。 Spring Boot 的自动配置可以使用服务连接的详细信息，并使用它们来建立与远程服务的连接。 执行此作时，连接详细信息优先于任何与连接相关的配置属性。
使用 Testcontainers 时，可以通过注释测试类中的容器字段来自动为容器中运行的服务创建连接详细信息。
-
Java
-
Kotlin
import org.junit.jupiter.api.Test;
import org.testcontainers.containers.Neo4jContainer;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.testcontainers.service.connection.ServiceConnection;
@Testcontainers
@SpringBootTest
class MyIntegrationTests {
@Container
@ServiceConnection
static Neo4jContainer<?> neo4j = new Neo4jContainer<>("neo4j:5");
@Test
void myTest() {
...
}
}import org.junit.jupiter.api.Test;
import org.testcontainers.containers.Neo4jContainer;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.testcontainers.service.connection.ServiceConnection;
@Testcontainers
@SpringBootTest
class MyIntegrationTests {
@Test
fun myTest() {
...
}
companion object {
@Container
@ServiceConnection
@JvmStatic
val neo4j = Neo4jContainer("neo4j:5");
}
}由于@ServiceConnection，上述配置允许应用程序中的 Neo4j 相关 bean 与在 Testcontainers 管理的 Docker 容器内运行的 Neo4j 进行通信。
这是通过自动定义Neo4jConnectionDetailsbean，然后由 Neo4j 自动配置使用，覆盖任何与连接相关的配置属性。
您需要添加spring-boot-testcontainers模块作为测试依赖项，以便将服务连接与 Testcontainers 一起使用。 |
服务连接注释由ContainerConnectionDetailsFactory注册的类spring.factories.
一个ContainerConnectionDetailsFactory可以创建一个ConnectionDetailsbean 基于特定的Container子类或 Docker 镜像名称。
以下服务连接工厂在spring-boot-testcontainers罐：
| 连接详细信息 | 匹配时间 |
|---|---|
名为“symptoma/activemq”的容器或 |
|
名为“otel/opentelemetry-collector-contrib”或类型为 |
|
名为“otel/opentelemetry-collector-contrib”或类型为 |
|
名为“otel/opentelemetry-collector-contrib”或类型为 |
|
类型 |
|
类型 |
|
名为“openzipkin/zipkin”的容器 |
|
默认情况下，将为给定的 Bean 创建所有适用的连接详细信息 Bean 如果只想创建适用类型的子集，可以使用 |
默认情况下Container.getDockerImageName().getRepository()用于获取用于查找连接详细信息的名称。
Docker 映像名称的存储库部分忽略任何注册表和版本。
只要 Spring Boot 能够获取Container，当使用static字段，如上例所示。
如果您使用@Bean方法，Spring Boot 不会调用 bean 方法来获取 Docker 镜像名称，因为这会导致急切初始化问题。
相反，bean 方法的返回类型用于找出应该使用哪个连接详细信息。
只要您使用类型化容器，例如Neo4jContainer或RabbitMQContainer.
如果您正在使用GenericContainer，例如使用 Redis，如以下示例所示：
-
Java
-
Kotlin
import org.testcontainers.containers.GenericContainer;
import org.springframework.boot.test.context.TestConfiguration;
import org.springframework.boot.testcontainers.service.connection.ServiceConnection;
import org.springframework.context.annotation.Bean;
@TestConfiguration(proxyBeanMethods = false)
public class MyRedisConfiguration {
@Bean
@ServiceConnection(name = "redis")
public GenericContainer<?> redisContainer() {
return new GenericContainer<>("redis:7");
}
}import org.springframework.boot.test.context.TestConfiguration
import org.springframework.boot.testcontainers.service.connection.ServiceConnection
import org.springframework.context.annotation.Bean
import org.testcontainers.containers.GenericContainer
@TestConfiguration(proxyBeanMethods = false)
class MyRedisConfiguration {
@Bean
@ServiceConnection(name = "redis")
fun redisContainer(): GenericContainer<*> {
return GenericContainer("redis:7")
}
}Spring Boot 无法从GenericContainer使用哪个容器镜像，因此name属性从@ServiceConnection必须用于提供该提示。
您还可以使用name属性@ServiceConnection以覆盖将使用的连接详细信息，例如在使用自定义图像时。
如果您使用的是 Docker 镜像registry.mycompany.com/mirror/myredis，你会使用@ServiceConnection(name="redis")确保RedisConnectionDetails被创建。
动态属性
服务连接的一个稍微冗长但更灵活的替代方案是@DynamicPropertySource.
静态@DynamicPropertySource方法允许向 Spring 环境添加动态属性值。
-
Java
-
Kotlin
import org.junit.jupiter.api.Test;
import org.testcontainers.containers.Neo4jContainer;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.DynamicPropertyRegistry;
import org.springframework.test.context.DynamicPropertySource;
@Testcontainers
@SpringBootTest
class MyIntegrationTests {
@Container
static Neo4jContainer<?> neo4j = new Neo4jContainer<>("neo4j:5");
@Test
void myTest() {
// ...
}
@DynamicPropertySource
static void neo4jProperties(DynamicPropertyRegistry registry) {
registry.add("spring.neo4j.uri", neo4j::getBoltUrl);
}
}import org.junit.jupiter.api.Test
import org.springframework.boot.test.context.SpringBootTest
import org.springframework.test.context.DynamicPropertyRegistry
import org.springframework.test.context.DynamicPropertySource
import org.testcontainers.containers.Neo4jContainer
import org.testcontainers.junit.jupiter.Container
import org.testcontainers.junit.jupiter.Testcontainers
@Testcontainers
@SpringBootTest
class MyIntegrationTests {
@Test
fun myTest() {
...
}
companion object {
@Container
@JvmStatic
val neo4j = Neo4jContainer("neo4j:5");
@DynamicPropertySource
@JvmStatic
fun neo4jProperties(registry: DynamicPropertyRegistry) {
registry.add("spring.neo4j.uri") { neo4j.boltUrl }
}
}
}上述配置允许应用程序中与 Neo4j 相关的 Bean 与在 Testcontainers 管理的 Docker 容器内运行的 Neo4j 进行通信。