superior-testing

更可靠的测试

让测试为行为和风险提供持久的证据。让测试套件适配仓库现有的工具和架构；不要强行套用通用的测试金字塔、框架或覆盖率目标。

明确契约

编写测试前，先明确：

• 要保护的可观察行为或不变量；
• 测试必须识别的故障或回归；
• 可观察到该行为的公共边界；
• 涉及的依赖、状态、时间、并发和外部系统；
• 现有的测试约定、辅助工具、夹具和 CI 限制。

对于已报告的 bug，在实际可行时，应先复现故障，再修改实现。确认测试因预期原因而失败，而不是因为夹具、环境或断言有问题。

选择最精简且可信的测试

选择单元、组件、集成、契约、端到端、基于属性或迁移测试时，或者变更需要在多个层面获得覆盖时，请阅读 references/test-strategy-and-levels.md。

优先选择成本最低、且能测试风险实际归属位置的测试：

• 在稳定的可调用边界测试纯规则；
• 使用集成测试验证持久化、序列化、框架接线或服务边界；
• 使用契约测试验证独立演进的生产者和消费者；
• 对少量关键流程使用端到端测试，前提是接线本身就是风险所在。

不要在每个层面重复相同断言。只有在能验证不同故障模式时，才增加另一层测试。

提高测试信号

• 断言可观察结果、状态转换、产生的效果或稳定契约，而非私有方法调用。
• 根据契约选取有代表性的边界情况和无效输入，而非随意排列组合。
• 确保每个失败都能提供足够信息，指出哪个契约遭到破坏。
• 保持快照小而有明确目的；审查语义变更，不要直接接受大范围的快照变动。
• 将行覆盖率视为发现问题的信号，而非正确性的证明。
• 除非现有命名和结构妨碍测试表达其目的，否则应予以保留。

如果请求范围允许，生产代码可以添加小型的可测试性切入点，前提是它能改善实际设计。不要暴露私有内部实现、添加依赖注入机制，也不要仅为满足测试框架而改变行为。

确保执行可靠

如果测试涉及共享夹具、数据库、文件、网络、时间、随机性、异步工作、并发、重试或间歇性失败，请阅读 references/reliable-test-design.md。

• 在自己负责的边界控制时间和随机性。
• 等待可观察条件，而不是猜测等待时长后休眠。
• 隔离可变状态，并确保即使测试失败也会清理。
• 模拟外部所有权边界，而非正在测试的内部协作。
• 找出并记录尚未解决的原因前，绝不要通过重试、延长超时或跳过执行来掩盖不稳定的测试。

按需执行

先运行受影响范围最小的测试，然后根据仓库惯例和变更风险运行相关测试套件、类型检查、lint 或构建检查。未经明确授权且未获准使用相应环境，不要运行破坏性集成测试、生产流量实验或会修改共享外部系统的测试。

报告：

• 覆盖的行为和风险；
• 测试层级及其可信的原因；
• 执行的命令和观察到的结果；
• 变更前已存在或仍未解决的失败；
• 未测试的重要环境或条件。

有针对性地组合技能

• 当测试是更广泛变更集审查中的一个风险领域时，使用 superior-code-review。
• 当失败的测试表明存在未知的生产环境或环境原因，而非测试设计问题时，使用 superior-debugging。
• 当迁移、真实引擎集成、事务或数据兼容性契约决定被测行为时，使用 superior-database。
• 当基准测试方法、性能预算、容量检查或回归阈值是重点时，使用 superior-performance。
• 当受控故障、降级、恢复、故障转移或还原测试是重点时，使用 superior-reliability。
• 当流水线和发布验证负责测试环境或质量门禁时，使用 superior-delivery。
• 当测试伴随业务规则、状态转换、持久化或 API 行为的变更时，使用 superior-logic。
• 对由威胁驱动的负面用例和安全控制验证，使用 superior-api-security。
• 当断言的行为由相应的界面关注点负责时，使用 superior-accessibility、superior-responsive 或 superior-ui。
• 仅当测试策略、验证流程或交付的实现会改变项目的长期知识时，才使用 superior-docs。

不要将范围明确的测试请求扩大为无关的生产代码重构或全面重写测试套件。