unit-testing

单元测试

此技能可帮助你编写、重构、审查和运行单元测试：这类快速、隔离的检查从调用方的角度测试一个小型导出契约，不依赖框架接线、数据层或浏览器。无论是编写新测试、完善现有测试、决定断言内容，还是评估他人对单元测试所做的更改，都可以使用此技能。

这些约定与框架无关——无论项目使用 Jest、Vitest、Node 内置的测试运行器，还是类似的运行器，都适用。示例使用 TypeScript 编写，并采用大多数运行器共有的 describe/it/expect 词汇；请将 it/test、断言入口和模拟调用视为项目测试运行器所提供功能的代称。

如果项目提供了针对特定运行器的功能，那么该功能负责机制——配置文件、测试池与隔离、覆盖率提供程序、报告器，以及运行器自身的模拟和假计时器 API；而此技能负责决定断言什么、测试如何组织，以及行为是否适合用单元测试验证。如果你想了解该使用哪个选项或调用哪个函数，请使用运行器的相关功能；如果你想了解测试应该验证什么，请使用此技能。

单元测试只有在能快速、独立地从外部验证一个小型导出契约时，才有存在的价值。如果测试过度拟合实现细节，或取代了可信度更高的集成测试或端到端测试，就会成为负担——因此，此技能也包括了解何时_不_应编写单元测试，以及应将相关行为交由更全面的测试验证。

本文档中的关键词“MUST”“MUST NOT”“REQUIRED”“SHALL”“SHALL NOT”“SHOULD”“SHOULD NOT”“RECOMMENDED”“MAY”和“OPTIONAL”，应按 RFC 2119 中的定义进行解释。

测试范围

请参阅 testing-scope.md，了解以下内容：

• 借助决策图判断某项行为应由单元测试、集成测试还是端到端测试覆盖
• 保持纯辅助函数测试简洁，并将浏览器、数据层和框架相关行为交由更全面的测试验证
• 识别单元测试的可信度何时低于集成测试或端到端检查
• 在依赖帧的测试替身中保留相关中间状态和完成顺序，但不声称具备原生证据
• 在渲染器不可用时检查公开的几何属性和配置，但不声称替代了生产 UI 或像素证据

测试组织与命名

请参阅 spec-structure-and-naming.md，了解以下内容：

• 添加、重命名、重新分组或审查 describe(...) 和测试用例块
• 按类型命名测试主体：可调用对象使用 ()，UI 组件使用尖括号，非可调用契约不加后缀
• 编写清晰明了、读起来像验证语句的场景名称
• 对重复条件或情况进行分组，避免重复函数名

行为与实现细节

请参阅 behavior-and-implementation-details.md，了解以下内容：

• 避免测试过度拟合私有辅助函数、依赖内部实现、回调机制或调用形式
• 让断言聚焦于从调用方角度可见的导出行为
• 判断某项实现细节何时确实属于公开契约
• 区分外部规范或项目公开契约所承诺的精确值与照搬的私有字面量

固件、伪实现与 AHA

请参阅 fixtures-fakes-and-aha.md，了解以下内容：

• 创建固件、设置辅助函数、边界伪实现、模拟对象、间谍对象或共享常量
• 当测试用例需要清晰直观时，选择重复而非过早抽象
• 让可复用的测试辅助工具易于理解、范围明确，并以行为为导向

断言、快照与副作用

请参阅 assertions-snapshots-and-side-effects.md，了解：

• 如何为值、异步错误、副作用和模拟调用选择断言
• 如何断言某个分支具有区分性的可观察输出，并覆盖一个反例，而不只是确认某些内容已渲染
• 如何判断何时适合使用快照，以及如何让快照保持聚焦
• 如何验证可观察结果，而不依赖偶然的实现细节

Schema 和类型

请参阅 schemas-and-types.md，了解：

• 如何测试 schema、编解码器、解码后的响应结构，以及集合／列表响应解码
• 如何处理纯类型模块和编译时契约
• 如何平衡运行时 schema 检查与编译时类型预期

审查清单

请参阅 review-checklist.md，了解：

• 如何对单元测试进行实现自查或代码审查
• 如何检查结构、命名、测试夹具、模拟、断言和范围
• 可选的覆盖率门槛：项目的覆盖率命令、配置的阈值以及忽略指令的使用规范
• 当单元测试无法以足够的置信度覆盖行为时，如何报告剩余风险

项目默认规范

这些默认规范有意保持简短。请参阅链接的参考文档，了解示例、边缘情况和审查标准。如果规则提到“项目惯例”，请遵循现有的本地模式；如果没有现成模式，请建立一种并保持一致。

指南：

• MUST 遵循项目的单元测试文件命名惯例，将单元测试与源文件放在一起（例如，放在源文件旁的 *.test.ts 或 *.spec.ts），除非现有的本地模式要求使用其他位置。
• MUST 在测试运行器要求或支持显式导入时，显式导入测试框架的 API，而不是依赖隐式的全局作用域符号。
• MUST 在项目中一致使用所选的测试用例函数（it 或 test），不得在同一项目中混用其他写法。
• MUST 通过项目的单元测试命令（例如 npm run test:unit）运行单元测试，排查特定故障时除外。
• MUST 在新增或修改单元测试后运行项目的格式化和 lint 命令；如果项目有类型检查命令，也必须运行。
• SHOULD 在置信度取决于框架运行时连接、数据层、浏览器行为、渲染、路由或面向用户的 UI 时，优先选择集成测试或端到端测试。