| name | testing-best-practices |
| description | Steward persistent tests by choosing the right layer, admission standard, durability, fake-red safeguards, and cleanup. Use when adding, changing, deleting, reviewing, or relying on persistent tests, or when deciding whether a test is the right proof layer. Use this skill for persistent-test quality only; it does not own final proof selection or runtime evidence mechanics. |
Testing Best Practices
Owns persistent-test admission, cleanup, layer choice, test strength, and
meaningful persistent red evidence.
Does not own delivery claims, final scope, proof selection, browser mechanics,
or mobile mechanics. Use ../solution-shaping/SKILL.md for final shape and
../verify-work/SKILL.md for proof selection.
Non-Negotiables
Persistent tests protect durable boundaries, not ceremony.
Rules:
- this skill is mandatory whenever persistent tests are added, changed,
deleted, reviewed, or used as proof
- choose the cheapest honest persistent layer
- assert public behavior or a narrow durable contract
- assert current positive behavior or structure; negative assertions are valid
only for current closed sets, schemas, manifests, or public API contracts
- require changed durable boundary plus named weaker implementation
- delete, shrink, or rewrite bad touched tests
- never fake red evidence
- never replace required live-use proof with persistent tests
- prefer vertical red-green slices when changing behavior: one behavior test,
minimal implementation, then next behavior
- avoid horizontal batches that write many tests or specs before the first
behavior path is validated
- for migration/runtime failures, prefer the real failed path or faithful
integration/smoke proof before mocked persistent tests
- e2e tests are written by implementers when an approved task owns them; they
support verification only when they exercise the same claim through a
faithful entrypoint and leave inspectable artifacts
Reference Gates
Read references/persistent-test-contract.md when adding, editing, deleting,
reviewing, or deciding whether to keep a persistent test.
Changed-Test Loop
For each changed persistent test file:
- Name regression it should catch.
- Pick cheapest reliable layer.
- Emit one row:
<path>: <keep|shrink|rewrite|delete> [reason-codes|none].
- If the changed cluster is too big for the slice, schedule follow-up now.
Corpus Cleanup
Use only when the work owns a broader persistent-test suite slice, not for
ordinary touched-test edits.
For corpus cleanup, inventory suspicious clusters, take one coherent tranche,
assign keep | shrink | rewrite | delete, finish it, then refresh inventory.
Do not hide repo-wide ballast behind "untouched files" once cleanup is the
owned work.
When cleanup spans product areas but the real problem is test quality, keep
follow-up owned by testing cleanup instead of scattering it across product
queues.
Suspicious by default: giant mixed-purpose suites, status/presence/snapshot
clusters, heavy mocks/waits with thin assertions, runner-heavy low-layer tests,
and expensive tests without explicit retained contract.
Delete redundant expensive tests before optimizing them. Move behavior downward
before speeding up the wrong layer.
Helper:
scripts/test_suite_audit.py: inventory and score suspicious test files and
clusters before a corpus-wide cleanup tranche. It is an audit aid, not proof
that a test should be kept or deleted.
Output
One line per changed persistent test file:
<path>: <keep|shrink|rewrite|delete> [reason-codes|none]
