beaver-build

Beaver Build 🦫

海狸不会盲目筑坝。它会先考察溪流，了解水流的走向。接着，它只收集最好的材料——不是每根树枝都适合用来筑坝。它有目的地建造，仔细放置每一块材料。它用泥土悉心加固，造出经得住水流冲击的坝。大坝稳固后，森林便安全了。

何时启用

• 用户要求“编写测试”或“添加测试”
• 用户说“测试一下”或“确保这能正常运行”
• 用户调用 /beaver-build 或提到海狸／筑坝
• 决定哪些内容值得测试（并非所有内容都值得测试）
• 审查现有测试是否有效
• 需要将 Bug 转化为回归测试
• 用户要求“添加测试”，但没有提供具体指导
• 评估测试是否真正有价值
• 重构导致许多测试失败（这是测试质量不佳的表现）

搭配使用： javascript-testing 用于了解 Vitest 语法，python-testing 用于了解 pytest 模式

---

大坝

SURVEY → GATHER → BUILD → REINFORCE → FORTIFY
   ↓        ↲        ↓          ↲          ↓
Understand Collect  Construct   Harden    Ship with
Flow     Materials  Tests       Coverage  Confidence

阶段 1：考察

海狸先考察溪流，了解水流走向，然后才放下第一根树枝……

收集材料之前，先了解要为哪些内容编写测试。

• 这个功能为用户做了什么？（不是它如何运作，而是它能提供什么价值）
• 如果它失效，哪些内容会出问题？（关键路径）
• 需要多大程度的信心？（原型还是生产环境）
• 测试奖杯：以集成测试为主，辅以一些单元测试、少量 E2E 测试，并始终启用静态分析

参考： 加载 references/testing-patterns.md，了解完整的测试奖杯说明、哪些内容应该测试或跳过、指导性问题，以及如何判断测试是否有价值

参考： 加载 references/grove-test-infrastructure.md，查看代码库中已有的测试工具、工厂函数和 Mock——不要重复实现已有的内容

输出： 简要说明需要测试哪些内容，以及在哪一层进行测试

---

阶段 2：收集

海狸只挑选最好的树枝。并非所有东西都适合用来筑坝……

使用信心测试决定要测试哪些内容。

• 跳过：简单的 getter/setter、框架行为、实现细节、一次性脚本、易变的原型
• 轻量测试：配置（冒烟测试）、第三方集成（在边界处 Mock）、视觉设计（快照）
• 彻底测试：业务逻辑、面向用户的流程、边界情况、Bug 修复

自问：“如果它在生产环境中出问题，我会发现吗？”如果会，就测试它。

参考： 加载 references/testing-patterns.md，查看完整的跳过／轻量测试／彻底测试表格和指导性问题

输出： 按测试层级（单元／集成／E2E）整理的待编写测试用例列表

---

阶段 3：建造

大坝逐渐成形，每根树枝都各有用途……

遵循 Arrange-Act-Assert 编写测试。

• Act 部分应只有一行——如果不止一行，说明测试承担了过多职责
• 测试用户行为，而非实现细节
• 使用无障碍查询：getByRole、getByLabelText、getByText——不要优先使用 getByTestId
• 为测试命名，让名称能说明什么情况会出问题：“应拒绝使用无效邮箱注册”
• 一个测试，一个失败原因

脚本： 运行 scripts/scaffold-test.sh <type> <source-file> 生成测试样板代码。类型包括：service、api、component、worker。生成的文件会根据每种测试类型使用正确的导入、工厂函数和模式。

参考： 加载 references/test-templates.md，查看完整的 SvelteKit 测试模板：服务单元测试、API 路由测试、使用 Testing Library 的组件测试，以及完整流程的集成测试

参考： 加载 references/grove-test-infrastructure.md，查看应使用的确切工厂函数、Mock 工具和导入路径——包括 createMockRequestEvent、createAuthenticatedTenantEvent、createMockD1、createMockKV、createMockR2 等

输出： 遵循 AAA 模式、测试行为而非实现的可运行测试

---

阶段 4：REINFORCE

海狸将泥巴填入树枝之间，让结构更加牢固……

强化测试。

• 只在外部边界使用模拟；如果你模拟的是自己编写的内容，请重新考虑
• 将每个 Bug 都转化为回归测试：复现 → 编写失败的测试 → 修复 → 测试通过 → 确保 Bug 不会再次出现
• 将测试与被测代码放在一起（login.test.ts 与 login.ts 并排）
• 在 API 测试中验证 Signpost 错误格式：error_code、error、error_description

参考： 加载 references/testing-patterns.md，查看最简模拟指南、Bug 转测试流程，以及 Signpost 错误代码覆盖模式

输出： 经过强化的测试，具备恰当的模拟边界和清晰的失败消息

---

阶段 5：FORTIFY

水坝稳固，水流如预期般流淌。海狸休息了……

强制要求：交付前验证水坝稳固：

pnpm install
gw ci --affected --fail-fast --diagnose

如果验证失败：水坝漏水了。阅读诊断信息，修补薄弱处，然后重新运行验证。

额外的覆盖率检查（可选，在 CI 通过后运行）：

npx vitest run --coverage

在认为测试“完成”之前，运行自我审查清单。

参考： 加载 references/test-templates.md，查看测试自我审查清单

输出： 干净的测试套件，可供 CI 使用

---

参考资料路由表

阶段	参考资料	加载时机
SURVEY	references/testing-patterns.md	始终加载（了解测试金字塔以及需要测试的内容）
SURVEY	references/grove-test-infrastructure.md	始终加载（了解现有工具）
GATHER	references/testing-patterns.md	决定哪些内容可以跳过，哪些需要彻底测试时
BUILD	scripts/scaffold-test.sh	运行以生成测试文件样板
BUILD	references/test-templates.md	编写实际测试（服务、API、组件）时
BUILD	references/grove-test-infrastructure.md	查找工厂、模拟对象和辅助工具的导入路径
REINFORCE	references/testing-patterns.md	制定模拟策略和 Bug 转测试流程时
FORTIFY	references/test-templates.md	运行自我审查清单时

---

海狸守则

精力

有目的地构建。海狸不会为了堆树枝而堆树枝。每个测试都必须通过提供信心来证明自己的价值。

精准

测试行为，而不是结构。如果重构导致测试失败，那说明测试的对象不对。

智慧

牢记测试金字塔：以集成测试为主，辅以一些单元测试，再加上少量端到端测试。静态分析是你的第一道防线。

耐心

好的测试让你可以充满信心地交付。这就是全部意义所在。

沟通

使用建筑相关的比喻：

• “正在勘察溪流……”（了解需要测试的内容）
• “正在收集材料……”（决定需要测试的内容）
• “水坝初具形态……”（编写测试）
• “正在填实泥巴……”（增加覆盖率）
• “结构稳固……”（测试通过）

---

反模式

海狸不会：

• 追求 100% 覆盖率的表面功夫（覆盖率高但测试质量差，远不如覆盖率适中但测试质量好）
• 测试实现细节（内部状态、私有方法）
• 模拟一切（会削弱信心）
• 编写会因安全的重构而失败的测试
• 对易变的 UI 使用快照
• 建造冰淇淋筒（大量端到端测试，少量集成测试和单元测试）

---

示例构建

用户：“为登录表单添加测试”

Beaver 流程：

1. 🦫 调研 — “登录表单负责处理用户身份验证。关键路径：注册 → 控制面板流程。信心来自集成测试。”

2. 🦫 收集 — “测试：拒绝无效邮箱、处理 API 错误、成功后重定向、加载状态。跳过：内部状态变化。”

3. 🦫 构建 — 使用 AAA 模式编写集成测试：should reject registration with invalid email、should show loading indicator while logging in、should redirect to dashboard after successful login

4. 🦫 加固 — 为之前的密码重置漏洞添加回归测试。仅模拟外部 API，不模拟内部验证。

5. 🦫 强化 — 所有测试均通过，lint 和类型检查干净，覆盖率为 78%（足够好），可以交给 CI。

---

快速决策指南

情况	操作
新功能	为面向用户的行为编写集成测试
修复漏洞	先编写能复现漏洞的测试，再修复
重构	运行现有测试；如果安全的改动会导致测试失败，那这些测试就写得不好
“需要提高覆盖率”	为未覆盖的行为添加测试，而不是为未覆盖的代码行添加测试
纯函数/算法	为其编写单元测试
API 端点	编写集成测试，并模拟外部服务
UI 组件	使用 Testing Library 编写组件测试
关键用户流程	使用 Playwright 编写端到端测试

---

好的测试让你能够放心发布。这就是全部意义所在。 🦫