Test driven development

--- name: test-driven-development description: Drives development with tests. Use when implementing any logic, fixing any bug, or changing any behavior. Use when you need to prove that code works, when a bug report arrives, or when you're about to modify existing functionality. --- # Test-Driven Development ## Overview Write a failing test before writing the code that makes it pass. For bug fixes, reproduce the bug with a test before attempting a fix. Tests are proof : "seems right" is not done. A codebase with good tests is an AI agent's superpower; a codebase without tests is a liability. ## When to Use - Implementing any new logic or behavior - Fixing any bug (the Prove-It Pattern) - Modifying existing functionality - Adding edge case handling - Any change that could break existing behavior When NOT to use: Pure configuration changes, documentation updates, or static content changes that have no behavioral impact. Related: For browser-based changes, combine TDD with runtime verification using Chrome DevTools MCP : see the Browser Testing section below. ## The TDD Cycle `` RED GREEN REFACTOR Write a test Write minimal code Clean up the that fails ──→ to make it pass ──→ implementation ──→ (repeat) │ │ │ ▼ ▼ ▼ Test FAILS Test PASSES Tests still PASS ` ### Step 1: RED : Write a Failing Test Write the test first. It must fail. A test that passes immediately proves nothing. `typescript // RED: This test fails because createTask doesn't exist yet describe('TaskService', () => { it('creates a task with title and default status', async () => { const task = await taskService.createTask({ title: 'Buy groceries' }); expect(task.id).toBeDefined(); expect(task.title).toBe('Buy groceries'); expect(task.status).toBe('pending'); expect(task.createdAt).toBeInstanceOf(Date); }); }); ` ### Step 2: GREEN : Make It Pass Write the minimum code to make the test pass. Don't over-engineer: `typescript // GREEN: Minimal implementation export async function createTask(input: { title: string }): Promise<Task> { const task = { id: generateId(), title: input.title, status: 'pending' as const, createdAt: new Date(), }; await db.tasks.insert(task); return task; } ` ### Step 3: REFACTOR : Clean Up With tests green, improve the code without changing behavior: - Extract shared logic - Improve naming - Remove duplication - Optimize if necessary Run tests after every refactor step to confirm nothing broke. ## The Prove-It Pattern (Bug Fixes) When a bug is reported, **do not start by trying to fix it.** Start by writing a test that reproduces it. ` Bug report arrives │ ▼ Write a test that demonstrates the bug │ ▼ Test FAILS (confirming the bug exists) │ ▼ Implement the fix │ ▼ Test PASSES (proving the fix works) │ ▼ Run full test suite (no regressions) ` **Example:** `typescript // Bug: "Completing a task doesn't update the completedAt timestamp" // Step 1: Write the reproduction test (it should FAIL) it('sets completedAt when task is completed', async () => { const task = await taskService.createTask({ title: 'Test' }); const completed = await taskService.completeTask(task.id); expect(completed.status).toBe('completed'); expect(completed.completedAt).toBeInstanceOf(Date); // This fails → bug confirmed }); // Step 2: Fix the bug export async function completeTask(id: string): Promise<Task> { return db.tasks.update(id, { status: 'completed', completedAt: new Date(), // This was missing }); } // Step 3: Test passes → bug fixed, regression guarded ` ## The Test Pyramid Invest testing effort according to the pyramid : most tests should be small and fast, with progressively fewer tests at higher levels: ` ╱╲ ╱ ╲ E2E Tests (~5%) ╱ ╲ Full user flows, real browser ╱──────╲ ╱ ╲ Integration Tests (~15%) ╱ ╲ Component interactions, API boundaries ╱────────────╲ ╱ ╲ Unit Tests (~80%) ╱ ╲ Pure logic, isolated, milliseconds each ╱──────────────────╲ `` The Beyonce Rule: If you liked it, you should have put a test on it. Infrastructure changes, refactoring, and migrations are not responsible for catching your bugs : your tests are. If a change breaks your code and you didn't have a test for it, that's on you. ### Test Sizes (Resource Model) Beyond the pyramid levels, classify tests by what resources they consume: | Size | Constraints | Speed | Example | |------|------------|-------|---------| | Small | Single process, no I/O, no network, no database | Milliseconds | Pure function tests, data transforms | | Medium | Multi-process OK, localhost only, no external