TDD Best Practices

Test-Driven Development with behavior-focused testing, factory patterns, and the Red-Green-Refactor cycle.

Core Principle

Every single line of production code must be written in response to a failing test.

This is non-negotiable. If you're typing production code without a failing test demanding it, you're not doing TDD.

The Sacred Cycle: Red → Green → Refactor

1. RED - Write a Failing Test

Write a test that describes the desired behavior. The test must fail because the behavior doesn't exist yet.

Rules:

• •Start with the simplest behavior
• •Test ONE thing at a time
• •Focus on business behavior, not implementation
• •Use descriptive test names that document intent
• •Use factory functions for test data

2. GREEN - Minimal Implementation

Write the minimum code to make the test pass. Nothing more.

Rules:

• •Only enough code to pass the current test
• •Resist "just in case" logic
• •No speculative features
• •If writing more than needed, STOP and question why

3. REFACTOR - Assess and Improve

With tests green, assess whether refactoring would add value.

Rules:

• •Commit working code FIRST
• •External APIs stay unchanged
• •All tests must still pass
• •Commit refactoring separately
• •Not all code needs refactoring - if clean, move on

Quick Reference

When to Use Each Guide

Workflow Examples

Use workflow-examples.md when you need:

• •Complete TDD workflow examples (free shipping, payment validation)
• •Step-by-step RED-GREEN-REFACTOR cycles
• •When to refactor vs when to move on
• •Refactoring assessment criteria
• •Refactoring rules (commit first, preserve API, etc.)

Test Factories

Use test-factories.md when you need:

• •Factory function patterns with overrides
• •Why factories beat let/beforeEach
• •Composing factories for complex data
• •Test organization by behavior
• •No 1:1 mapping between tests and implementation
• •Achieving 100% coverage through behavior testing

Violations

Use violations.md when you need:

• •Critical violations reference (production code without test, etc.)
• •High priority issues (let/beforeEach, testing privates, etc.)
• •Style issues (large files, duplication, magic values)
• •Behavior vs implementation examples
• •Quality gates checklist

Patterns

Use patterns.md when you need:

• •Behavior-focused testing examples
• •Testing through public APIs only
• •Factory patterns with schema validation
• •Composing factories for complex data
• •Descriptive test naming patterns
• •Test organization by business behavior

Quick Reference: Decision Trees

Should I write this code?

Is there a failing test demanding this code?
├── Yes → Write minimal code to pass
└── No → Write the failing test first

Is my test good?

Does the test verify a business outcome?
├── Yes → Does it use the public API only?
│   ├── Yes → Does it use factory functions?
│   │   ├── Yes → Good test ✓
│   │   └── No → Refactor to use factories
│   └── No → Rewrite to avoid internals
└── No → Rewrite to focus on behavior

Should I refactor?

Are all tests green?
├── Yes → Is the code already clean?
│   ├── Yes → Commit and move on
│   └── No → Commit first, then refactor
└── No → Make tests pass first

How much code should I write?

Does this code make the current failing test pass?
├── Yes → Is there any code that could be removed
│         and tests still pass?
│   ├── Yes → Remove it
│   └── No → Done, commit
└── No → Keep writing minimal code

Summary Checklist

Before committing, verify:

• • All production code has a test that demanded it
• • Tests verify behavior, not implementation
• • Implementation is minimal (only what's needed)
• • Refactoring assessment completed
• • All tests pass
• • Factory functions used (no let/beforeEach)
• • Test names describe business behavior
• • Edge cases covered
• • Tests use public API only
• • No testing of implementation details
• • Test organization reflects business features
• • 100% coverage achieved through behavior testing