Test-Driven Development (TDD)
TDD is a red → green cycle. This skill is a reference for making this cycle produce tests worth keeping: what a good test is, where to place tests, what anti-patterns exist, and what the rules of the cycle are. Each section applies in every cycle—consult them before and during the cycle, not after.
When exploring the codebase, read
(if it exists), align test names and interface vocabulary with the project's domain language, and respect the ADRs of the area you're touching.
What Makes a Good Test
Tests validate behavior through public interfaces, not implementation details. Code can change completely; tests should not. A good test reads like a specification—"Users can check out with a valid cart" tells you exactly what capability exists—and because it doesn't care about internal structure, it survives refactoring.
See tests.md for examples, and mocking.md for the mocking guide.
Seams – Where to Place Tests
Seams are the public boundaries where your tests live: interfaces where you can observe behavior without reaching into the internals. Tests live at seams, never against internals.
Only test at pre-agreed seams. Before writing any test, write down the seam to test and confirm with the user. No tests are written on unconfirmed seams. You can't test everything—agreeing on seams upfront is the way to focus testing effort on critical paths and complex logic, not every edge case.
Ask: "What are the public interfaces, and which seams should we test?"
When the shape of interfaces is in question—how deep modules should be, where seams should be, what interfaces should expose—use the
skill to get vocabulary. It is the shared source for terms like module, interface, depth, seam, adapter, leverage, locality, a reference to consult, not a session to run.
Anti-Patterns
- Implementation-coupled — Mock internal collaborators, test private methods, or validate through bypass channels (check the database instead of using the interface). Identification signal: Tests fail during refactoring even though behavior hasn't changed.
- Tautological — Assertions recalculate expected values in the same way as the code (
expect(add(a, b)).toBe(a + b)
- Horizontal slicing — Write all tests first, then all implementations. Batches of tests validate imagined behavior: you're testing the shape of things instead of user-facing behavior, tests become insensitive to real changes, and you lock in test structure before understanding the implementation. Instead, use vertical slicing—one test → one implementation → repeat, where each test is a tracer bullet that responds to what the previous cycle taught you.
Rules of the Cycle
- Red before green. Write a test that fails first, then write only the code exactly needed to pass it. Don't anticipate future tests, and don't add speculative features.
- One slice at a time. One seam, one test, one minimal implementation per cycle.
- Refactoring is not part of the cycle. It belongs to the review phase (see the skill), not the red → green implementation cycle.