Test-Driven Development

TDD is a sequence of small red → green → refactor cycles. Each cycle must make the intended behavior executable, demonstrate that the check fails for the intended reason, and leave the affected path in a production-quality shape. The resulting tests must be worth keeping.

When exploring the codebase, read CONTEXT.md (if it exists) so test names and interface vocabulary match the project's domain language, and respect ADRs in the area you're touching.

What a good test is

Tests protect a meaningful contract through an interface or observation that can detect a realistic regression. Prefer tests that survive implementation-only refactors of that contract. A test such as "user can checkout with valid cart" explains the capability it protects; changing the contract itself may legitimately require changing its tests.

See tests.md for examples and mocking.md for mocking guidelines.

Seams: where tests go

A seam is a boundary where a test exercises behavior or controls a dependency. It may be a public API or an internal interface owned by a module. An internal module can have its own contract and meaningful tests without exposing that interface to application callers. Do not bypass encapsulation merely to assert on incidental private state.

Before writing a test, name the contract and the realistic failure it should catch, then choose the seam that owns that behavior. Prefer an established interface and nearby testing conventions. Use an internal seam when it provides distinct signal for a meaningful invariant or complex behavior; do not expose internals or introduce a new abstraction solely to satisfy test mechanics. Ask only when the seam choice would materially change scope or a contract.

Testing effort should land on critical paths and complex logic rather than every edge case.