test-guard

Test Guard

你在代码上线前审查新生成或修改过的测试代码。在第一轮测试编写完成、且代码尚未展示、提交或合并前，严格执行以下规范。请扮演敏锐的审查者，而非死板的挑剔者：重点找出浪费维护精力或掩盖真实 Bug 的代码，忽略无关紧要的样式偏好。

这些规范之所以存在，是因为 AI 编码 Agent 经常过度生成测试。常见的失败模式包括：高度依赖 Mock 的单元测试（仅仅断言了实现细节）、只差一个数值的近乎重复的测试主体，以及重新验证框架逻辑而非项目本身业务逻辑的测试。这些代码在 Diff 中看似很有产出，但往后每一次维护都是成本。

何时触发此 Skill

编码 Agent 刚编写了新的测试函数或测试文件（适用于任何语言）
你正在编辑现有的测试
你正在审查包含测试变更的 Diff
用户要求你编写、新增或审查测试

先理清项目的上下文

这些规范具有通用性，但具体落实需因地制宜。在开始审查前：

检查项目自带的 Agent 指引（CLAUDE.md、AGENTS.md）与测试文档。当项目专属的测试规范与本 Skill 冲突时，优先遵循项目本身的规范。
确认测试技术栈，并阅读对应的参考文档以了解具体的模式：
- Python / pytest → references/pytest.md
- PHP / PHPUnit / Pest / WordPress → references/phpunit.md
- JavaScript / TypeScript / Jest / Vitest → references/jest.md
若项目调用了 LLM API、使用了 Agent 框架，或集成了可观测性/遥测（telemetry）机制，请一并阅读 references/llm-app-testing.md——该文档针对 LLM 应用程序补充了三条专项规范。
梳理项目的系统边界：网络调用、数据库、文件系统、时钟与随机数、第三方 SDK、LLM API。项目现有的 Fixture 与测试辅助工具通常能反映出项目划分这些边界的位置。

执行步骤

阅读测试代码：查看 Diff、新文件或正在修改的段落。
对照以下规范逐一检查每个测试。
简明扼要地报告违规项：规范编号、位置、违规原因、建议修复方式。
若用户在编写测试前显式调用本 Skill，请在撰写时直接落实规范——切勿先写出违规代码再自己标记。

编写新测试时，请针对每个测试反问：“这个测试抓住了本测试集中其他测试抓不到的什么具体 Bug？”如果无法明确回答，就不要写。

九大规范

规范 1：测试行为，而非实现

从调用者的角度测试代码的功能。断言返回值与可观察的副作用（side effects）。绝不要断言某个内部辅助函数是否带着特定参数被调用——这种测试在每次重构时都会失败，而且抓不到任何真实 Bug。

违规模式： 断言某个内部函数的 Mock 被调用了，而该函数并不属于系统边界。
修复方式： 断言调用者能观察到的返回值或状态变更。

规范 2：每一个 Mock 都必须有正当理由

仅在系统边界进行 Mock：网络与 HTTP 调用、LLM API、数据库、外部文件上的文件系统 I/O、时钟与随机数、第三方 SDK。绝不要为了隔离“单元”而 Mock 内部类或辅助函数——你自己制造的缝隙往往会掩盖最值得捕捉的集成 Bug。

当你在边界进行 Mock 时，要断言调用者如何使用响应结果，而不是断言 Mock 接收到了哪些具体参数。

规范 3：一个测试对应一个场景，多变体改用数据驱动

若两个或多个测试拥有完全相同的 Setup 流程，仅仅在输入/输出值上有所不同，请将其合并为一个数据驱动测试（@pytest.mark.parametrize、PHPUnit #[DataProvider]、Jest test.each）。

适合拆分为独立测试的情况： 不同的 Setup 流程、不同的断言、不同的 Mock 配置，或是恰好使用了同一个函数但本质上不同的业务场景。

规范 4：每个测试都必须证明其存在的价值

反问：“这个测试抓住了其他测试抓不到的什么 Bug？”删除那些只能抓到拼写错误、验证数据类默认值、或是测试微不足道透传逻辑的测试。

常见缺乏正当理由的测试： 构造函数设置属性、测试类型系统本身就已经禁止的输入、日志消息的字符串格式化、常量是否等于其字面值。

规范 5：根据场景为测试命名

命名模式：test_<scenario>_<expected_outcome>（测试_<场景>_<预期结果>）。测试名称读起来应该像一条需求规格，而不是重复函数的签名。

坏示例	好示例
`test_parse_response_missing_field`	`test_malformed_response_falls_back_to_default`
`test_get_language_no_class`	`test_element_without_class_returns_empty_language`
`test_add_tags_single_string`	`test_single_tag_normalizes_to_list`

规范 6：线上回归测试是不可触碰的

用于复现真实线上 Bug 的测试永远是有存在价值的。请在测试名称或注释中引用对应事件（日期、Issue ID 或简短描述），且绝不要删除它们。它们不受规范 4 的限制——事件本身就是它们存在的理由。

规范 7：不要为框架自带的保障编写测试

不要去测试验证库能否正常验证、ORM 能否正常提交、路由能否正常返回 404，或者测试框架的 Fixture 能否正常运行。去测试构建在框架之上的你自己的逻辑。

违规模式： 如果删光项目所有的自定义代码只保留框架默认设置，测试依然能通过。

规范 8：状态对象与数值对象是真实存在的，绝不 Mock

绝不要 Mock 数据模型、DTO、实体（Entity）或状态对象。请直接实例化真实对象。Mock 状态对象会掩盖字段名拼写错误和校验错误——而这恰恰是最值得捕捉的 Bug。如果构造真实对象很痛苦，这属于设计反馈，而不是 Mock 的理由；可以写一个小型 Builder 或 Factory 辅助函数来简化构造。

规范 9：被测基础设施必须使用真实基础设施

当数据库查询、Schema 行为或持久化逻辑本身就是测试的主体时，请连接真实的测试数据库，并通过 Fixture 执行真实的数据库迁移（Migration）。在那种情况下 Mock Session 抓不到任何问题。只有当持久化只是被测行为的副作用时，Mock 数据库才是可以接受的。

报告格式

当指出违规项时，请统一使用以下格式：

**规范 N 违规** 位于 `tests/path/file.ext::<test_name>`
- 违规内容：<用一句话说明具体违反了什么>
- 修复建议：<用一句话说明应该如何修改>

按文件分栏汇总违规项。若某个文件没有违规，则无需提及。

严重程度指南

并非所有违规的严重点都相同。请根据实际情况做出判断：

必须修复（Must fix）： 规范 1、2、8 —— 这些问题会掩盖真实 Bug 或导致测试极其脆弱
建议修复（Should fix）： 规范 3、4、5、7 —— 这些问题会导致代码膨胀与维护负担
不可触碰（Sacred）： 规范 6 —— 绝不删除，始终允许
值得关注（Worth noting）： 规范 9 —— 属于测试架构层面；可以指出，但不要为了它而阻碍细微的修改

参考文档

references/pytest.md — Python/pytest 模式：parametrize、fixtures、mock 边界、真实的 Pydantic 实例
references/phpunit.md — PHP/PHPUnit/Pest 模式，包含 WordPress 与 WooCommerce 的测试边界
references/jest.md — Jest/Vitest 模式：test.each、模块 mock、msw、快照测试规范
references/llm-app-testing.md — 针对 LLM 应用程序的三条追加规范：Prompt 契约、可观测性集成、Agent 流程转换