test-driven-development

name	test-driven-development
description	实现功能、修复 bug 或重构行为时使用——先验证失败测试，再实现当前 Task 的最终行为并保持其测试通过

测试驱动开发

先写测试，确认它因目标行为缺失而失败，再编写最小实现使当前 Task 的目标测试通过。

核心原则： 没有观察到正确的失败，就不能证明测试验证了目标行为。

失败测试 → 验证失败原因 → 最小实现 → 目标测试通过 → 整理 → 再次通过

适用范围

场景	行为
新功能	必须使用 TDD
bug 修复	先写可重现问题的失败测试
行为重构	先用测试锁定行为
纯文档和静态资源	不要求构造虚假测试
生成文件或机械配置	使用与产物相匹配的验证

红—绿—重构

digraph tdd {
    rankdir=LR;
    "编写最小失败测试" [shape=box];
    "失败原因正确？" [shape=diamond];
    "修正测试" [shape=box];
    "编写最小实现" [shape=box];
    "目标测试通过？" [shape=diamond];
    "修正实现" [shape=box];
    "整理代码" [shape=box];
    "再次运行目标测试" [shape=box];

    "编写最小失败测试" -> "失败原因正确？";
    "失败原因正确？" -> "修正测试" [label="否"];
    "修正测试" -> "失败原因正确？";
    "失败原因正确？" -> "编写最小实现" [label="是"];
    "编写最小实现" -> "目标测试通过？";
    "目标测试通过？" -> "修正实现" [label="否"];
    "修正实现" -> "目标测试通过？";
    "目标测试通过？" -> "整理代码" [label="是"];
    "整理代码" -> "再次运行目标测试";
}

红：编写失败测试

测试必须：

• 只验证一个明确行为
• 名称描述业务结果
• 使用真实代码，除非外部系统使 mock 无法避免
• 包含清晰输入、输出和错误断言
• 因目标行为缺失而失败

测试通过说明它覆盖的是已有行为，需要修正测试。测试因语法、导入或环境错误中止，不是有效红阶段。

绿：实现目标行为

编写使当前测试通过的最小最终实现：

• 不添加测试未要求的能力
• 不为开发期间保持服务运行而添加兼容层
• 不保留随后会删除的临时接口
• 遵循设计定义的最终命名和结构

重构：保持目标测试通过

只在目标测试通过后：

• 移除重复
• 改进命名
• 提取必要辅助函数
• 删除失效代码

整理后再次运行相同测试。

smart-exec-plan 中的验证边界

smart-exec-plan 连续执行全部 Stage。Task 和 Stage 不是部署边界，因此当前 Task 的绿色状态只要求其计划规定的目标测试通过。

中间 Task 可以存在：

• 尚未迁移的调用方
• 暂时失败的完整构建
• 暂时无法启动的服务
• 将由后续已定义 Task 完成的集成

这不允许当前 Task 忽略自身失败。以下情况仍须立即修正：

• 当前 Task 新增或修改的测试失败
• 失败与后续 Task 无关
• 出现计划外错误
• 数据可能丢失或损坏
• 测试通过依赖虚假断言或过度 mock

全部 Stage 完成后必须运行完整验证，届时不得保留任何中间失败。

bug 修复

重现 bug 的失败测试
→ 确认测试因该 bug 失败
→ 最小修复
→ 回归测试通过
→ 相关测试通过

不得先修改生产代码再补回归测试。

测试质量

好的测试应具备：

• 最小：一个测试只表达一个行为
• 清晰：名称说明预期结果
• 敏感：业务规则改变时相关测试会失败
• 真实：验证真实代码交互，而不是只验证 mock
• 稳定：不依赖任意等待时间和共享状态

测试是行为规格，不是覆盖率装饰。无法写出准确测试通常说明接口或职责仍不清楚，应停止并检查设计。

禁止做法

• 先写实现后补测试
• 保留预先写好的实现作为参考再声称采用 TDD
• 测试一开始就通过却继续实现
• 把导入错误当作正确红阶段
• 为了通过测试修改正确断言
• 只测试 mock 调用次数而不测试行为
• 用宽泛快照代替关键业务断言
• 为中间服务可用性增加最终不需要的兼容代码
• 在最终验证失败时以“中间状态”为理由继续

Task 完成检查

• 已看到目标测试正确失败
• 失败原因是目标行为缺失
• 已实现设计规定的最终行为
• 当前 Task 的目标测试通过
• 整理后测试仍通过
• 没有计划外改动
• 没有纯开发过渡兼容代码