docker-testcontainers

Docker Testcontainers — 集成测试容器

Guidance for running Docker containers in automated tests with Testcontainers.

When to Use

ALWAYS use this skill when the user mentions:

• "testcontainers", "Testcontainer", "测试容器"
• "集成测试", "docker 测试"
• "数据库测试", "PostgreSQL test", "MySQL test"
• "Java Testcontainers", "Python Testcontainers"
• "测试环境搭建"

Java — Testcontainers

PostgreSQL Example

@Testcontainers
@SpringBootTest
class OrderRepositoryTest {

    @Container
    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16-alpine")
            .withDatabaseName("testdb")
            .withUsername("test")
            .withPassword("test");

    @DynamicPropertySource
    static void configure(DynamicPropertyRegistry registry) {
        registry.add("spring.datasource.url", postgres::getJdbcUrl);
        registry.add("spring.datasource.username", postgres::getUsername);
        registry.add("spring.datasource.password", postgres::getPassword);
    }

    @Test
    void shouldSaveAndFindOrder() {
        Order saved = repository.save(new Order(...));
        assertThat(repository.findById(saved.getId())).isPresent();
    }
}

Redis Example

@Container
static GenericContainer<?> redis = new GenericContainer<>("redis:7-alpine")
        .withExposedPorts(6379);

// Get connection string
String redisUrl = "redis://" + redis.getHost() + ":" + redis.getMappedPort(6379);

Kafka Example

@Container
static KafkaContainer kafka = new KafkaContainer(
        DockerImageName.parse("confluentinc/cp-kafka:7.6.0"));

String bootstrapServers = kafka.getBootstrapServers();

Python — testcontainers-python

import pytest
from testcontainers.postgres import PostgresContainer
from testcontainers.redis import RedisContainer

@pytest.fixture(scope="module")
def postgres():
    with PostgresContainer("postgres:16-alpine") as pg:
        yield pg.get_connection_url()

def test_database_connection(postgres):
    import psycopg2
    conn = psycopg2.connect(postgres)
    assert conn.status == psycopg2.STATUS_READY

Container Lifecycle

// Singleton: one container for all tests
@Container
static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16");

// Per-test: new container for each test
@Test
void test() {
    try (var redis = new GenericContainer<>("redis:7")) {
        redis.start();
        // test...
    } // auto-closed by try-with-resources
}

CI/CD Configuration

# GitHub Actions — DinD (Docker-in-Docker)
jobs:
  test:
    runs-on: ubuntu-latest
    services:
      docker:
        image: docker:27-dind
        options: --privileged
    steps:
      - uses: actions/checkout@v4
      - run: ./gradlew test

Workflow — 推荐集成流程

Step 1: 添加依赖: testImplementation 'org.testcontainers:testcontainers:1.20.6' Step 2: 定义容器: @Container static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16-alpine") Step 3: 注入配置: @DynamicPropertySource 将容器连接信息注入 Spring 配置 Step 4: 编写测试: @Test void shouldSaveAndFind() 正常业务测试 Step 5: CI 加速: 启用 withReuse(true) + GHA cache

Gotchas — Common Pitfalls

• CI slow startup: Container images need to be pulled in CI. → Recovery: Pre-warm by adding docker pull postgres:16-alpine before test step; enable withReuse(true) in .testcontainers.properties.
• Port conflicts in CI: Testcontainers picks random ports — no conflicts. But hardcoded ports in tests will fail. → Recovery: Always use container.getMappedPort(5432) instead of hardcoding port numbers.
• Resource cleanup: Ryuk auto-removes containers. In CI, ensure DinD or socket access. → Recovery: If TESTCONTAINERS_RYUK_DISABLED=true, add @AfterAll cleanup; check Docker socket is mounted in CI.
• Static vs instance containers: Static @Container fields share ONE container across the class. Instance fields create per-test containers. → Recovery: Use static for databases (shared state OK); use instance for isolation-critical tests; check @TestInstance(TestInstance.Lifecycle.PER_CLASS) for JUnit 5.

Boundary — 能力边界（适用与不适用场景）

分类	场景	说明
✅ 能做	Java/Python 集成测试	PostgreSQL/MySQL/Redis/Kafka 等容器化数据库测试
✅ 能做	Spring Boot 测试	@Testcontainers + @DynamicPropertySource 自动注入
✅ 能做	CI 集成	GitHub Actions/Jenkins 中自动启动/清理
⚠️ 需条件	跨 JVM 复用	需配置 testcontainers.reuse.enable=true
⚠️ 需条件	非 Java 语言测试	使用各语言对应 Testcontainers 库
❌ 超范围	手动测试/调试	使用 docker-run
❌ 超范围	生产数据库测试	连接生产实例而非容器
❌ 超范围	性能/压测	专用工具（JMeter/K6）

When NOT to Use This Skill

❌ Skip	✅ Use Instead
Manual testing	docker-run
Production database testing	docker-storage + real instance
Mock testing	Use Mockito/unittest.mock
Docker basics	docker-basics

Security & Stability

• Testcontainers use random ports — no port conflicts with running services.
• Containers are automatically cleaned up by Ryuk after test completion.
• Never use Testcontainers in production code — test scope only.
• Use withReuse(true) for local development to speed up tests (container survives between runs).

📚 官方文档参考

文档	地址
Testcontainers 概述	https://docs.docker.com/testcontainers/
Testcontainers for Java	https://java.testcontainers.org/
Testcontainers Cloud	https://testcontainers.com/cloud/
Spring Boot 集成	https://java.testcontainers.org/modules/spring-boot/
CI 配置	https://java.testcontainers.org/supported_docker_environment/continuous_integration/

🧭 Docker Skills Journey

📍 You are here: docker-testcontainers — 测试容器

← Prev: docker-troubleshooting — Problem debugging → Next: docker-ai-ml — AI/ML workloads

FAQ

Q1: 如何快速上手此技能？ A: 参考上方的快速开始章节，按步骤操作即可。

Q2: 遇到版本不兼容问题怎么办？ A: 检查依赖版本，使用 lock 文件锁定，参考常见陷阱章节。

Q3: 如何在生产环境使用？ A: 参考最佳实践章节，确保配置正确，做好监控和日志。

Q4: 性能如何优化？ A: 参考性能优化相关文档，使用缓存、索引等手段。

Q5: 如何贡献或反馈问题？ A: 在 GitHub 仓库提交 Issue 或 Pull Request。

Q6: 是否支持中文？ A: 支持中文文档和中文注释，详见国内适配章节。