测试中隔离外部依赖时如何选择虚拟化策略并防止真实调用逃逸

为测试套件中的每个外部依赖选择正确的隔离策略（进程内 mock、HTTP stub、录制回放、故障注入、临时真实服务），并确保 CI 中没有任何真实调用逃逸。

适用场景

解决思路

1. 先检查 `.agents/qa-project-context.md` 是否存在：若存在则使用它、遵循已有 mocking 约定，并跳过其中已回答的问题。
2. 盘点系统调用的外部依赖，找出测试中最痛苦的（限流、慢、不稳定、付费）作为最高优先级虚拟化对象，列出支付、邮件、认证和第三方数据源。
3. 按测试层级确定隔离策略：单元测试用快速的进程内 mock，集成测试用 HTTP 层 stub，E2E 用真实或容器化服务。
4. 优先使用提供方官方的测试模式或沙箱（如 Stripe test mode、Twilio test creds），其保真度高于自建 stub。
5. 检查是否与依赖方有契约：有则用契约测试保持 stub 同步；没有则明确「mock 你不拥有的东西」是已知风险。
6. 确认 CI 是否有 Docker：无 Docker 则选 MSW（进程内）；有 Docker 则可选 WireMock、Testcontainers、Toxiproxy。
7. 按所需置信度匹配隔离层级：单元测试可激进 mock，集成测试用真实 stub 或真实服务，E2E 用最接近生产但仍可靠的环境。
8. 当真实服务快速、免费且可靠时优先用真实服务（如本地 PostgreSQL 容器），仅对慢、不可靠或付费的依赖使用 fake。
9. 绝不 mock 你不拥有且无契约的东西：优先级为「提供方官方测试模式/沙箱 → 由契约测试验证漂移的 HTTP stub → 裸 stub（仅当无更好选择）」。
10. 让 stub 真实地失败：每个 stub 都要有错误变体，包括 429 限流、500、超时、畸形响应体。
11. 在测试与工具之间加一层抽象：把 MSW handlers、WireMock stubs、Testcontainers 设置封装在统一接口后，便于切换工具而不重写测试。
12. 按决策树选择：内部依赖→进程内 mock；数据库/缓存/消息队列→Testcontainers；第三方 HTTP API→有沙箱则 staging 用沙箱、CI 用 MSW/WireMock，无沙箱则 MSW/WireMock + 契约测试检测漂移；内部微服务→契约测试（Pact）+ 消费者测试用 stub。
13. 默认选 MSW 用于进程内 Node/浏览器测试；跨语言 CI 或独立 stub 服务器选 WireMock；OpenAPI 规范即契约时选 Prism；开发期探索性 mock 选 Mockoon。
14. 使用 MSW 2.x 在网络层拦截 HTTP（浏览器用 Service Worker，Node 用请求拦截），在 HTTP 层 stub（如 `POST /v1/payment_intents`），绝不在 SDK 方法层 stub。
15. 在 CI 中把 `setupServer(...).listen({ onUnhandledRequest })` 设为 `"error"`，使任何逃逸的真实调用导致运行失败；本地迭代时用 `"warn"`。
16. 使用 WireMock 3.13.2（4.0 截至 2026 年中仍为 beta，CI 留在 3.x），可独立运行或作为 Docker 容器，适合多语言环境或复杂匹配规则。
17. 用基于优先级的映射处理错误场景：`priority: 1` 的映射匹配 opt-in 头（如 `X-Test-Scenario: rate-limit`）并返回 429，仅在测试要求时遮蔽默认 happy-path 映射。
18. 用 WireMock 管理 API 以编程方式创建 stub（`POST /__admin/mappings`）、验证（`POST /__admin/requests/count`）和重置（`POST /__admin/mappings/reset`）。
19. 用 Testcontainers 在 Docker 中启动真实服务做集成测试：套件前启动、套件后销毁；使用 `@testcontainers/postgresql` 11.x 等；端口是随机的，始终通过 `getMappedPort()` / `getConnectionUri()` 读取，绝不硬编码 5432/6379。
20. 用 Toxiproxy（`ghcr.io/shopify/toxiproxy:2.12.0`）作为 TCP 代理注入延迟、带宽限制和连接重置；让应用指向代理端口而非真实服务；在 `afterEach` 中始终移除 toxics，否则会跨测试泄漏。
21. 用录制回放库（Hoverfly、Polly.JS 或 VCR 风格 cassette）实现录制回放，不要手写录制器；它适合从真实 API 引导 stub 和多步交互的回归基线。
22. 录制回放要打上 `recordedAt` 时间戳，并在录制超过 30 天时让测试失败，强制重新录制。
23. CI 集成：MSW 无需基础设施，CI 与本地一致，唯一规则是 CI 中设 `onUnhandledRequest: "error"`；WireMock 和 Testcontainers 需要 Docker。
24. 不要在同一套件中混用两种不兼容的端口模型：docker-compose 模型发布固定端口（可硬编码 `DATABASE_URL=...localhost:5432...`），Testcontainers 模型用随机端口并通过 `getMappedPort()` 注入 `process.env`；每套件选一种。
25. 避免反模式：不要 mock 一切；不要在各测试间使用不一致的 mock 行为（集中 handlers 并复用同一响应形状）；API 变化时更新 stub；不要在错误的层 stub；不要缺少错误场景覆盖；不要共享长生命周期的 mock 服务器（每次测试运行启动自己隔离的 stub 服务器）；录制回放必须有过期检查。
26. 验证无真实调用逃逸，从最小检查开始：`CI=1 npm run test:integration`（`onUnhandledRequest:"error"` 下 exit 0 表示无逃逸）；`docker compose -f docker-compose.test.yml up -d --wait --wait-timeout 120 && echo OK` 后 `docker compose -f docker-compose.test.yml down -v`；`grep -iE "api\.stripe\.com|api\.twilio\.com" ci-run.log && echo "LEAK" || echo "clean"`。
27. 完成标准：为每个外部依赖决定并记录隔离策略；stub 覆盖所有关键外部依赖且每个至少有一条错误路径（4xx/5xx、超时或限流）；stub 和映射文件与测试代码同仓库版本化；套件在 CI 中以 `onUnhandledRequest: "error"`（或 WireMock 等价物）通过，且 grep CI 日志中真实提供方主机无输出；任何录制回放基线带 `recordedAt` 时间戳和 30 天过期检查。

适用边界 · 注意事项

• 不要用于消费者驱动的契约验证（Pact、broker）——应使用 contract-testing。
• 不要用于搭建完整 Docker Compose 环境或种子数据——应使用 test-environments。
• 不要用于广泛的韧性/游戏日故障演练——应使用 chaos-engineering。