Overview
Testing Doctrine loads one conviction into your agent: a test suite exists to let you change code with confidence, so every test is judged by the promise it protects — behavior through a public contract, never implementation detail. The core file carries fifteen non-negotiables and two decision frameworks (which level catches this failure, and to-mock-or-not); eight reference files go deep on test strategy and coverage policy, unit tests that survive refactors, mocking discipline, integration and API testing, Playwright end-to-end, UI component testing, the flaky-test playbook, and TDD workflow with CI pipeline shape — loaded only when the task needs them.
What it grants
- 01Fits the codebase first: detects the runner and conventions, extends what exists, never introduces a parallel stack
- 02Level-selection doctrine: start from the failure you fear, pick the lowest level that catches it honestly — integration as the workhorse
- 03The mocking ladder: real thing > hand-written fake > MSW at the wire > vi.mock as last resort — and never mock what you own
- 04Unit tests as executable spec: behavior names, builders over fixtures, table-driven cases, snapshot discipline
- 05API testing through the front door: app factories, real test databases via containers, tenant-scoping security tests
- 06Playwright doctrine: role-first locators, auto-waiting over sleeps, auth state reuse, data setup via API not UI
- 07The flaky-test playbook: eight root-cause families, quarantine policy, retries as telemetry never treatment
- 08Coverage as flashlight not target — plus mutation testing where honesty matters
- 09TDD where it pays, reproduce-first on every bug fix, and the cheapest-first CI ladder with sharding
Try it like this
agent> Audit this test file the testing-doctrine way — find the implementation coupling, fix the mocking, and make every name read as a spec.