---
name: testcontainers-integration-testing
description: >
  提供基于 Testcontainers 的 Java 集成测试工作流，用于数据库、中间件和外部依赖的接近真实行为验证。
  当任务涉及持久化、消息、缓存、对象存储或多依赖编排时使用。
---

# Testcontainers Integration Testing

## 用途

- 把“依赖共享测试环境”收敛成“本地或 CI 可重复启动的临时依赖环境”。
- 适合数据库、Redis、MQ、对象存储、搜索引擎或浏览器依赖的集成验证。

## 默认做法

1. 先明确要验证的真实依赖和关键行为，不要把所有外部系统都塞进同一个大而慢的集成测试。
2. 优先为高风险链路建立容器化验证，例如 repository 查询语义、事务回滚、消息收发、缓存一致性、数据库迁移和真实协议交互。
3. 容器镜像、端口、等待条件和初始化数据都要显式写进测试，不依赖共享环境中的隐式前置状态。
4. 让测试自己启动依赖、执行验证、清理资源；不要要求执行者手工先起一套本地服务再跑测试。
5. 只把 Testcontainers 用在“接近真实行为才有价值”的场景；纯逻辑和普通 service 分支仍优先走单元测试。

## 触发信号

- 改动涉及数据库、缓存、消息、搜索或对象存储等真实依赖。
- 单元测试通过了，但仍无法证明事务、SQL、序列化、连接配置或依赖编排是对的。
- 当前验证严重依赖共享环境、手工准备测试数据或“本地我起过服务所以能跑”。
- 团队需要在 CI 中稳定重放一次接近真实依赖的关键链路。

## 配套约束

1. 先遵循 [rules/java/testing.md](../../../rules/java/testing.md) 的 Java 测试重点，再决定是否需要引入容器化验证。
2. 对纯逻辑、参数分支和普通 service 规则，优先继续使用 [java-unit-test](../java-unit-test/SKILL.md)。
3. 需要把编译、单测、启动和静态分析收口时，配合 [maven-qa](../maven-qa/SKILL.md) 一起使用。
4. 若测试依赖 Docker / Podman 等容器运行时，必须在输出中说明执行前提；环境缺失时不要伪造“测试已通过”。
5. Testcontainers 不能替代发布前环境验证；若变更仍有部署、网络或配置差异风险，继续回到 `/team-review` 与 `/team-release` 说明。