testing-principles

与语言无关的测试原则

这里的测试保证已接受的行为，而下一个 Agent 会将每项现有测试都视为必须保留的要求。因此，脆弱、重复或贴合实现细节的测试会变成一项虚假的要求：它会被设法绕过，而这种变通会给实现留下技术债。只保留其验证价值值得维护的测试。

测试选择

• 默认通过用户和调用方可观察到的边界上的集成测试和端到端测试，证明已接受的行为。对于单个有代表性的边界测试无法证明的逻辑情况（例如计算、解析或分支规则），添加单元测试。
• 每项行为声明由一项测试负责：此类逻辑由其单元测试负责，其他行为则由可观察到该行为的最窄集成或端到端边界上的测试负责。在更宽边界或某种变体（视口、设备、角色）上的测试，证明该边界或变体新增的内容，例如接线、映射、持久化、渲染或导航；对于由其他测试负责的规则，最多保留一个有代表性的用例。
• 在精简测试之前，根据已接受的结果确定所需的验证边界。通过应用或服务入口交付的结果，包含相关的生产组合，例如路由、Provider、状态归属或适配器。孤立的组件测试或通过测试构建的替代组合无法证明这些接线。复用能够穿过该边界的验证，或选择一项能够做到这一点的测试；根据必须观察的内容选择测试框架，而不是根据组件数量或测试泳道配额。低于该边界的测试可能无法发现断开的操作、丢失的状态更新或失效的状态转换。明确限定于组件范围的结果仍使用其组件边界。
• 将覆盖率视为发现未测试区域的诊断信号，而非目标；任何 CI 阈值都是项目配置，不是质量目标本身。
• 项目有配置速度预算时，按预算执行。否则，只有当观察到的反馈或 CI 成本对当前结果影响显著时，才调查测试速度；若测试所需的验证边界要求如此，则保留较慢的测试。

测试设计规则

• 将每项测试组织为 Arrange、一次 Act 和 Assert；可以通过多条断言来证明一项行为。
• 遵循仓库的测试命名约定，并在名称中说明条件和可观察结果。
• 通过公共边界或集成边界测试行为。断言应验证返回值、输出、错误或状态变化，而不是私有实现。
• 使用独立推导出的字面值、属性、获准的快照或夹具预期值。根据实现推导出的判定标准无法发现同一实现中的缺陷。
• 保持每项测试的预期结果无条件成立。当表驱动或基于属性的方法能让每个用例分别报告，并使用独立的判定标准时，可以采用这些方法。
• 覆盖已接受的边界行为和错误行为；根据契约推导用例，而不是添加泛化的边缘情况组合。
• 每项测试都自行创建并清理状态，可单独运行且顺序不限，并控制会影响测试结果的时间或随机性。
• 保持测试可执行。修复或删除已不再描述已接受行为的测试；恢复仅为绕过故障而禁用的测试。

Mock 和边界规则

• 对直接的外部 I/O 边界使用 Mock；内部业务逻辑和被测边界保持真实。
• 使用现有的应用自有适配器作为 Mock 边界。仅当无法通过当前设计控制外部 I/O、不稳定的契约或所需的替代实现时，才引入适配器。
• 将 Mock 行为限制在测试所需的契约范围内。

数据层测试

当数据访问只是被测行为的依赖项时，基于 Mock 的测试就足够了。当被测对象是查询、仓库实现、架构约束或迁移兼容性时，应使用项目的真实数据库引擎或其认可的等效环境进行验证。根据仓库配置确定测试环境；如果不存在有代表性的环境，且添加此类环境不在已批准的工作范围内，则应报告缺少的验证决策。

根据设计文档或仓库配置中指定的架构来源，交叉核对数据访问代码。验证架构来源是证明表、列、类型、约束或方言兼容性的必要条件；Mock 成功只能证明 Mock 边界内的行为。

验证要求

能力探测后置条件

当能力探测使用使用方的边界，并断言使用方所需的确切属性时，即为通过。命令成功、导入成功或对象存在只能作为设置证据。

测试组织

遵循仓库既有的测试路径、运行器路由和命名规则。建立经过批准的新约定时，仅当不同测试类型的设置、运行器或环境有所不同时，才将其分开。

回归测试

• 为每个可复现的行为缺陷修复添加回归测试。如果无法执行复现，则记录原因以及可防止问题复发的替代静态、契约或环境证据。
• 对缺乏特征描述的旧代码进行保持行为不变的更改前，应先建立通过的特征描述证据，并在更改后重新运行。

参考资料

• references/frontend.md：编写、修改或审查组件、钩子或 UI 集成测试时阅读
• references/e2e.md：编写、修改或审查浏览器 E2E 测试时阅读