---
name: test-driven-development
description: Use when building new features, refactoring existing modules, or fixing bugs using Test-Driven Development (TDD: Red-Green-Refactor cycle).
---

# Test-Driven Development (TDD)

## Purpose
Build robust, well-designed, and thoroughly tested software by writing automated tests *before* writing production code.

## The Red-Green-Refactor Cycle

### 1. 🔴 RED — Write a Failing Test
- Define the desired behavior from the caller's perspective.
- Write a focused test asserting that behavior.
- **Run the test** and verify that it fails for the *expected* reason (e.g. missing method or assertion mismatch, not a syntax/import error).

### 2. 🟢 GREEN — Write the Minimal Implementation
- Write just enough code to make the failing test pass.
- Resist the temptation to implement speculative future features or premature optimizations.
- **Run the test suite** and verify that all tests pass.

### 3. 🔵 REFACTOR — Clean Up & Optimize
- Eliminate duplication and code smells.
- Improve naming, types, and module structure.
- Ensure all invariants hold while keeping the test suite green at all times.

## Best Testing Practices
- **Test Behavior, Not Implementation Details:** Avoid asserting private state or internal methods. Test through public interfaces.
- **Fast and Deterministic:** Unit tests should run in milliseconds without relying on real network calls or unstable timing delays.
- **AAA Pattern:** Arrange (setup data), Act (call function/method), Assert (check outcome and side-effects).