/t —— 用例化、回归、修 bug

测试产物与附加报告

测试过程保留测试设计基线，并默认额外生成一份给人查阅的 HTML 报告。具体子目录沿用项目既有约定：

• test-cases.md：稳定的测试设计基线，包含需求追溯、验收/对抗/回归用例和测试数据
• quality-report.html：与本轮用例集同目录、默认生成的执行视图，包含结果总览、覆盖缺口、缺陷、环境、风险与上线建议，供人工额外查阅

首次创建 test-cases.md 时使用 docs/templates/test-cases.md；生成质量报告时使用 docs/templates/quality-report.html。test-cases.md 随需求和影响面增量更新；每轮测试完成后根据 真实结果覆盖更新 quality-report.html，历史版本由 Git 保留，不创建大量带日期的报告。

已有 test-cases.md 时直接沿用其目录；首次创建时遵循项目现有测试目录结构。 生成这些产物不要求必须存在工作项 ID，没有工作项时使用 SPEC、分支或当前测试主题描述上下文，不得因此阻塞 /t。 test-cases.md 模板不存在时停止并提示重新执行 /init，不得自行编造模板。 quality-report.html 模板不存在或生成失败时，只说明未生成的原因并继续主流程，不得阻塞测试、Review、MR 或合入判断。

质量报告不是事实源、审批节点或质量门禁。测试结果、缺陷状态和流转结论始终由测试代码、CI、原始日志、 缺陷系统及人工决定维护；报告只能读取并展示这些事实，缺失或损坏不能反向改变它们。

质量报告只能汇总实际执行证据：没有运行的用例写 NOT RUN，环境阻塞写 BLOCKED， 代码分析不能写成运行通过。报告不得包含密码、Token、Cookie、未脱敏账号或生产数据。

计数口径固定为：获得终态 = PASS + FAIL + BLOCKED， 计划用例 = 获得终态 + NOT RUN，执行率 = 获得终态 ÷ 计划用例。

生成质量报告时，先回答两个能直接行动的问题：

• AI 已完成哪些测试：逐项写清用例、AI 实际做了什么、结果、证据和未解决问题
• 还需要人完成哪些测试：逐项写清为什么 AI 不能完成、人要怎么操作、预期看到什么、负责人和状态

AI 能执行的测试必须在交付前执行，不得只因麻烦就转给人。需要人工测试时不能只写“有风险”或 “需人工确认”，必须给出拿来就能照做的操作与通过标准；没有人工测试时明确写“无”。

报告再补充 P0/P1/P2 执行分布、登记缺陷数、验证方式降级、需求偏差与人工裁决，以及仍未完成的 具体事项。没有证据例外时明确写“无”，不得用空表或笼统的“测试通过”代替。

事实关系是单向的：SPEC.md 定义验收，test-cases.md 定义测试设计，测试代码、CI 和原始日志 证明实际结果，缺陷系统维护缺陷状态，最后由这些事实生成 quality-report.html。不得从质量报告 反向修改用例，也不得在用例集和质量报告中分别人工维护两套 PASS / FAIL 数字。

分层覆盖：逐层判断，涉及就补

四层的定义、依赖处理和运行时机见项目 AGENTS.md 的「测试分层」。/t 的职责是 显式判断本次改动涉及哪几层，并让每个涉及的层都有对应测试：

• 单元 / 接口 / 集成 / E2E 逐层写「涉及」或「不涉及 + 一句理由」，默认不写 = 漏测
• 改了函数逻辑 → 单元；动了 API 契约 → 接口；跨模块或跨服务链路变了 → 集成； 关键业务流程变了 → E2E（其他用户可见变化用组件、接口或集成测就好）
• 前端改动要有自己的组件/状态测试，不能靠后端用例兑现

已有代码缺测试时：

1. 本次改动路径上的缺口必须补，否则这次行为根本没被验证
2. 路径之外的历史缺口列成清单写进回归结论，由研发登记为技术债工作项（缺哪层、哪段代码、什么风险）， 不塞进本次范围

三种场景

1. 新功能：验收标准 → 可执行用例

SPEC.md 的「可验证行为」逐条变成测试。一条行为对不上任何测试 = 没验收。

覆盖不只是正常路径：边界、错误路径、并发/重入（如果适用）。 只有 happy path 的测试套件给的是虚假的安全感。

2. 修 bug：Prove-It 模式

1. 先写一个能复现 bug 的测试，确认它 FAIL
2. 再修
3. 用同一个测试证明修好了
4. 跑全量回归

没有复现测试的修复不算修复。 它会以另一种形式回来。

发现缺陷时交给开发的是一个失败的测试，不是一句「这里有问题」。

3. 回归：全量跑，给结论

新需求不只跑新用例。旧用例全量跑一遍，产出回归结论：

跑了 N 条，挂 M 条：
- <用例>：<为什么挂> → <修 / 是预期变更，已更新用例 / 已知问题，工作项 PROJ-xxxx>

这份结论是 MR 「Tests」段的原料。「测试通过」四个字不是结论， 没说清跑了什么、挂了什么、为什么可以放，等于没验。

每轮测试执行完成后都要尝试在本轮 test-cases.md 同目录生成 quality-report.html，这是默认动作，不需要额外选择； 用例只写 ID，不复制完整步骤； 缺陷不得复制完整缺陷档案，但必须保留缺陷系统编号和链接、关联用例、严重级别、对本次上线判断的 影响及原始证据链接。复现步骤、根因和状态流转由缺陷系统维护。

“AI 已完成的测试”只能写有实际执行证据的结果；“需要人完成的测试”每项必须包含具体操作、预期结果、 负责人和状态。上线建议必须能从 P0/P1/P2 结果、阻断缺陷、关键回归、证据例外和人工测试完成状态直接推出。 涉及多仓、公开接口、schema、数据迁移或独立部署单元时，保留模板中的“联合发布评估”； 普通改动删除该可选节，不生成大段“不适用”。

报告交付前自检：不得残留 {{...}} 占位符；测试上下文、commit、环境、执行时间不得为空； 三条计数公式必须成立；每条 FAIL / BLOCKED 都必须关联用例 ID 和原始证据；每项人工测试都有 可执行步骤、预期结果、负责人和状态。 自检失败时不要交付一份看似完整的报告，说明缺口并继续主流程。

定位问题时

先保留证据（日志、失败输出、复现步骤），再动手。 按 复现 → 定位 → 简化 → 修复 → 防护 走，找根因不打补丁： grep 一遍同一个函数的所有调用方，只修 ticket 说的那条路径，兄弟调用方还是坏的。

同一个症状修第二次 → 停下来跑 /ct。

Red Flags

• 测试是照着实现写的（实现改了测试就挂，但行为没变）
• 为了让测试变绿而改测试
• 回归「跑过了」但说不出跑了多少条
• 在用例集和质量报告里分别维护 PASS / FAIL，两个数字迟早不一致
• 报告写了 PASS，但找不到对应测试、CI 或原始执行证据
• 缺陷报告里没有可复现的最小步骤
• 只有单测，改动明明动了接口/链路/用户流程却没补对应层
• 前端改了但一条前端测试都没加
• 不做逐层判断，或一句「不涉及」带过没有理由
• 明知本次改动路径无测试覆盖却继续改，把补测试推给“以后”