testing git:20260915.0c8f517A

Immutable. This exact content is served forever at /api/v1/blob/015b0c14cd0b5910.

---
name: testing
description: "Repository-aware test execution rules for TDD, observable proof, and boundary selection. Use when writing, reviewing, or fixing tests."
---

# Testing

## Reference

Read [references/typescript.md](references/typescript.md) only for TypeScript tests in web frontend work, including React, RTL, MSW, and Playwright tests. It does not apply to backend or non-web TypeScript tests.

## Governing Sources

Use test commands, thresholds, boundaries, fixtures, and conventions from the repository, task, Work Plan, Design Doc, or test skeleton. When these sources are silent, select the smallest repository-supported proof without introducing a new project-wide default.

## TDD Gate

Use RED-GREEN-REFACTOR for behavior-changing implementation when a focused automated test adds or restores necessary behavioral proof:

1. **RED**: Add or select a test that observes the required behavior. Run it and confirm it fails for the targeted missing behavior or regression.
2. **GREEN**: Make the smallest implementation change that satisfies the behavior. Run the focused test.
3. **REFACTOR**: Improve the changed code without changing the contract. Re-run the focused test.
4. **VERIFY**: Run the repository's required quality command and every wider check required by the task boundary.

For non-behavioral work or behavior already proven at the required boundary, use the smallest applicable verification instead of creating duplicate proof. Reuse existing evidence only while it remains valid for the changed behavior. Documentation, pure configuration, and disposable exploration do not require a RED phase. A productionized spike must gain tests before completion. Repository-required checks still apply.

## Proof Selection

- Test through the public or externally observable boundary named by the acceptance criterion or proof obligation.
- Keep a dependency real when that dependency is the boundary under proof; isolate external I/O only when the selected test level permits it.
- Use integration or E2E tests for persistence, process, browser, service, or cross-component claims that unit tests cannot observe.
- A broader test does not replace a required focused check, and a focused test does not prove a wider boundary.

## Capability Probe Postconditions

Evidence is substantive only when an executed assertion observes the exact consumer-visible postcondition.

- A helper result, mock call, source match, build success, or zero-test run does not prove behavior unless that is the named claim.
- Intentional absence is substantive when absence is the expected postcondition.
- State-changing behavior must assert relevant before → action → after state, including persistence or rollback semantics when applicable.
- For a changed route or alternate input path, exercise that path explicitly; evidence from another route is not interchangeable.

## Test Integrity

- Keep tests deterministic, isolated, and active.
- Use meaningful assertions on results, state, or observable effects.
- Preserve proof of user-required behavior and actual consumer contracts. When an authorized reduction removes an internal mechanism or unwanted behavior, remove or update its obsolete tests together with the affected design; tests do not make that mechanism mandatory. Verify the retained outcome and changed boundary rather than weakening assertions to hide a remaining defect.
- Use project-scoped setup and guaranteed cleanup for mutated state or external resources.
- Treat coverage as diagnostic unless a governing source defines a threshold.

## Completion Gate

- [ ] Focused tests pass; when the TDD Gate applies, RED failed for the targeted missing behavior or regression; otherwise RED is recorded as not applicable with the reason
- [ ] Required integration/E2E boundary is exercised
- [ ] Every cited behavior has a consumer-visible capability probe
- [ ] Repository-defined quality commands pass
- [ ] Required tests are active, substantive, isolated, and order-independent
- [ ] Mutated state and resources are restored