testcontainers

Testcontainers

当工作涉及用于集成测试的一次性 Docker 容器时，使用此技能：数据库、消息代理、云模拟器、Compose 堆栈、等待策略、Ryuk 清理，或 CI 容器运行时。

工作流

1. 修改代码前，先检查本地 Testcontainers 的使用情况：
   • 语言和软件包版本（testcontainers、@testcontainers/*、Java org.testcontainers:*、Python extras、Go modules/...）。
   • 容器运行时：Docker Desktop、Colima、Podman、OrbStack、Rancher、DinD，或 Testcontainers Cloud。
   • 测试运行器生命周期：Vitest/Jest 全局设置、JUnit @Container、pytest fixtures、Go CleanupContainer。
   • 使用现有模块还是手动编写通用容器；网络；Compose；复用标志。
2. 如果版本不明确、语言 API 有差异，或工作涉及 CI/运行时/Cloud，请查阅最新官方文档。从 source-map.md 开始。
3. 根据工作内容查阅相应参考文档：
   • Node/TypeScript 核心功能、等待、网络、模块、运行器：node-core.md。
   • Java、Python、Go 和其他语言：languages.md。
   • 跨语言模块目录：modules-catalog.md。
   • 环境变量、CI、运行时、Ryuk、复用、安全：ci-runtimes-ops.md。
4. 优先使用项目采用的语言和现有模块包。不要引入第二种语言绑定。
5. 在最小的有效边界（一个模块 + 客户端）验证，然后验证整个测试套件的生命周期。

核心判断

• 依赖项有对应模块时，优先使用官方模块，而不是 GenericContainer / DockerContainer。
• 始终解析运行时主机 + 映射端口（getHost() / getMappedPort() / 语言中的等效方法）。切勿硬编码 localhost:5432 或固定主机端口。
• 固定镜像标签（postgres:16.3、redis:7.4）。避免在 CI 中使用浮动的 latest。
• 优先选择复制到容器中，而非绑定挂载（绑定挂载在 DinD/远程 Docker 环境下会失效）。
• 多容器 DNS 使用网络 + 别名。避免使用固定容器名称和主机名。
• 有意选择等待策略：监听端口（默认）、日志消息、HTTP、健康检查或组合策略。在 Colima/Rancher 上，将日志/健康检查等待与监听端口等待配合使用。
• 在 CI 中保持启用 Ryuk，除非环境不支持；若将其禁用，请确保采用其他清理方式。
• 仅在本地开发者机器上启用复用（withReuse / TESTCONTAINERS_REUSE_ENABLE）。不要在 CI 中依赖复用。
• 将 Testcontainers 用于集成/契约边界。纯单元测试应避免使用 Docker。
• 使模块主版本与核心包匹配（Node 12.x 模块搭配 testcontainers@12，后者需要 Node >=22.22；Java 2.x 使用 testcontainers-* 依赖项 + BOM）。
• 仅使用临时凭据。切勿将生产密钥放入容器环境变量中。

语言默认配置

语言	核心包	优先选择
Node/TS	testcontainers + @testcontainers/<svc>	模块 + await using / 可靠的资源清理
Java	org.testcontainers:testcontainers + BOM 2.x	模块 + try-with-resources 或 JUnit @Container
Python	testcontainers[extras]	模块 + 上下文管理器 / fixtures
Go	testcontainers-go + modules/<svc>	testcontainers.Run + CleanupContainer(t, …)

验证

优先使用仓库提供的命令。对于有实质意义的 Testcontainers 工作，覆盖相关子集：

• 在诊断测试失败前，确认 Docker（或 Cloud Agent）可访问。
• 针对性集成测试：启动模块 → 使用真实客户端连接 → 断言一项行为 → 停止并清理。
• 如果更改了相关 API，则进行多容器 / 网络 / Compose 冒烟测试。
• 等待策略的失败模式：断言超时错误有用，而不是让测试套件一直挂起。
• 如果更改了环境变量、Ryuk、DinD、套接字挂载或 Cloud 设置，则执行符合 CI 场景的运行。
• 并行性检查：使用随机端口，并且不共享可变容器状态，除非按设计由套件范围内共享。
• Postgres 模块的快照 / 恢复检查（快照请勿使用数据库名 postgres）。

报告已运行和未运行的检查，以及仍存在的任何运行时或软件包版本假设。