Test-Driven Development
Philosophy
Core principle: Tests verify behavior through public interfaces, not implementation details. Code can change entirely; tests should not.
Good tests are integration-style: they exercise real code paths through public APIs. They describe what the system does, not how. A good test reads like a specification. These tests survive refactors because they don't depend on internal structure.
Bad tests are coupled to implementation. They mock internal collaborators, test private methods, or verify through external means. Warning sign: your test breaks when you refactor, but behavior hasn't changed.
See reference/tests.md for examples and reference/mocking.md for mocking guidelines.
Framework Agnostic
This skill works with any test framework (Vitest, Jest, Playwright, Cypress, pytest, JUnit, etc.) and any stack (Vue.js, React, Node.js, backend services). Adapt examples to the project's language and framework.
Anti-Pattern: Horizontal Slices
DO NOT write all tests first, then all implementation. This is "horizontal slicing" — treating RED as "write all tests" and GREEN as "write all code."
This produces poor tests: they test imagined behavior, test the shape of things rather than user-facing behavior, and become insensitive to real changes.
Correct approach: Vertical slices via tracer bullets. One test, one implementation, repeat.
WRONG (horizontal):
RED: test1, test2, test3, test4, test5
GREEN: impl1, impl2, impl3, impl4, impl5
RIGHT (vertical):
RED→GREEN: test1→impl1
RED→GREEN: test2→impl2
RED→GREEN: test3→impl3
Workflow
1. Planning
Before writing any code:
Ask: "What should the public interface look like? Which behaviors are most important to test?"
2. Tracer Bullet
Write ONE test that confirms ONE thing — proves the path works end-to-end:
RED: Write test for first behavior → test fails
GREEN: Write minimal code to pass → test passes
3. Incremental Loop
For each remaining behavior:
, one test at a time.
- Only enough code to pass the current test
- Don't anticipate future tests
- Keep tests focused on observable behavior
4. Refactor
After all tests pass, look for refactor candidates:
Never refactor while RED. Get to GREEN first.
Checklist Per Cycle
[ ] Test describes behavior, not implementation
[ ] Test uses public interface only
[ ] Test would survive an internal refactor
[ ] Code is minimal for this test
[ ] No speculative features added