writing-tests

编写测试

原则是：没有实际收益，就不写测试。不要为了对应某个差异、保留某个字面值，或让微小改动看起来更安全而添加测试。只有当测试能证明一种可能独立于这次编辑而退化的行为时，才值得保留。

测试用于验证业务行为、不变量、转换、运行时和权限边界、生成契约以及用户可见的工作流。如果某项测试唯一有意义的失败原因只是“这个静态值变了”，那它通常是重复，而非保护。

这个测试值得写吗？

只有满足以下所有条件，测试才值得保留。如果有一项不满足，就重写或不写。

1. 验证行为，而非实现。 它断言的是可观察到的契约：返回值、抛出的错误、持久化状态的变化、渲染或导出的输出、API/CLI 响应、生成的产物，或外部可见的副作用。无害的内部重构不应导致它失败。
2. 能检测出行为变异。 至少有一项断言会在行为出现细微错误时失败：条件被取反、边界发生变化、返回了常量，或缺少持久化状态。
3. 具有实质意义。 它不是断言 getter 返回刚设置的值、透传 helper 返回输入、包装器调用它所包装的函数、枚举数组等于手工抄写的自身字面值、公共导出存在，或在运行时断言类型系统已保证的内容。
4. 独立。 无论单独运行还是以任意顺序运行，它都能通过。没有共享的可变状态、隐式的时钟耦合或对夹具顺序的依赖。
5. 放在正确的层级。 纯计算、解析器、reducer、selector 逻辑适合快速单元测试。数据库、架构、验证器、权限、运行时和多单元的连线行为，应使用项目的真实测试环境进行集成测试。完整的用户流程应通过端到端验证。
6. 没有重复覆盖。 同一行为尚未在成本更低的层级得到覆盖。

修复缺陷时，从原始故障入手。通常，价值最高的验证是检查发生故障的路由、API、浏览器流程、命令或集成接缝。修复过程中为某个新建 helper 编写的单元测试不算回归覆盖，除非该 helper 负责处理故障行为。

不要添加以下测试

• 对应实现数据或单个变更字面值的测试：静态配置行、目录状态、导航项、路由表、功能标志默认值、标签、文案或状态列表。
• 测试本应由库自身负责的库行为。
• 仅因代码被提取出来而创建的测试。
• getter/setter、透传、单行包装器、公共导出或仅涉及类型的测试。
• 断言 mock 收到的调用参数恰好等于测试指示它传入的参数。
• 当提取出的逻辑加上浏览器/端到端验证能更直接地证明行为时，不要编写 React/组件挂载测试。
• 无法捕获其声称要覆盖的缺陷类型的伪集成测试，例如：对于依赖真实架构、验证器、索引、触发器、权限或运行时行为的问题，使用手工编写的数据库模拟器。
• 无需推敲就会重新生成的快照或基准文件。

优质测试的类型

• 业务计算、状态转换、验证、筛选、派生、权限、解析器行为、数据转换、生成契约、跨文件一致性、幂等性和类级不变量。
• 针对广泛不变量的属性测试，例如往返、守恒、交换性、规范化、单调性或“只在边界处舍入一次”规则。优先选择验证不变量的属性，而非“不会抛出错误”的属性。
• 针对依赖真实架构、验证器、索引、触发器、权限、提供方/运行时边界或多单元连线行为的集成测试。
• 仅当产物本身就是契约时，才使用黄金测试：例如已发出的事件形状、公共协议输出、渲染后文档的文本/结构、迁移行为、生成的代码或提供方响应解析。明确记录更新命令，且仅在确有意图时重新生成。

结构与运行器

遵循项目既有的测试架构：运行器、目录布局、fixture 约定、文件名后缀、包脚本和分层方式。不要另创一套模式。

如果项目有默认运行器，就使用它。只有在确有强制性约束时才使用其他运行器，例如需要特定运行时、DOM 环境、原生视觉测试工具、模块重置功能、框架编译器或集成测试库。除非项目有明确规定，否则不要在同一个包或代码范围内混用运行器。

除非项目有共享 fixture 约定，否则 fixture 和构建器应与测试放在一起。Provider/API fixture 应保留真实响应的语义；如需精简，应缩减体量，而不是改变含义。

AI 编写指南

先写断言，再写测试准备代码。每个测试尽量只包含 1 到 3 个有意义的断言。重点覆盖 Agent 容易忽略的失败场景：null、空值、边界、错误、并发、权限和业务规则边界。

运行目标测试，以及受影响代码范围所需的项目检查。修复 bug 时，在可行的情况下，证明该测试在原始故障条件下会失败。