Test-Driven Development

Run this as the implementer.

No production behaviour ships untested. Two tiers - project instructions decide which layers fall where; if they are silent, use these:

• Strict test-first - where the test is the contract other code relies on: a public API or endpoint, a domain operation with declared inputs, outputs, and errors, a published library surface. Write the failing test before the code exists.
• Test-required, order-flexible - everything else: helpers, view components, adapters, serialisers, end-to-end tests. The behaviour must end up tested; the order is yours.

The cycle

One behaviour at a time:

1. Red - write the smallest test for the behaviour.
2. Watch it fail for the missing behaviour, not for a typo or load error.
3. Green - write the least code that passes. Nothing speculative.
4. Watch it pass - run only the focused test.
5. Refactor while green.

Code written before its test, on a strict layer, is test-after. Delete it and rebuild it from a failing test.

Checks: focused as you go, full once at the end

Run focused tests during the cycle - only what you need to see red and green. When the unit's work is done, run the unit's full spec and lint commands once and record the output in your report. If that run fails, fix and run it once more. Reviewers do not run checks; your final run is the evidence.

What good tests do

• Assert observable behaviour - return values, errors, persisted rows, emitted events, enqueued work - not internals.
• Cover every happy path and every failure path, including the error contract.
• Use real collaborators where practical. Mock only real boundaries.
• Stub network calls, including timeout, error status, and malformed body.
• Stay deterministic and independent of order.

User-facing units: prove the journey

1. Wire the entry point - the nav item, link, or control that gets a user to the feature.
2. Write an end-to-end test that starts where a user lands and navigates through the interface. Do not jump to the deep URL.
3. Assert the visible outcome.

A user-facing unit is not done until this test passes.

Existing untested code

When you change untested behaviour that must be kept, write a characterisation test first. For a defect, the first test reproduces the root cause found by systematic-debugging.

Exceptions

Only the user can approve skipping the red step, for one specific behaviour where a failing test cannot be observed. Ask with the behaviour, the reason, the substitute check, and the risk. Record the approval and its scope in PROGRESS.md. It does not extend to other behaviour.

Done when

Every behaviour is tested (red observed where strict), the full specs and lint passed in one final run recorded in the report, and - for a user-facing unit - the journey test passed. A unit with no production behaviour is exempt only when the diff proves it.