Testcontainers 系列专题：第 3 篇进阶用法

Testcontainers 系列专题 - 第 3 篇：进阶用法 - 自定义容器与网络

引言

在前两篇中，我们掌握了 Testcontainers 的基本用法和核心功能，能够轻松启动数据库容器并集成到测试框架中。然而，在真实项目中，我们可能需要使用自定义镜像，或者让多个容器协同工作来模拟复杂的系统。本篇将深入探讨这些进阶主题，帮助你解锁 Testcontainers 的更多潜力。

自定义容器

Testcontainers 的内置容器（如 PostgreSQLContainer、MySQLContainer）已经覆盖了许多常见场景，但有时你需要运行特定的镜像或自定义配置。这时，可以使用 GenericContainer 或从 Dockerfile 构建容器。

从远程镜像启动自定义容器

假设你需要测试一个运行在 Nginx 上的静态网站，可以直接使用 GenericContainer：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
import org.junit.jupiter.api.Test;
import org.testcontainers.containers.GenericContainer;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;
import org.testcontainers.utility.MountableFile;

import java.net.HttpURLConnection;
import java.net.URL;

import static org.junit.jupiter.api.Assertions.assertEquals;

@Testcontainers
public class CustomNginxTest {

    @Container
    public GenericContainer<?> nginx = new GenericContainer<>("nginx:latest")
            .withExposedPorts(80)
            .withCopyFileToContainer(
                    MountableFile.forClasspathResource("index.html"),
                    "/usr/share/nginx/html/index.html"
            );

    @Test
    public void testNginxServesCustomPage() throws Exception {
        String url = "http://" + nginx.getHost() + ":" + nginx.getMappedPort(80);
        HttpURLConnection connection = (HttpURLConnection) new URL(url).openConnection();
        connection.setRequestMethod("GET");
        int responseCode = connection.getResponseCode();
        assertEquals(200, responseCode); // 验证 Nginx 返回 200 OK
    }
}

代码说明：
- withExposedPorts(80)：映射 Nginx 的默认端口。
- withCopyFileToContainer：将本地的 index.html 复制到容器中，替换默认页面。
- 测试通过 HTTP 请求验证 Nginx 是否正常提供服务。

从 Dockerfile 构建容器

如果需要更复杂的自定义逻辑，可以基于 Dockerfile 创建容器：

创建一个 Dockerfile（例如放在项目根目录下的 docker/ 文件夹）：
```
FROM nginx:latest
COPY custom.conf /etc/nginx/conf.d/default.conf
```

创建 custom.conf（放在同一目录）：

server {
    listen 80;
    server_name localhost;
    location / {
        root /usr/share/nginx/html;
        index custom.html;
    }
}

测试代码：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
import org.junit.jupiter.api.Test;
import org.testcontainers.containers.GenericContainer;
import org.testcontainers.images.builder.ImageFromDockerfile;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;

import java.net.HttpURLConnection;
import java.net.URL;

import static org.junit.jupiter.api.Assertions.assertEquals;

@Testcontainers
public class DockerfileNginxTest {

    @Container
    public GenericContainer<?> nginx = new GenericContainer<>(
            new ImageFromDockerfile("custom-nginx")
                    .withFileFromPath(".", Path.of("docker"))
                    .withFileFromClasspath("custom.html", "custom.html")
    ).withExposedPorts(80);

    @Test
    public void testCustomNginx() throws Exception {
        String url = "http://" + nginx.getHost() + ":" + nginx.getMappedPort(80);
        HttpURLConnection connection = (HttpURLConnection) new URL(url).openConnection();
        connection.setRequestMethod("GET");
        assertEquals(200, connection.getResponseCode());
    }
}

代码说明：
- ImageFromDockerfile：从指定路径的 Dockerfile 构建镜像。
- withFileFromPath：将 docker/ 目录下的文件纳入构建上下文。
- withFileFromClasspath：将 custom.html 添加到镜像中。

容器网络

在微服务架构中，多个服务需要通过网络通信。Testcontainers 支持创建自定义网络，让容器之间可以相互访问。

示例：API 服务与 Redis

假设你有一个简单的 API 服务依赖 Redis，我们可以使用 Testcontainers 模拟这种依赖关系：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
import org.junit.jupiter.api.Test;
import org.testcontainers.containers.GenericContainer;
import org.testcontainers.containers.Network;
import org.testcontainers.containers.wait.strategy.Wait;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;

import java.net.HttpURLConnection;
import java.net.URL;

import static org.junit.jupiter.api.Assertions.assertEquals;

@Testcontainers
public class ApiRedisTest {

    private static final Network network = Network.newNetwork();

    @Container
    public GenericContainer<?> redis = new GenericContainer<>("redis:6.2")
            .withNetwork(network)
            .withNetworkAliases("redis") // 网络别名
            .withExposedPorts(6379);

    @Container
    public GenericContainer<?> api = new GenericContainer<>("my-api:latest")
            .withNetwork(network)
            .withEnv("REDIS_HOST", "redis") // 使用别名连接 Redis
            .withEnv("REDIS_PORT", "6379")
            .withExposedPorts(8080)
            .waitingFor(Wait.forHttp("/health")); // 等待 API 就绪

    @Test
    public void testApiWithRedis() throws Exception {
        String url = "http://" + api.getHost() + ":" + api.getMappedPort(8080) + "/data";
        HttpURLConnection connection = (HttpURLConnection) new URL(url).openConnection();
        connection.setRequestMethod("GET");
        assertEquals(200, connection.getResponseCode());
    }
}

代码说明：
- Network.newNetwork()：创建一个自定义网络。
- withNetwork(network)：将容器加入同一网络。
- withNetworkAliases：为 Redis 设置网络别名，API 容器可以通过 redis 访问它。
- withEnv：配置 API 容器连接 Redis。

注意：这里假设 my-api:latest 是一个预构建的镜像，实际中需要替换为你的应用镜像。

等待策略

容器启动后可能需要时间初始化（如数据库创建表、API 服务监听端口）。Testcontainers 提供了等待策略，确保容器就绪后再运行测试。

内置等待策略

端口就绪：Wait.forListeningPort()（默认策略）。
HTTP 就绪：Wait.forHttp("/health")。
日志匹配：Wait.forLogMessage(".*Started.*", 1)。

示例：等待 MySQL 初始化

1
2
3
4
5
6
@Container
public MySQLContainer<?> mysql = new MySQLContainer<>("mysql:8.0")
        .withDatabaseName("testdb")
        .withUsername("user")
        .withPassword("password")
        .waitingFor(Wait.forLogMessage(".*ready for connections.*", 1));

自定义等待策略

如果内置策略不够，可以实现自定义逻辑：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
import org.testcontainers.containers.wait.strategy.AbstractWaitStrategy;

public class CustomWaitStrategy extends AbstractWaitStrategy {
    @Override
    protected void waitUntilReady() {
        // 自定义检查逻辑，例如通过 API 调用确认服务就绪
        while (!isServiceReady()) {
            try {
                Thread.sleep(100);
            } catch (InterruptedException e) {
                Thread.currentThread().interrupt();
            }
        }
    }

    private boolean isServiceReady() {
        // 示例：检查特定条件
        return true;
    }
}

// 使用
@Container
public GenericContainer<?> container = new GenericContainer<>("my-app:latest")
        .withExposedPorts(8080)
        .waitingFor(new CustomWaitStrategy());

总结

本篇介绍了 Testcontainers 的进阶用法，包括自定义容器的创建、多容器网络的配置以及等待策略的运用。这些功能让你可以模拟复杂的系统架构，并在测试中获得更高的灵活性和可靠性。下一篇文章将探讨如何将 Testcontainers 集成到 CI/CD 流程中。

Testcontainers 系列专题：第 3 篇 进阶用法

相关文章：

Testcontainers 系列专题：第 3 篇进阶用法