1 / 4概念
Integration Testing
集成测试验证的是你的代码与真实依赖之间的接缝:SQL 方言、事务、序列化、协议、认证。它比单元测试慢,但能抓到单测永远抓不到的那类错误——替身和真实依赖行为不一致。
1 概念
1.1 一句话定义
集成测试在受控环境中使用真实或高保真的依赖(数据库、消息代理、HTTP 服务、文件系统),验证两个或多个组件组合后的行为。它不追求覆盖所有分支,而是验证边界契约和真实运行时语义。
1.2 它解决什么问题
- 单测里的内存仓储通过,真实 SQL 却因为约束、类型转换或隔离级别失败。
- JSON 序列化、时间格式、字符编码在真实协议下才暴露。
- 消费者和提供者对同一 API 的理解不一致,契约漂移。
- 事务、重试、连接池和迁移脚本在单元测试里根本没有执行。
集成测试把“接缝处”的风险提前到 CI,而不是留到联调或生产。
1.3 不属于本页的内容
| 主题 | 去哪 |
|---|---|
| 纯逻辑与用例的快速断言 | Unit Testing |
| 浏览器端用户旅程 | End-to-End Testing |
| 容量与尾延迟 | Performance Testing |
| 容器与镜像的构建细节 | Containers & Cloud Native |
| 数据库索引与执行计划 | Databases |
1.4 关键术语
| 术语 | 含义 | 容易混淆的点 |
|---|---|---|
| 接缝 | 两个组件之间的边界 | 不是代码里的任意一行 |
| 测试容器 | 用 Docker 启动的一次性依赖 | 不是共享的测试环境 |
| Fixture | 测试前置数据/环境 | 不是生产种子数据 |
| 契约测试 | 验证消费者与提供者的接口约定 | 不是端到端 |
| 消费者驱动契约 | 由消费者定义期望,提供者验证 | 不是 OpenAPI 文档 |
| 数据库隔离 | 每个测试独立的数据空间 | 不是“跑完再删库” |
| 幂等种子 | 重复执行不产生重复数据 | 不是随机插入 |
| 测试数据构建器 | 用代码构造合法数据 | 不是复制生产数据 |
2 机制
2.1 心智模型
集成测试像在实验室里接一段真实电路:只接通你要验证的那一段,其他部分用可控替身。每增加一个真实依赖,真实度上升、速度和稳定性下降;所以一次只验证一个接缝。
不变量:测试自己创建依赖、自己迁移 schema、自己清理数据,不依赖外部共享环境。 依赖外部环境的“集成测试”最终会变成不可重复的手工联调。
2.2 机制拆解
- 选择接缝:数据库、消息、HTTP、文件系统或认证。
- 启动依赖:Testcontainers/Docker、内存代理或契约 mock。
- 迁移 schema 到已知版本,加载最小 fixture。
- 执行被测代码,断言真实返回值/持久化结果/发出的消息。
- 验证边界行为:约束冲突、序列化、超时、重试。
- 销毁容器/清空数据,确保下一个测试从干净状态开始。
数据库隔离常用四种:事务回滚、truncate、每个测试独立 schema、每个套件独立容器。选择取决于迁移成本和并行度。
2.3 完整枚举
| 依赖类型 | 真实依赖 | 常用替身 | 验证重点 |
|---|---|---|---|
| 关系型数据库 | PostgreSQL/MySQL 容器 | 内存库(不推荐) | SQL、约束、事务、隔离级别 |
| NoSQL/缓存 | Redis/MongoDB 容器 | 内存 fake | 序列化、TTL、原子操作 |
| 消息代理 | Kafka/RabbitMQ 容器 | 内存队列 | 投递语义、顺序、重试 |
| HTTP 下游 | 真实测试服务 | WireMock/MSW | 状态码、超时、重试、错误体 |
| 文件/对象存储 | 本地临时目录/MinIO | 内存文件系统 | 路径、权限、分块 |
| 认证 | 测试 IdP/本地密钥 | 固定 token | 受众、过期、签名 |
| 隔离策略 | 速度 | 隔离度 | 适用 |
|---|---|---|---|
| 事务回滚 | 快 | 中 | 单连接、无 DDL |
| Truncate | 中 | 高 | 简单 schema |
| 每测试 schema | 中 | 高 | 并行、DDL |
| 每套件容器 | 慢 | 最高 | 迁移复杂、少量套件 |
2.4 关键数字与量级
| 指标 | 量级 | 说明 |
|---|---|---|
| 容器启动 | 1–10 秒 | 镜像预热后可更快 |
| 单集成测试 | 100 ms–2 s | 受迁移与网络影响 |
| 集成套件 | 分钟级 | 应少于 E2E |
| 连接池 | 5–20 | 按并发测试数配置 |
| Fixture 数据量 | 10–100 行 | 最小可用,避免大种子 |
| Flaky 率 | < 1% | 高于此值先查环境 |
3 实践
3.1 最小示例
// order-repository.integration.test.ts:真实 PostgreSQL,一次性容器。
import {afterAll, beforeAll, beforeEach, describe, expect, it} from 'vitest';
import {PostgreSqlContainer, type StartedPostgreSqlContainer} from '@testcontainers/postgresql';
import {Pool} from 'pg';
import {PostgresOrderRepository} from './postgres-order-repository';
let container: StartedPostgreSqlContainer;
let pool: Pool;
beforeAll(async () => {
container = await new PostgreSqlContainer('postgres:16-alpine').start();
pool = new Pool({connectionString: container.getConnectionUri()});
await pool.query(`
create table orders (
id text primary key,
status text not null check (status in ('open','paid')),
total_cents integer not null check (total_cents > 0)
)
`);
}, 30_000);
afterAll(async () => {
await pool.end();
await container.stop();
});
beforeEach(async () => {
await pool.query('truncate orders');
});
describe('PostgresOrderRepository', () => {
it('persists a paid order', async () => {
const repo = new OrderRowRepository(pool);
await repo.insert({id: 'order-1', status: 'paid', totalCents: 9900});
const row = await pool.query('select status, total_cents from orders where id = $1', ['order-1']);
expect(row.rows[0]).toEqual({status: 'paid', total_cents: 9900});
});
});
3.2 常用操作与参数
| 操作 | 命令 / API | 说明 |
|---|---|---|
| 起数据库容器 | new PostgreSqlContainer('postgres:16-alpine') | 固定镜像版本 |
| 起消息容器 | new KafkaContainer() | 启动较慢,按套件复用 |
| HTTP mock | WireMock/MSW | 模拟状态码、延迟、错误体 |
| 迁移 | migrate up 到固定版本 | 与生产同一套脚本 |
| 清理 | truncate / 事务回滚 | 保证测试独立 |
| 契约验证 | Pact/Spring Cloud Contract | 消费者与提供者双向验证 |
3.3 标准流程
- 列出接缝和它最容易出错的语义(约束、序列化、重试、超时)。
- 选择真实依赖或高保真替身;固定镜像/版本。
- 用与应用相同的迁移脚本建 schema。
- 每个测试构造最小 fixture,避免共享可变数据。
- 断言真实结果:数据库行、发出的消息、收到的 HTTP 请求。
- 在 CI 中缓存镜像、并行分片,控制总时长。
3.4 与相邻技术的组合
- 单元测试:单测覆盖逻辑分支,集成测试覆盖真实接缝。
- 契约测试:消费者驱动契约验证 API 形状,不需要启动完整下游。
- 端到端测试:集成测试验证组件,E2E 验证用户旅程。
- CI/容器:Testcontainers 依赖 Docker;CI runner 必须支持。
3.5 选型维度
| 维度 | 取值 | 影响 |
|---|---|---|
| 接缝风险 | 低 / 高 | 高风险用真实依赖 |
| 依赖启动成本 | 低 / 高 | 高则按套件复用或 mock |
| 契约稳定性 | 稳定 / 易变 | 易变用消费者驱动契约 |
| 并行需求 | 低 / 高 | 高则每测试独立 schema/容器 |
| CI 环境 | 支持 Docker / 不支持 | 不支持则用远程容器或 mock |
| 反馈速度 | 秒 / 分钟 | 控制在分钟级 |
3.6 决策规则
- 验证 SQL/事务/约束:真实数据库容器,不用内存库。
- 验证 HTTP 错误处理:WireMock/MSW,不启动真实下游。
- 验证服务间契约:消费者驱动契约,优先于完整 E2E。
- 依赖启动太慢:按套件复用容器,测试间清数据。
- CI 不支持 Docker:用托管测试依赖或契约 mock,并明确覆盖率缺口。
3.7 替代方案对比
| 方案 | 优势 | 代价 | 适用 |
|---|---|---|---|
| 真实容器 | 高保真 | 慢、依赖 Docker | 数据库/消息 |
| 内存替身 | 快 | 语义差异大 | 纯逻辑/早期 |
| API mock | 可控错误 | 契约可能漂移 | 下游不稳定 |
| 契约测试 | 轻量、双向 | 需要双方维护 | 服务间 API |
| 共享测试环境 | 真实 | 不可重复、数据污染 | 少量手工验证 |
3.8 何时不该用
- 纯函数/领域规则:单测足够,集成测试只会更慢。
- 第三方服务没有测试环境且无法 mock:先做契约隔离,不要直连生产。
- 依赖启动成本高于收益:用契约测试或 mock,明确不覆盖的部分。
- 团队没有 Docker/CI 支持:先补基础设施,否则测试不可重复。
4 边界
4.1 典型故障
| 症状 | 根因 | 处理 |
|---|---|---|
| 本地通过、CI 失败 | 镜像/端口/时区/架构不同 | 固定镜像与平台,CI 同构 |
| 测试互相污染 | 共享数据库、未清理 | 每测试清数据/独立 schema |
| 端口被占用 | 固定端口、容器未回收 | 随机端口,确保 stop |
| 迁移后测试挂起 | schema 版本不一致 | 固定迁移版本,启动即迁移 |
| 偶发超时 | 容器冷启动/网络慢 | 预热镜像、合理超时、重试 |
| 契约测试通过但线上失败 | 只测了 mock,没测真实协议 | 补一条真实集成路径 |
| 时间/时区断言失败 | 依赖本地时区 | 固定 UTC/注入 clock |
| 测试数据泄漏到其他环境 | 连到共享库 | 禁止非本地连接串 |
4.2 反模式
| 做法 | 后果 | 替代 |
|---|---|---|
| 用内存库代替真实 SQL | 方言/约束差异被掩盖 | 真实容器 |
| 共享一个测试数据库 | 数据污染、顺序依赖 | 每测试隔离 |
| 复制生产数据 | 隐私与体积问题 | 构造最小 fixture |
| 用 sleep 等容器 | 慢且不稳定 | 等待就绪探针/端口 |
| 只测 happy path | 错误处理未验证 | 加约束/超时/失败用例 |
4.3 可观测信号
容器启动时间、测试耗时分布、flaky 率、数据库连接数、迁移版本、失败时的容器日志。CI 中保留失败容器日志,不要只留测试堆栈。
4.4 安全 / 性能 / 一致性边界
- 安全:不要连生产/共享环境;测试数据不含真实个人信息。
- 隔离:测试之间不能共享可变状态;并行时尤其要独立 schema。
- 性能:集成测试控制在分钟级;慢用例拆到单独套件。
- 真实性:mock 只能验证你理解的契约,不能证明真实依赖的行为。