update

.codebuddy/skills/test-driven-development/writing-good-tests.md

@@ -0,0 +1,145 @@
+# 写好测试
+
+**在以下情况加载此参考：** 编写或修改测试、添加 mock、或为测试添加清理/辅助方法时。
+
+## 概述
+
+一个测试的存在是为了抓住某个**具体的**破坏。这里的一切都由两条原则统辖：
+
+```
+1. 每个测试都点名它要抓的破坏
+2. 每个测试都跑真东西
+```
+
+严格的 TDD 会自然产出这两点：一个先写、并且在真实代码上亲眼看着它失败过的测试，已经证明了自己**能**失败；而只有当真实依赖被证明缓慢或属于外部时，mock 才配被引入。
+
+## 原则 1：点名它要抓的破坏
+
+在写测试体之前，先回答：**什么样的生产代码改动应该让这个测试失败——而那个改动是 bug 还是一个决定？** 一个测试靠抓住走错的分支、缺失的副作用、传错的参数、边界情况或被破坏的契约来赢得它的位置。
+
+**独立推导期望值。** 用字面量和手工核对过的 fixture；带字面量 `want` 值的表驱动测试是首选形态。一个由**被测代码本身**（或它的辅助函数）算出来的期望值，无论那段代码干了什么都会通过：
+
+```typescript
+// ❌ 镜像断言：同一个 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，或者把这条断言删掉。
+
+```typescript
+// ✅ 真实行为
+expect(screen.getByRole('navigation')).toBeInTheDocument();
+
+// ❌ mock 是否存在
+expect(screen.getByTestId('sidebar-mock')).toBeInTheDocument();
+```
+
+**你的人类伙伴会这样纠正你：** "我们是在测一个 mock 的行为吗？"
+
+**在正确的层级上 mock。** 在替换真实方法之前，先搞清它的每一个副作用；只 mock 掉慢的或外部的那一步操作，把测试真正依赖的东西保留为真实的。不确定时，先拿真实实现跑一遍测试，观察实际上必须发生什么。
+
+```typescript
+// ❌ 这个 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