Tdd

Purpose

Drive feature development and bug fixes through tight red-green-refactor cycles, one behavior at a time. Tests verify observable behavior through public interfaces so they survive internal refactors. Vertical slices (tracer bullets) replace the "write all tests, then all code" anti-pattern because tests written in bulk inevitably test imagined behavior — not actual behavior.

Philosophy

Tests verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't.

• 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 — "user can checkout with valid cart" tells you exactly what capability exists. These tests survive refactors because they don't care about internal structure.
• Bad tests are coupled to implementation. They mock internal collaborators, test private methods, or verify through external means (querying a database directly instead of using the interface). The warning sign: your test breaks when you refactor, but behavior hasn't changed. If you rename an internal function and tests fail, those tests were testing implementation, not behavior.

Anti-pattern: horizontal slices. DO NOT write all tests first, then all implementation. That treats RED as "write all tests" and GREEN as "write all code." It produces crap tests because:

• Tests written in bulk test imagined behavior, not actual behavior
• You end up testing the shape of things (data structures, function signatures) rather than user-facing behavior
• Tests become insensitive to real changes — they pass when behavior breaks, fail when behavior is fine
• You outrun your headlights, committing to test structure before understanding the implementation

Correct approach: vertical slices via tracer bullets. One test → one implementation → repeat. Each test responds to what you learned from the previous cycle.

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. Plan with the user before writing any code

   • Explore the codebase. Use the project's domain glossary so test names and interface vocabulary match the project's language. Respect ADRs in the area you're touching.
   • Confirm with the user what interface changes are needed
   • Confirm with the user which behaviors to test, and prioritize them — you can't test everything, so focus on critical paths and complex logic, not every possible edge case
   • Identify opportunities for deep modules (small interface, deep implementation) — see ./references/deep-modules.md
   • Design interfaces for testability (accept dependencies, return results, small surface) — see ./references/interface-design.md
   • List behaviors to test (not implementation steps)
   • Get user approval on the plan before proceeding
   • Example: User asks to add a checkout flow → ask "What should the public checkout() interface look like? Which behaviors matter most — happy path, invalid cart, payment failure, partial refund?" Get explicit prioritization before any test is written.

2. Fire the tracer bullet

   • Write ONE test that confirms ONE thing about the system
   • RED: test fails (confirm it fails for the right reason — not a syntax error)
   • GREEN: write the minimum code to make it pass
   • This proves the path works end-to-end before you build more on top of it
   • Example:

     RED:   test("checkout with valid cart returns confirmed status") → fails (no checkout fn)
     GREEN: implement minimal checkout() returning { status: "confirmed" } → test passes
     

3. Loop one behavior at a time

   • For each remaining behavior, run RED → GREEN
   • Rules:
     • One test at a time
     • Only enough code to pass the current test
     • Do NOT anticipate future tests
     • Keep tests focused on observable behavior through the public interface
   • After each GREEN, run the per-cycle checklist:
     • 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
   • IF: the test breaks when you rename an internal function but behavior is unchanged → THEN the test is coupled to implementation; rewrite it against the public interface (see ./references/tests.md for good/bad examples)
   • IF: the behavior crosses a system boundary (external API, database, time, randomness, filesystem) → THEN mock at that boundary only — never mock internal collaborators (see ./references/mocking.md)
   • Example: Next behavior is "checkout with empty cart returns error" → write that test alone, watch it fail, add the minimal guard clause, watch it pass, then run the checklist.

4. Refactor only while GREEN

   • Never refactor while RED. Get to GREEN first.
   • After all tests for the current slice pass, look for refactor candidates: duplication, long methods, shallow modules, feature envy, primitive obsession, and existing code the new code reveals as problematic (see ./references/refactoring.md)
   • Apply changes:
     • Extract duplication
     • Deepen modules (move complexity behind simple interfaces)
     • Apply SOLID principles where natural
     • Consider what the new code reveals about existing code
   • Run tests after EACH refactor step. If anything goes red, undo or fix immediately before the next step.
   • Example: After three checkout tests are green you notice cart-total math repeated in two places → extract calculateTotal(cart), run tests, all green → continue.

5. Return to the loop or finish

   • IF: more prioritized behaviors remain → return to step 3
   • IF: all prioritized behaviors are covered and refactor pass is clean → summarize what was built, which behaviors are covered, and any deferred behaviors the user explicitly chose not to test
   • Example: "Checkout flow done. Covered: valid cart, empty cart, payment failure. Deferred per your call: partial refund (edge case, low priority)."

References

Good vs. bad tests, with examples

• IF: deciding whether a test is well-formed, debugging a test that breaks on refactor, or unsure what to assert
• THEN: Read ./references/tests.md
• EXAMPLES:
  • "is this test testing implementation or behavior?"
  • "my tests keep breaking when I rename things"
  • "what should I assert here?"

Mocking and system boundaries

• IF: about to mock something, designing an external integration, or wondering if a dependency should be injected
• THEN: Read ./references/mocking.md
• EXAMPLES:
  • "should I mock the database?"
  • "how do I test this Stripe integration?"
  • "this function is hard to mock — what do I change?"

Interface design for testability

• IF: designing a new function or module, or an existing one is painful to test
• THEN: Read ./references/interface-design.md
• EXAMPLES:
  • "this function takes too many params to test"
  • "how should I shape this API?"
  • "the test setup is enormous — what's wrong with the interface?"

Deep modules (small interface, deep implementation)

• IF: an interface feels too wide, too many methods, or wraps trivial logic
• THEN: Read ./references/deep-modules.md
• EXAMPLES:
  • "is this module too shallow?"
  • "should I split or combine these classes?"
  • "this wrapper does almost nothing — keep it?"

Refactor candidates after GREEN

• IF: all tests pass and you're entering the refactor step
• THEN: Read ./references/refactoring.md
• EXAMPLES:
  • "what should I refactor now that tests pass?"
  • "I see duplication — extract or leave?"
  • "the new code makes the old code look bad — what do I do?"

Works well with

Optional collaborators — tdd runs standalone and these degrade gracefully if absent.

• grill-with-docs (or grill-me) — align on scope, interface, and behaviors before the first test; grill-with-docs also records the ADRs tdd should respect.
• living-plan — its build workflow delegates the test-first implementation of each task to tdd, handing over the plan's behaviors as the approved design. tdd stays fully usable without it.
• diagnose — after a diagnosis pins a bug, lock the fix with a tdd regression test.
• setup-toolbox-context — provides the CONTEXT.md vocabulary tdd uses for test and interface names.