superior-testing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Superior Testing

Make tests provide durable evidence about behavior and risk. Fit the suite to the repository's existing tools and architecture; do not impose a generic test pyramid, framework, or coverage target.

让测试成为有关行为和风险的可靠、持久证据。根据代码仓库现有的工具与架构适配测试套件；不要强加通用测试金字塔、测试框架或覆盖率目标。

Establish the contract

确定契约

Before writing a test, identify:

the observable behavior or invariant being protected;
the failure or regression the test must distinguish;
the public boundary where the behavior can be observed;
dependencies, state, time, concurrency, and external systems involved;
existing test conventions, helpers, fixtures, and CI constraints.

For a reported bug, reproduce the failure before changing the implementation when practical. Confirm that the test fails for the intended reason rather than because the fixture, environment, or assertion is broken.

在编写测试前，先确定：

要保护的可观察行为或不变量（invariant）；
测试必须能够区分的故障或回归；
可以观察该行为的公共边界；
涉及的依赖项、状态、时间、并发和外部系统；
现有的测试约定、helpers、fixtures 和 CI 约束。

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

Choose the narrowest credible test

选择范围最窄且可信的测试

Read references/test-strategy-and-levels.md when selecting among unit, component, integration, contract, end-to-end, property-based, or migration tests, or when a change needs coverage at more than one layer.

Prefer the least expensive test that exercises the real owner of the risk:

pure rules at a stable callable boundary;
integration tests for persistence, serialization, framework wiring, or service boundaries;
contract tests for independently changing producers and consumers;
end-to-end tests for a small number of critical journeys whose wiring is itself the risk.

Do not repeat the same assertion at every layer. Add another layer only when it proves a distinct failure mode.

在 unit、component、integration、contract、end-to-end、property-based 或 migration 测试之间进行选择，或变更需要在多个层级覆盖时，阅读 references/test-strategy-and-levels.md。

优先选择成本最低、且能真正覆盖风险归属层的测试：

纯规则：在稳定且可调用的边界上进行验证；
integration 测试：用于持久化、序列化、框架接线或服务边界；
contract 测试：用于独立变更的生产者和消费者；
end-to-end 测试：用于少量关键流程，且流程接线本身构成风险。

不要在每一层重复相同断言。只有当新增层级能够证明一种不同的 failure mode 时，才添加该层级。

Design for signal

围绕有效信号进行设计

Assert observable outcomes, state transitions, emitted effects, or stable contracts rather than private method calls.
Use representative boundary cases and invalid inputs derived from the contract, not arbitrary permutations.
Keep each failure diagnostic enough to identify the broken contract.
Keep snapshots small and intentional; review semantic changes instead of accepting broad snapshot churn.
Treat line coverage as a discovery signal, not proof of correctness.
Preserve established naming and structure unless they prevent the test from expressing its purpose.

Production code may receive a small testability seam when the requested scope permits it and the seam improves the real design. Do not expose private internals, add dependency injection machinery, or alter behavior solely to satisfy a test harness.

断言可观察结果、状态转换、产生的副作用或稳定契约，而不是私有方法调用。
使用源自契约、具有代表性的边界用例和无效输入，而不是任意排列组合。
确保每次失败都提供足够的诊断信息，以识别被破坏的契约。
保持 snapshots 精简且目的明确；审查语义变更，不要接受大范围的 snapshot churn。
将 line coverage 视为发现信号，而非正确性的证明。
保留既有命名和结构，除非它们妨碍测试表达其目的。

如果请求范围允许，且 testability seam 能够改进实际设计，生产代码可以接受小幅的可测试性调整。不要暴露私有内部实现、引入 dependency injection 机制，或仅为迎合 test harness 而改变行为。

Keep execution reliable

保证执行可靠性

Read references/reliable-test-design.md when tests involve shared fixtures, databases, files, networks, time, randomness, asynchronous work, concurrency, retries, or intermittent failures.

Control time and randomness at an owned boundary.
Wait for observable conditions instead of sleeping for guessed durations.
Isolate mutable state and clean it up even after failure.
Mock external ownership boundaries, not the internal collaboration being tested.
Never hide a flaky test with retries, larger timeouts, or skipped execution without identifying and recording the unresolved cause.

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

在测试自身控制的边界管理时间和随机性。
等待可观察条件，而不是按照猜测的时长 sleep。
隔离可变状态，即使测试失败也要完成清理。
对外部 ownership boundary 进行 mock，而不是 mock 被测的内部协作。
绝不能用 retries、更大的 timeout 或跳过执行来掩盖 flaky test，除非已经识别并记录尚未解决的原因。

Execute proportionately

按变更范围和风险适度执行

Run the narrowest affected test first, then the relevant suite, type checks, lint, or build checks according to repository practice and change risk. Do not run destructive integration tests, production traffic experiments, or tests that mutate shared external systems without explicit authorization and an approved environment.

Report:

the behavior and risk covered;
test level and why it is credible;
commands run and observed results;
failures that predated the change or remain unresolved;
important environments or conditions not exercised.

先运行受影响范围中最窄的测试，然后根据代码仓库惯例和变更风险运行相关测试套件、类型检查、lint 或构建检查。

未经明确授权并使用经批准的环境，不要运行破坏性的 integration 测试、生产流量实验，或会修改共享外部系统的测试。

报告：

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

Combine skills narrowly

按需组合 skill

Use
```
superior-code-review
```
when tests are one risk area within a broader change-set review.
Use
```
superior-debugging
```
when a failing test is evidence of an unknown production or environment cause rather than a test-design problem.
Use
```
superior-database
```
when a migration, real-engine integration, transaction, or data-compatibility contract owns the behavior under test.
Use
```
superior-performance
```
when benchmark methodology, performance budgets, capacity checks, or regression thresholds are primary.
Use
```
superior-reliability
```
when controlled fault, degradation, recovery, failover, or restore testing is primary.
Use
```
superior-delivery
```
when pipeline and release verification owns the test environment or gate.
Use
```
superior-logic
```
when tests accompany changes to business rules, state transitions, persistence, or API behavior.
Use
```
superior-api-security
```
for threat-driven negative cases and security-control verification.
Use
```
superior-accessibility
```
,
```
superior-responsive
```
, or
```
superior-ui
```
when the asserted behavior is owned by those interface concerns.
Use
```
superior-docs
```
only when the test strategy, verification procedure, or delivered implementation changes durable project knowledge.

Do not broaden a focused test request into unrelated production refactoring or a full-suite rewrite.

当测试只是更广泛变更集审查中的一个风险领域时，使用
```
superior-code-review
```
。
当失败测试是未知生产或环境问题的证据，而非测试设计问题时，使用
```
superior-debugging
```
。
当 migration、真实引擎 integration、transaction 或数据兼容性契约主导被测行为时，使用
```
superior-database
```
。
当 benchmark 方法、性能预算、容量检查或回归阈值是重点时，使用
```
superior-performance
```
。
当受控故障、降级、恢复、failover 或 restore 测试是重点时，使用
```
superior-reliability
```
。
当 pipeline 和发布验证主导测试环境或 gate 时，使用
```
superior-delivery
```
。
当测试伴随业务规则、状态转换、持久化或 API 行为变更时，使用
```
superior-logic
```
。
对于威胁驱动的负面用例和安全控制验证，使用
```
superior-api-security
```
。
当断言的行为由可访问性、响应式或 UI 关注点主导时，使用
```
superior-accessibility
```
、
```
superior-responsive
```
或
```
superior-ui
```
。
仅当测试策略、验证流程或交付的实现变更了项目的持久知识时，使用
```
superior-docs
```
。

不要将聚焦的测试请求扩展为无关的生产代码重构或全量测试套件重写。