Instruction file imported from jijingkun-commits/fastapi (
.cursor/rules/test_quality.mdc). Copyright stays with the author.
测试质量规则（唯一质量门禁）
适用范围：本仓库所有测试真理源文档、自动化测试脚本、测试报告、审查与验收流程。 目标：把“高质量测试”从经验要求变成硬门禁。 原则：测试的目标不是证明“代码能跑”，而是证明“关键风险被有效约束”。 方法论参考：
${CODEX_HOME:-$HOME/.codex}/engineering/guides/test-case-quality-guide.md
0. 与现有规则的分工（强制）
本规则只负责“测试质量标准”，不替代以下现有规则：
- 文档同步与双向追溯：由
doc_sync.mdc负责； - 测试执行、证据矩阵、测试报告：由
jjk-test负责； - 审查结论、风险分级、是否放行：由
jjk-review/jjk-verify负责； - 测试解释器、上下文校验、运行态校验：由
AGENTS.md负责。
分工边界：
- 本规则回答：什么是高质量测试、哪些测试必须补、哪些测试应阻断；
- 执行链回答：怎么跑、跑了什么、证据是什么；
- 文档真理源回答：系统应该测什么、风险覆盖到了哪里。
禁止把“执行过测试”误当成“测试质量达标”。
1. 核心目标（强制）
高质量测试必须同时满足以下 5 个目标：
- 风险可映射：每个关键测试都能映射到明确风险，而不是泛泛“补个测试”；
- 缺陷可检出：测试失败时，能识别真实业务问题，而不是只证明接口还活着；
- 断言有语义：断言业务契约、状态语义、失败语义，不只断言表面状态；
- 结构低脆弱：尽量减少对私有实现、临时文案、无关调用顺序的依赖；
- 资产可演化：新增测试必须能回填测试真理源，旧低价值测试必须可识别、可替换、可淘汰。
2. 风险驱动原则（强制）
新增/修改测试前，必须先识别本次变更命中的风险模型；禁止直接只按 Happy Path / Edge Case / Error Handling 生成测试。
至少从以下维度中选择适用项：
- 输入边界 / 等价类
- 状态迁移 / 状态收口
- 权限 / 角色 / 多租户隔离
- 幂等 / 重试 / 去重
- 部分失败 / 超时 / 中断 / 回滚 / 补偿
- 数据一致性 / 副作用 / 落库 / 事件
- 可观测性 / 错误契约 / reason_code / error_code
- 并发 / 顺序 / 竞争条件
- 外部依赖退化 / 降级 / fallback
- 历史缺陷复现 / review 风险复现
适配要求：
- 若命中工作流、路由、多智能体、handoff、coverage、queue、streaming，必须显式评估：
- 顺序一致性
- pending / blocked / success / failure 收口语义
- 多目标覆盖完整性
- 部分结果返回时的最终统一汇总语义
失败码：
TEST_RISK_MODEL_MISSINGTEST_HIGH_RISK_DIMENSION_UNCOVERED
3. 用例设计标准（强制）
3.1 每个关键变更至少补齐以下适用集合
每个 feature / bugfix / refactor，至少补齐以下适用项：
- 1 个主业务成功场景；
- 1 个关键失败场景；
- 1 个高风险边界场景；
- 1 个状态语义或副作用场景（若涉及状态、DB、缓存、事件、任务队列）；
- 1 个历史问题回归场景（若已有事故、缺陷、review 指出过类似风险）。
3.2 若变更涉及编排层或工作流层，必须额外补充
- 目标是否被完整消费；
- 中间 pending 是否被错误判成 success；
- 部分结果是否污染最终汇总；
- 无结构化结果时是否仍保持正确失败/待补齐语义；
- 外部工具噪声/错误是否被错误透传给下游或用户。
3.3 测试名要求（强制）
测试名必须同时说明：
- 输入条件或上下文；
- 预期行为；
- 失败语义或约束点。
允许：
test_build_delivery_artifacts_marks_data_query_pending_without_structured_result
不允许：
test_data_querytest_it_workstest_pending_case
失败码：
TEST_NAME_TOO_WEAKTEST_SCOPE_AMBIGUOUS
4. 断言设计标准（强制）
4.1 断言最低要求
每个关键测试至少要有两类断言：
- 主结果断言：业务输出是否符合契约；
- 失败语义断言：失败/缺失/pending/blocked 时系统语义是否正确。
若涉及持久化、副作用、事件、异步、状态机，还必须至少补一类：
- 副作用断言；
- 状态断言；
- 可观测性断言（日志、reason_code、error_code、metric、trace 语义）。
4.2 推荐断言优先级
从高到低：
- 业务契约断言
- 状态语义断言
- 副作用断言
- 可观测性断言
- 调用交互断言
说明：
- 调用交互断言只能做辅助，不能替代业务契约断言。
4.3 明确禁止的弱断言
命中以下任一情况，默认视为弱断言：
- 只断言
status_code == 200 - 只断言
result is not None - 只断言
len(result) > 0 - 只断言 mock 被调用几次
- 只断言某个 helper 返回值，而不验证业务结果
- 只依赖 snapshot，没有关键业务断言
失败码：
TEST_ASSERTION_WEAKTEST_BEHAVIOR_NOT_ASSERTED
5. 测试结构与可维护性标准（强制）
5.1 必须避免的结构问题
- 一个测试同时覆盖多个不相关行为；
- 失败后无法定位是哪个业务要求坏了；
- 大量复制 setup、夹具、输入构造；
- 强依赖私有函数、内部变量、临时日志文案；
- 测试对实现顺序过度敏感，轻微重构就大量炸。
5.2 推荐结构
- 一个测试聚焦一个行为；
- 输入构造尽量业务化，不用神秘常量堆砌；
- 断言按“主结果 -> 状态/副作用 -> 错误语义”顺序组织；
- 公共夹具可以抽，但禁止为躲避清晰表达而过度抽象。
失败码：
TEST_IMPL_COUPLEDTEST_SETUP_DUPLICATEDTEST_FAILURE_NOT_LOCALIZABLE
6. 坏测试反模式（强制阻断）
命中以下任一项，默认阻断：
- 只测实现，不测行为
- 例如只测私有 helper、内部字段、临时分支；
- 只测 mock，不测系统契约
- 例如只看 mock 调用顺序，不验证输出语义；
- 只做表面通路检查
- 例如只有 200、非空、长度大于 0；
- 把 snapshot 当主断言
- 例如没有任何关键字段/状态语义断言；
- 为了好写测试而绕开真实边界
- 例如跳过关键状态流、绕开真实副作用、绕开异常语义；
- 用一个大而全测试覆盖多个风险
- 失败后不知道哪个要求退化；
- 已知低价值测试长期保留且不治理
- 例如历史遗留 smoke 一直冒充关键回归。
失败码：
TEST_LOW_VALUE_CASE_DETECTEDTEST_SNAPSHOT_OVERUSETEST_REAL_BOUNDARY_SKIPPED
7. 测试真理源同步（强制）
新增/修改测试若改变覆盖范围，必须同步回填：
- 对应模块测试案例文档；
测试用例库.md；- 若为历史问题修复，补充“风险来源 / 缺陷来源 / 退化条件”；
- 若新增测试替代旧低价值测试，必须在真理源中记录替代关系。
禁止：
- 只加自动化脚本，不回填测试真理源；
- 只补测试报告，不更新模块测试案例；
- 只在 review / report 中口头说明，不更新真理源。
失败码：
TEST_DOC_SYNC_MISSINGTEST_CASE_SOURCE_NOT_UPDATED
8. 测试质量评分卡（供 review / verify 消费，强制）
jjk-review / jjk-verify 必须显式输出以下评分项：
| 维度 | 评分范围 | 判定要点 |
|---|---|---|
| 风险覆盖 | 0~2 | 是否覆盖关键风险而非只跑通路径 |
| 失败模式覆盖 | 0~2 | 是否覆盖最可能出错的真实失败模式 |
| 断言质量 | 0~2 | 是否断言业务契约与失败语义 |
| 脆弱性 | 0~2 | 是否过度依赖实现细节 |
| 可维护性 | 0~2 | 是否清晰、聚焦、可定位 |
放行规则：
- 总分
< 7：默认不放行； - 任一维度
0：直接阻断； - 命中坏测试反模式：直接阻断；
- 若风险等级为
P0/P1，且缺少失败模式覆盖：直接阻断。
失败码：
TEST_REVIEW_SCORE_TOO_LOWTEST_FAILURE_MODE_UNCOVERED
9. 高风险场景强制覆盖矩阵（强制）
以下场景必须强制覆盖，不得只用“已有 Happy Path”代替：
| 场景类型 | 必须覆盖项 |
|---|---|
| 多智能体编排 | 顺序、pending、部分失败、统一汇总 |
| Handoff / Router | target_agent 选择、task_description 保真、generic/specific 收敛 |
| 外部检索 / 第三方工具 | 无结果、错误文本、噪声清洗、不可直接透传 |
| 数据查询 / Data Agent | 澄清、空结果、结构化结果缺失、权限与错误契约 |
| 状态机 / 队列 | 状态迁移、恢复、重复触发、收口一致性 |
| SSE / 事件流 | 事件顺序、重复、done 收口、异常隔离 |
| DB / 副作用 | 持久化一致性、回滚、重复写、幂等性 |
10. 低价值测试治理（强制）
10.1 低价值测试识别标准
命中以下任一项，应标记为低价值测试：
- 与需求/设计/风险无映射；
- 与其他测试重复覆盖同一浅层路径；
- 主要验证框架行为而非业务行为；
- 历史上未能有效检出该模块真实问题；
- 一旦重构就脆断，但对业务风险无增益。
10.2 处理策略
- 能升级则升级；
- 不能升级则标记“待替换”；
- 已有更强替代项时，允许淘汰；
- 淘汰时必须在测试真理源记录替代关系。
禁止以“测试数量变少”为理由保留低价值测试。
11. Lean 与净增长例外（强制）
11.1 原则
生产代码继续遵守 lean / shrink-only； 但以下目录为覆盖关键风险可允许净增长：
tests/**app/tests/**docs/开发文档/测试管理/**
11.2 适用条件
只有在满足以下条件时，测试净增长被视为合理：
- 明确覆盖新增风险或历史缺陷；
- 补齐原有缺口而非堆砌重复场景；
- 已回填测试真理源；
- 未命中低价值测试反模式。
11.3 治理提示
若项目 Layer1 对“新增行数 > 删除行数”有硬门禁，则必须在更高优先级治理文件中显式声明本例外；否则本条仅作为质量规则建议，无法自动覆盖 Layer1。
12. 执行链接入要求（强制）
12.1 jjk-test 必须增加
- 风险建模步骤；
- 主失败模式覆盖检查；
- 断言强度检查；
- 坏测试反模式检查；
- 测试质量小结。
12.2 jjk-review 必须增加
- 测试质量评分卡；
- 低价值测试识别；
- 风险覆盖缺口判断；
- 是否允许放行结论。
12.3 jjk-verify 必须增加
- 审查结论是否已覆盖测试质量评分；
- 是否仍存在关键失败模式未覆盖；
- 是否存在“有证据但质量不达标”的情况。
13. 输出模板（推荐）
13.1 测试报告应补充
## Test Quality Review
- 风险模型：PASS / WARN / FAIL
- 主失败模式覆盖：PASS / WARN / FAIL
- 断言质量：PASS / WARN / FAIL
- 实现耦合风险：PASS / WARN / FAIL
- 低价值测试识别：PASS / WARN / FAIL
- 阻断项：...13.2 审查报告应补充
## 测试质量评分卡
- 风险覆盖：2/2
- 失败模式覆盖：2/2
- 断言质量：1/2
- 脆弱性：2/2
- 可维护性：1/2
结论：PASS / CONCERNS / BLOCK14. 失败码总表（强制）
TEST_RISK_MODEL_MISSINGTEST_HIGH_RISK_DIMENSION_UNCOVEREDTEST_NAME_TOO_WEAKTEST_SCOPE_AMBIGUOUSTEST_ASSERTION_WEAKTEST_BEHAVIOR_NOT_ASSERTEDTEST_IMPL_COUPLEDTEST_SETUP_DUPLICATEDTEST_FAILURE_NOT_LOCALIZABLETEST_LOW_VALUE_CASE_DETECTEDTEST_SNAPSHOT_OVERUSETEST_REAL_BOUNDARY_SKIPPEDTEST_DOC_SYNC_MISSINGTEST_CASE_SOURCE_NOT_UPDATEDTEST_REVIEW_SCORE_TOO_LOWTEST_FAILURE_MODE_UNCOVERED
15. 底线原则（强制）
- 测试的目标是暴露风险，不是证明流程完整；
- 证据完整不能替代质量达标；
- 测试数量不能替代测试检出力；
- “补了测试”不等于“补了关键风险”；
- 未命中关键失败模式的测试集，不得宣称测试充分。