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.

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.