---
name: test-driven-development
description: "Testing outcome gate for features and bugfixes: before any merge, every behavior change must be backed by test evidence that failed before the change and passes after it. Defines what counts as evidence and what test quality means; does not prescribe your coding order."
---

# 测试结果门(Test Evidence Gate)

## 结果门(合并前的硬性验收)

```
每个行为变更,合并前必须有"先失败、后通过"的测试证据。
```

具体要求:

1. **红→绿证据**: 对每个新行为/修复,存在一个测试,你能出示它在变更前失败(或对着被还原的代码失败)、在变更后通过的**本会话工具输出**。测试从未失败过 = 无法证明它在测真东西。
2. **Bug 修复必带回归测试**: 先有复现该 bug 的失败测试,再谈修复。修完后该测试通过、其余测试不回归。
3. **全绿交付**: 合并前全部测试通过,输出干净(无报错、无告警噪音)。

为什么要求"先失败":变更后才补写的测试天然通过,它验证的是"代码做了什么"而不是"代码应该做什么"——你没见过它抓到问题,就不知道它能不能抓到问题。事后补测的情况下,用"还原变更→测试转红→恢复变更→测试转绿"的方式补出证据。

写代码的顺序(先测后码、先码后测、边探索边写)不做规定;探索性代码写完后,仍要按上述方式补出红绿证据才能合并。

**例外**(与人类确认后): 一次性原型、生成代码、纯配置文件。

## 测试质量(证据必须是真证据)

| 要求 | 说明 |
|---|---|
| 测行为,不测 mock | 测试对象是真实代码路径;mock 只用于不可控外部依赖(真实网关、计费 API)。断言 mock 被调用了几次 ≠ 测试了行为 |
| 一个测试一个行为 | 名字里需要"和"就拆开;名字描述行为而非编号 |
| 真实样本优先 | 用录制的真实网关响应或其二次构造,不凭空捏造响应结构(CLAUDE.md §4.6) |
| 并发/韧性是一等对象 | 重试穿透取消、熔断开路半开、限流结算退款、降级方向都要有测试 |

添加 mock 或测试工具前,读 `testing-anti-patterns.md`(测 mock 行为、给生产类加测试专用方法等常见坑)。

## 常见自欺(仍然不算证据)

- "太简单不用测" —— 简单代码也会坏;库的 bug 击穿所有下游。
- "我手动验证过了" —— 无记录、不可重跑,不是证据。
- "测试一次通过,应该没问题" —— 从未失败过的测试,不知道它测的是什么。

运行命令统一 `conda run -n PolyGateway pytest ...`。
