testing git:20261105.e0d5bb2A

Immutable. This exact content never changes and is served at /api/v1/blob/985699cbcfcd6b31.

---
name: testing
description: Selects and runs behavior checks, implements red-green tests, and verifies regressions. Use before writing or running any tests, when the user asks for tests, coverage, TDD, a failing test, or proof that a change works, with pytest, PHPUnit, unittest, node --test, go test, cargo test, vitest, or jest. Excludes benchmarking and standalone security audits.
---

1. Recover the requested behavior, defect evidence, affected callers, dependencies, and contracts before editing. Read project instructions, nearby tests, test configuration, manifests, lockfiles, and relevant CI commands. Read the local glossary and applicable ADRs when present. Identify the public boundary at which a wrong result is observable and what that boundary cannot prove.
2. Select the smallest check that can detect a plausible violation of each changed behavior. Reuse existing coverage before adding tests. Choose by the following rules, combining levels only when they observe different risks.

   - Use a unit test for deterministic local rules and transformations.
   - Use an integration test when correctness depends on real collaborating modules, persistence, serialization, or resource lifecycle.
   - Use a contract test for request, response, error, event, or compatibility guarantees at a producer-consumer boundary. A stub alone does not prove the producer honors it.
   - Use a property test for a documented invariant across a meaningful input domain. Read [property-based.md](references/property-based.md) when designing generators, reviewing properties, or triaging a counterexample.
   - Use an e2e test when the claimed result depends on the complete user workflow across real application boundaries. A unit test cannot establish that the assembled workflow works.
   - Use a smoke test to check startup and a critical operation in the named environment after an authorized build or release. Do not infer release success from local tests or perform a deployment just to obtain evidence.
   - Use inspection for non-executable text or configuration facts. Syntax, lint, types, compilation, and coverage are complementary checks, not evidence that runtime behavior works.

3. Prepare the declared environment with its installed runtime and runner versions. If declared dependencies are missing, install them using the project's package manager and lockfile within the existing authorization. Do not silently skip installation, upgrade dependencies, introduce a second runner, use a system-wide installer, or download a tool implicitly. If installation fails or is prohibited, record the attempted command and blocker and continue independent checks. Adding a new property-testing dependency requires the user's decision unless already authorized.
4. For a feature, write one focused test for the next requested observable behavior before implementation. For a bug, first reproduce the reported failure through the actual caller's inputs and lifecycle, then encode it as a regression test before fixing it. Run the selected test against the unchanged implementation. Inspect the failure and establish that it exposes the missing or incorrect behavior. Import errors, missing fixtures, invalid setup, zero selected tests, and unrelated crashes are not a valid red step. If an API is absent, add only the smallest contract-shaped stub needed to reach the intended failing assertion.
5. If the test already passes, check selection and whether it reaches the affected path. Correct the reproduction or identify existing coverage instead of forcing a failure. If changes already exist, use a safe isolated baseline only when permitted. Never reset or overwrite the user's worktree. State when a pre-fix failure could not be observed and why. Do not label a test written after implementation as test-first.
6. Implement only enough to pass that test. Run the same test and inspect its result. Repeat one behavior at a time. Refactor only while green, within scope, and rerun affected tests after any refactor. Do not weaken assertions, update snapshots blindly, or suppress failures to make the implementation pass.
7. Keep roughly one focused permanent test per stated behavior, sized like neighboring tests. Several assertions may establish one outcome. Use parameterization for input variants of that outcome and separate tests for distinct contracts. This is not a one-test quota for a whole feature. Avoid duplicate tests and large speculative matrices. Read [test-smells.md](references/test-smells.md) when adding or reviewing tests, especially mocks and asynchronous assertions.
8. Execute the selected regression checks against the final changed state. Read [regression-checks.md](references/regression-checks.md) for runner commands, evidence requirements, and the completion gate. Include affected existing consumers and relevant rejection, boundary, cancellation, concurrency, or data-compatibility paths when changed. Fix regressions introduced by this task. Preserve unrelated work and report pre-existing failures without fixing them just to obtain green output.
9. Before claiming a result, match it to the actual command, working directory, selected target, completed output, exit status, and executed test evidence. Wait for running checks to finish. A cached summary, a command that failed to start, a dry run, collection-only output, all-skipped tests, or syntax-only success cannot establish behavior. Do not claim a suite passed from a partial run.
10. Inspect the complete final task diff, including staged and new files, for scope, generated artifacts, secrets, and temporary materials. Remove only verified task-owned scratch files and fixtures no longer in use. Do not leave temporary scripts in the repository. Keep permanent tests and intentional regression inputs. Once relevant checks pass, repeat or broaden only for a subsequent edit, failure, or specific unresolved risk.

Report the changed behavior and the validation that actually ran. Include the command and decisive observed result concisely, or refer to the retained tool output without pasting long logs. Separate failed checks from checks that never ran. For each unfinished requirement or necessary unrun check, state its concrete blocker and what remains unverified. Never report the whole task ready while required checks remain unresolved. If an earlier claim lacked execution evidence, correct it and run the missing authorized check before making another readiness claim.