test-driven-development

Test-Driven Development

Write one failing test that describes the next behavior, write the minimal code to pass it, then refactor while green. Every production change starts with a test that proves the need exists. This is the discipline within each vertical slice — not framework syntax, but when and why to write tests.

Skip for exploratory prototyping, config-only changes (environment variables, feature flags), visual/CSS-only tweaks, and one-off scripts that won't be maintained.

Quick Reference — TDD Cycle

Phase	Action	Rule
RED	Write one test that fails for the right reason	No production code without a failing test
GREEN	Write the simplest code that makes the test pass	Resist the urge to generalize prematurely
REFACTOR	Improve structure while all tests stay green	Never change behavior and structure at once

Quick Reference — Principles

Principle	Practice
One test at a time	Complete the full red-green-refactor cycle before writing the next test
Behavior over implementation	Test what code does, not how it does it; assert outputs and side effects
Vertical slices	TDD one end-to-end behavior at a time, not one layer at a time
Mock at boundaries	Mock I/O, network, filesystem, clock. Never mock internal collaborators
Deep modules	Design small interfaces with rich internals; fewer tests cover more behavior
Refactor only when green	All tests pass before touching structure; refactoring under red hides new bugs
Design through tests	The first test IS the API design decision; awkward tests signal awkward interfaces
Failing test for every bug	Reproduce the bug as a failing test before writing the fix

Planning Before Coding

Step	Action	Output
1	Identify behaviors	List of observable behaviors the feature must exhibit
2	Order by dependency	Sequence where each test builds on prior passing tests
3	Design the interface	Function signatures, parameter types, return types
4	Identify mock boundaries	External dependencies that need test doubles

Common Mistakes

Mistake	Correct Pattern
Writing all tests first	One test at a time. Complete the cycle before starting the next
Testing private methods	Test through the public interface; private methods are implementation detail
Mocking internal collaborators	Only mock at I/O boundaries; trust your own code
Writing code before a failing test	RED first. The failing test proves the behavior is missing
Refactoring while tests are red	Get to GREEN first, then refactor with confidence
Tests coupled to call sequences	Assert on outputs and state, not on which internal methods were called
Skipping the refactor phase	GREEN is not done. Clean up duplication and naming before moving on
Hardcoding expected values	Use triangulation: add a second test case to force the general solution
One giant test per feature	One test per behavior — small, focused, independently meaningful

Delegation

• Slice decomposition: If the tracer-bullets skill is available, use it to decompose features into vertical slices before applying TDD within each slice
• Test framework syntax: Delegate framework-specific patterns to vitest-testing, e2e-testing, or api-testing skills
• Feature planning: If the plan-first-development skill is available, use it for upfront planning before entering the TDD cycle
• Individual TDD cycles: Delegate each red-green-refactor cycle to a Task subagent to keep context focused

References

• Test Quality — good vs bad tests, what to test, naming, triangulation, refactoring signals
• Mocking Boundaries — boundary rule, test doubles, dependency injection, anti-patterns
• Design for Testability — deep modules, interface-first design, pure functions, computation vs I/O