backend-testing

后端测试

将此技能用作数据包优先的后端测试路由器。

目标不是为每种框架倾倒样板代码，而是：

1. 将请求归类到正确的后端测试数据包，
2. 选择规模最小且足以令人信服的测试层组合，
3. 明确说明依赖真实性和数据控制，
4. 如实区分本地、PR 和较慢的测试通道，
5. 如果实际任务是策略、契约结构或身份验证实现，则将请求转至其他技能。

需要时阅读：

• references/intake-packets-and-route-outs.md
• references/test-layer-matrix.md
• references/stability-checklist.md

适用场景

• 为 API、服务、存储库、工作器、集成或身份验证流程添加或修复后端测试覆盖
• 判断后端变更需要单元、集成、契约/API 还是精简冒烟测试
• 设计测试夹具、工厂、数据播种/重置、身份验证引导或环境控制策略
• 决定使用模拟对象、伪对象、容器还是真实依赖
• 稳定不稳定的后端测试套件，尤其是仅在 CI 中失败以及本地与 CI 结果不一致的情况
• 检查后端测试套件是否范围过广、速度过慢、过度依赖模拟，或缺少关键测试层

不适用场景

• 主要任务是组织范围的测试策略、门禁设计、发布证据或公司级 QA 理念 → 使用 testing-strategies
• 主要任务是在能够合理规划测试之前确定 API 契约结构、版本控制或架构设计 → 使用 api-design
• 主要任务是实现身份验证/会话/提供方行为，而不是测试这些行为 → 使用 authentication-setup
• 主要任务是前端/浏览器测试或 UI 工作流覆盖
• 尚无具体的后端行为或回归目标；此时应先定义缺失的行为数据包，而不是假装测试计划已经确定

指南

第 1 步：将请求归入一个数据包

给出建议前，先选择最合适的单一入口数据包。

数据包

• coverage-plan — 为具体的后端变更确定要添加哪些测试层
• fixture-and-reset-plan — 确定如何播种、隔离、重置或引导数据/身份验证状态
• contract-and-api-checks — 在接口已存在的前提下，保护响应/事件/架构兼容性
• flake-stabilization — 稳定仅在 CI 中出现或偶发的后端故障
• execution-lane-split — 划分本地快速、PR、夜间和仅发布时运行的后端检查

如果请求包含多个方面，指出主要数据包和一个次要关注点。

第 2 步：确定后端范围和风险

收集最少但有用的上下文：

• 范围：端点、服务、存储库、工作器、队列使用者、身份验证流程、集成或迁移
• 风险最高的行为：验证、权限、持久化、重试、幂等性、顺序、序列化、副作用、兼容性
• 已有的测试覆盖
• 涉及的外部依赖：数据库、缓存、队列、电子邮件、支付、第三方 API、身份提供方、文件系统
• 运行时/语言技术栈
• 证据必须成立的环境：本地开发循环、PR CI、定期 CI、发布冒烟测试

如果请求较为模糊，先选择值得保护的最小回归范围。

第 3 步：选择合适的测试层

根据数据包和风险，选择最精简且足以令人信服的测试层组合。

单元/服务

主要风险在于分支逻辑、验证、编排或近乎纯粹的业务规则时优先选择。

集成

数据库行为、框架接线、中间件、事务、队列、缓存或序列化很重要时优先选择。

契约/API

客户端依赖响应结构、状态码、架构或事件，且接口已存在时优先选择。

冒烟/选择性端到端

仅当范围精简且对发布至关重要的用户旅程跨越多个后端边界，并且较低层测试会遗漏核心风险时才优先选择。

说明范围内和范围外的内容，并解释原因。

第 4 步：有意识地决定依赖的真实性

对于每项依赖，选择以下一种：

• mock / stub — 成本高、不稳定，或与被测行为无关
• fake / simulator — 行为很重要，但轻量级替代方案就足够
• containerized real dependency — 查询、迁移、消息语义或线路行为足够重要，出现偏差会造成问题
• shared external environment — 仅在无法避免时使用；明确说明其脆弱性代价

良好默认做法：

• 如果仓储、迁移、事务或序列化行为是核心，优先使用真实 DB 行为
• 除非正在测试集成契约本身，否则优先 mock 出站第三方 API
• 优先选择范围精简的容器化切片，而不是庞大的全依赖 PR 测试环境
• 如果生产环境一致性是主要风险，不要声称 fake 和真实依赖等效

第 5 步：定义 fixture、数据、认证和环境控制

状态含糊不清时，后端测试套件就不值得信赖。

请说明：

• fixture/factory 策略
• seed/reset/rollback 方案
• 面向用户、角色、租户、令牌或会话的认证/引导辅助工具
• 必要时对时间/随机性/幂等性的控制
• 隔离规则：每项测试、每个文件、每个测试套件，还是每个环境
• 发生失败时要收集的调试信号

如果测试套件依赖执行顺序、残留数据或 sleep，必须直接指出这种脆弱性。

第 6 步：拆分执行通道

将本地、PR 和较慢的测试通道视为不同任务。

请定义：

• local-fast path — 开发者应反复运行的内容
• PR path — 合并前必须通过的内容
• scheduled / nightly path — 更广的覆盖范围或成本较高的真实性测试
• release / incident path — 必要时用于验证信心或防止回归的精简检查

如果测试套件很慢，就拆分它。不要假装一个庞大且权威的测试流程能在所有场景中切实可行。

第 7 步：生成一份后端测试方案包

返回一份简洁的方案包，而不是泛泛而谈。

建议的方案包形式：

• coverage-plan → 覆盖表 + 依赖策略 + 排除项
• fixture-and-reset-plan → fixture/reset 说明 + 认证/引导注意事项
• contract-and-api-checks → 兼容性方案包 + 消费方/提供方范围 + 转交事项
• flake-stabilization → 不稳定测试说明，列出可能原因、隔离修复、就绪检查和调试信号
• execution-lane-split → 通道矩阵，说明本地/PR/定时/发布流程的职责

方案包至少包含：

• 变更范围和主要风险
• 选定的方案包及任何次要关注点
• 选择的测试层及其原因
• 依赖真实性决策
• fixture/数据/认证/环境控制
• 执行通道拆分
• 请求中部分内容由其他领域负责时的明确转交事项

第 8 步：定稿前确认范围边界

检查：

• 方案包是否保护真正的后端回归风险，而非追求泛泛的覆盖率？
• 是否将组织范围的验证策略留在 testing-strategies 中？
• 是否将契约的 形式 决策转交给 api-design，仅在接口已存在时才在此处负责契约的 保护？
• 是否将认证实现工作转交给 authentication-setup？
• 维护者能否理解依赖为何被 mock、fake、容器化或直接使用真实依赖？

输出格式

## Backend Test Packet: [Surface or Change]

### Packet choice
- Primary packet: coverage-plan | fixture-and-reset-plan | contract-and-api-checks | flake-stabilization | execution-lane-split
- Secondary concern: optional
- Confidence: high | medium | low

### Change framing
- Surface: ...
- Main risks: ...
- Runtime: ...
- Existing coverage: ...

### Layer decisions
| Layer | In scope? | What it protects | Notes |
|------|-----------|------------------|-------|
| Unit / service | yes/no | ... | ... |
| Integration | yes/no | ... | ... |
| Contract / API | yes/no | ... | ... |
| Smoke / selective E2E | yes/no | ... | ... |

### Dependency realism
| Dependency | Strategy | Why |
|------------|----------|-----|
| Database / queue / cache | ... | ... |
| External API | ... | ... |
| Auth provider | ... | ... |

### Data and environment control
- Fixtures / factories: ...
- Seed / reset: ...
- Auth bootstrap: ...
- Isolation rule: ...
- Debug signals: ...

### Execution lanes
- Local-fast: ...
- PR CI: ...
- Scheduled / nightly: ...
- Release / incident: ...

### Route-outs
- `testing-strategies`: ...
- `api-design`: ...
- `authentication-setup`: ...

示例

示例 1：认证密集型 API 变更

输入：“我们为 Express API 添加了刷新令牌轮换和新的管理员专属端点。我需要后端测试来发现认证失败、令牌重放问题和 DB 持久化错误，同时又不让 CI 变成庞大的端到端测试套件。”

良好的响应形式：

• 选择 coverage-plan 作为主要方案包
• 结合单元/服务层与集成/API 覆盖，而不是采用一个庞大的 E2E 测试套件
• 在令牌/会话行为至关重要时，使用真实 DB 或容器化持久化
• 定义认证引导辅助工具和重置策略
• 将冒烟测试限制在精简的发布关键路径上

示例 2：服务套件中仅在 CI 中出现的间歇性故障

输入：“我们的 FastAPI 测试在本地通过，但在 CI 中会因预置的 Postgres 状态和后台任务而失败。请给出一份稳定化计划。”

良好响应形式：

• 选择 flake-stabilization 作为主要方案包
• 指出种子数据／重置漂移、就绪状态、异步时序或残留状态可能是原因
• 建议加强隔离、添加就绪检查和调试信号，而不只是重试
• 明确区分本地快速运行和 CI 权威验证的行为

示例 3：API 已存在后的契约保护

输入：“我们的支付服务和 webhook 消费者在响应字段上总是出现偏差。我不需要重新设计 API，而是需要能捕获兼容性回归的后端测试。”

良好响应形式：

• 选择 contract-and-api-checks 作为主要方案包
• 由于接口已存在，因此在此处进行契约保护
• 将任何架构重新设计或版本控制讨论转交给 api-design
• 建议覆盖消费者／提供者或架构兼容性，而不是泛化地增加冒烟测试

示例 4：范围过广的策略请求

输入：“为我们的前端、后端、移动端和 QA 设计整体工程组织测试策略。”

良好响应形式：

• 识别出主要任务应归入 testing-strategies
• 将任何后端专属建议仅作为交接事项，并限定范围
• 拒绝将 backend-testing 扩展为通用 QA 治理技能

最佳实践

1. 从方案包入手，而不是从框架入手。
2. 在追求覆盖率百分比之前，先保护真正的后端回归风险。
3. 优先采用分层后端覆盖，而不是庞大且脆弱的端到端测试套件。
4. 明确夹具、种子数据和身份验证引导策略；隐藏状态会摧毁信任。
5. 有意拆分本地快速运行、PR、定期运行和发布流程。
6. 在线路行为至关重要时使用真实依赖，但要控制高成本的真实环境测试范围。
7. 将不稳定测试视为信任问题，而不只是麻烦。
8. 将策略、契约形态和身份验证实现的所有权转交出去，而不是自行承担。

参考资料

• 实用测试金字塔
• pytest：良好的集成实践
• Testcontainers
• Pact 文档
• GitHub Actions：构建和测试 Python