8.5 KiB
写好测试
在以下情况加载此参考： 编写或修改测试、添加 mock、或为测试添加清理/辅助方法时。
概述
一个测试的存在是为了抓住某个具体的破坏。这里的一切都由两条原则统辖：
1. 每个测试都点名它要抓的破坏
2. 每个测试都跑真东西
严格的 TDD 会自然产出这两点：一个先写、并且在真实代码上亲眼看着它失败过的测试，已经证明了自己能失败；而只有当真实依赖被证明缓慢或属于外部时，mock 才配被引入。
原则 1：点名它要抓的破坏
在写测试体之前，先回答：什么样的生产代码改动应该让这个测试失败——而那个改动是 bug 还是一个决定？ 一个测试靠抓住走错的分支、缺失的副作用、传错的参数、边界情况或被破坏的契约来赢得它的位置。
独立推导期望值。 用字面量和手工核对过的 fixture；带字面量 want 值的表驱动测试是首选形态。一个由被测代码本身（或它的辅助函数）算出来的期望值，无论那段代码干了什么都会通过：
// ❌ 镜像断言：同一个 builder 算出了等式两边 —— 永远为真
const expected = buildSearchQuery({ tag: 'urgent' });
expect(buildSearchQuery({ tag: 'urgent' })).toBe(expected);
// ✅ 手工推导的字面量
expect(buildSearchQuery({ tag: 'urgent' })).toBe('tag:"urgent"');
不要写变更探测器。 如果只有有意为之的决定才能让一个测试失败——某个常量的取值、某句消息的精确措辞、某个私有结构——那它会在重新设计时误报、却对真 bug 一路沉睡。要测那个依赖于该决定的行为：不是 expect(MAX_RETRIES).toBe(5)，而是"一次失败的调用会被重试 5 次，且第 6 次尝试永不发生"。
测行为，不测文本。 断言某个脚本、skill 或配置文件"包含某一行"，只能证明源文件就是源文件。要拿受控输入去跑脚本，然后断言它的输出、副作用或退出码。用来指挥 agent 的文档，靠消费它的 agent 的行为来测（writing-skills）；写给人看的散文根本不该有测试。
测你的代码，不测框架。 测你的代码在其边界上所做的契约——你注册的那条路由、你发出的那条查询、你产出的那个 payload。上游的机制是它们维护者该写的测试（经典反例：断言你的 router 会调用一个已注册的 handler——那是框架的测试，不是你的）。当上游行为确实让你意外时，写一个窄窄的表征测试，把那个假设点名出来。同样的边界也适用于你代码内部：构造函数、getter、常量和琐碎的转发，只有当它们做校验、归一化、给默认值、做推导、做强制或产生副作用时才配有测试——否则就去断言第一个依赖于它们、且对消费者可见的结果。
门控函数
在写测试体之前：
点名那个会让这个测试失败的生产代码改动。
点不出来 → 围绕一个可观察的行为重新设计
"源文本变了" → 去跑这个产物，断言它的效果
只有有意为之的决定能让它失败 → 这是变更探测器；改测那个
依赖于该决定的行为
确认期望值的推导过程没有用到被测代码。
如果它复用了被测代码的逻辑或辅助函数：
换成字面量或手工核对过的 fixture
原则 2：跑真东西
mock 不配拥有断言。 一个针对 mock 的断言，在 mock 存在时通过、在 mock 缺席时失败——它对被测组件什么都没说。要断言真实组件的行为；如果你要检查的就是那个 mock，那就把它 unmock，或者把这条断言删掉。
// ✅ 真实行为
expect(screen.getByRole('navigation')).toBeInTheDocument();
// ❌ mock 是否存在
expect(screen.getByTestId('sidebar-mock')).toBeInTheDocument();
你的人类伙伴会这样纠正你： "我们是在测一个 mock 的行为吗？"
在正确的层级上 mock。 在替换真实方法之前，先搞清它的每一个副作用；只 mock 掉慢的或外部的那一步操作，把测试真正依赖的东西保留为真实的。不确定时，先拿真实实现跑一遍测试，观察实际上必须发生什么。
// ❌ 这个 mock 吞掉了配置写入，而重复检测正是要读它
vi.mock('ToolCatalog', () => ({
discoverAndCacheTools: vi.fn().mockResolvedValue(undefined)
}));
// ✅ 只 mock 掉缓慢的服务器启动；配置写入保持真实
vi.mock('MCPServerManager');
让替身足够具体。 当参数、调用次数或调用顺序本身就是契约的一部分时，就要断言它们——一个什么都接受的 fake 什么都没验证。给每个分支（成功、报错、格式错误）配它自己的 fixture 或 spy，这样走错的分支就无法满足期望。
完整镜像真实数据。 按现实中的完整结构来 mock——所有有文档的字段——而不是只 mock 你这个测试会读的那几个。部分 mock 会静默失败：下游代码读到一个被省略的字段时，测试通过、集成崩掉。
生产类只承载生产方法。 只有测试才需要的清理逻辑，放在测试工具里，绝不作为生产类上的 destroy()。自问：这个方法只被测试调用吗？这个类拥有这份资源的生命周期吗？答错了 → 挪进测试工具。
宁可用真实组件，也不要复杂 mock。 当 mock 的搭建代码超过测试逻辑本身、mock 漏掉了真实组件才有的方法、或者 mock 一改测试就崩时，改成用真实组件的集成测试。你的人类伙伴会这样问： "这里我们真的需要用 mock 吗？"
门控函数
在添加 mock 或测试辅助函数之前：
列出真实方法的副作用；测试所依赖的那些保持真实 ——
只 mock 它们下面那一层「慢的/外部的」。
mock 的返回值要完整镜像真实结构。
只被测试调用的方法，属于测试工具，不属于生产代码。
正要对 mock 本身下断言？
把它 unmock，或者删掉这条断言。
测试与实现一同交付
TDD 循环——失败的测试、最小实现、重构——就是"完成"的定义。交付这个行为需要的测试，且只交付这些：琐碎代码和给人看的散文都不配有测试，而一个为了满足流程而写的测试会永远付出维护代价。
变异检查
收尾之前，在脑子里对生产代码做变异；对每一种现实的变异，都应至少有一个测试失败：
- 常量或参数写错
- 分支处理写错
- 缺失状态变更或副作用
- 返回空值或默认值
- 缺失对零值、空值、nil、未授权或格式错误输入的校验
一个没有任何测试能抓住的变异，标记出该行为无保护——或者那个测试是同义反复。
快速参考
| 当你…… | 就这么做 |
|---|---|
| 写任何测试 | 点名它要抓的破坏——是 bug，不是决定 |
| 构造期望值 | 手工推导；绝不用被测代码去算 |
| 测一个脚本或文档 | 跑它 / 压测它的消费者；绝不 grep 它的文本 |
| 想给依赖写测试 | 测你的边界契约，不测它们有文档的机制 |
| 想对一个被 mock 的元素下断言 | 改测真实组件，或者把它 unmock |
| 正要 mock 某个方法 | 先搞清它的副作用；在慢的/外部的那一层上 mock |
| 构造一个 mock 返回值 | 完整镜像真实结构 |
| 需要只有测试才用的清理逻辑 | 放进测试工具 |
| 眼看 mock 搭建代码膨胀 | 改成用真实组件的集成测试 |
| 写完一个测试文件 | 跑一遍变异检查 |
危险信号
- 搭建过程和断言共用同一个对象，等式必然成立
- 这个测试只可能因为 panic、崩溃或选择器缺失而失败
- 这个测试在每次有意改动时都失败，却从不在意外破坏时失败
- 期望值藏在循环、builder 或辅助函数背后
- 这个测试去 grep 源码文本，或者断言某个已删除的符号仍然是删除状态
- 就算只剩下框架，这个测试依然"成立"
- 这个测试是为覆盖率而存在的，不检查任何副作用或结果
- 某条断言检查的是
*-mock这种 test ID，或者你把 mock 去掉它就失败 - 某个方法只被测试文件调用
- mock 搭建占了测试的一半以上，或者你说不出为什么需要这个 mock
- "为了安全起见"而 mock