testing-conventions
Pins the contract in tests with absolute-instant fixtures and partial module mocks.
- Group
- Conventions
- Kind
- Read-only
- Loads when
- Writing or reviewing test files
When it runs
When test files are being written or reviewed. Claude loads it on its own when the description matches the file or the task; it never writes anything itself. It matches:
- *.test.*
- *.spec.*
- tests/
- e2e/
The conventions
- Pin the contract. A test pins the contract, not current behavior. If a test passes only after you fixed the test, check that you did not encode a bug: a red test may describe the correct contract.
- Absolute instants. A fixture pins an absolute instant, never a local-time literal. An ambient-timezone fixture hides a contract mismatch until CI runs in a different timezone from your machine.
- Partial mocks. Mock a module with a partial built on the original (for example Vitest's
importOriginal), never an exhaustive hand-written stub. A stub breaks the day the module gains an export, and one new export can break every suite that stubs it. - Red before the fix. A regression test must fail on the unfixed code: run it before the fix and see it red. A test only ever seen green may not exercise the bug at all.
- Real boundaries. Do not fake the boundary that could be wrong. A fake database that returns ready records hides a broken query; test that path against a real test database or the real call.
- Telling failures. A failure message names the missing record or shows the actual response. Never raise retries or timeouts to hide a flaky test; find the race instead.
2030-01-01T08:00:00ZRelated
- The qa-expert agent applies these rules to every test it writes or assesses.
- The tdd-enforcer output style: one failing test before any code.
- typescript-conventions asks for tests for every new function.