| name | test-driven-development |
| description | Use when implementing new features or logic that requires tests — before writing implementation code. Covers Red-Green-Refactor cycle, stack-specific test patterns, test naming conventions, and mocking. Triggers: "write tests first", "TDD", "test-driven", "failing test", "red-green-refactor", "how do I test X". |
Test-Driven Development
Iron Law
NO IMPLEMENTATION WITHOUT A FAILING TEST FIRST
Write the test. Run it. See it fail (RED). Then implement until it passes (GREEN). Then refactor.
When TDD Applies
DO use TDD for:
- New features and new logic
- Bug fixes (write a test that reproduces the bug first)
- Any code path that has business logic
DO NOT use TDD for:
- Config changes, renames, formatting
- Trivial one-line fixes with no logic
- See
leverage-patterns.md Test-First section for the full rule
Red-Green-Refactor Cycle
RED -> Write a test that FAILS for the right reason
Run it. Confirm it fails. If it passes without code -> test is wrong.
GREEN -> Write the MINIMUM code to make the test pass
No extras. No "while I'm here" additions.
REFACTOR -> Clean up code without changing behavior
Run tests again. Must still pass.
For verifying regression tests are genuine (not vacuous): see verification-before-completion Red-Green protocol.
For TDD during bug investigation: see systematic-debugging Phase 4 — Create Failing Test Case.
Test Naming Convention
Pattern: test_<what>_<when>_<expected> (or should_<expected>_when_<condition>)
# Java
@Test void createUser_withDuplicateEmail_throwsConflictException()
# NestJS/Jest
it('should throw ConflictException when email already exists', ...)
# Python/pytest
def test_create_user_with_duplicate_email_raises_conflict():
# Flutter
test('createUser throws ConflictException when email is duplicate', ...)
Stack Dispatch
| Stack | Reference File | Load When |
|---|
| Java 21 / Spring Boot WebFlux | references/tdd-patterns-java.md | Writing tests for Spring Boot, WebFlux, reactive Java |
| NestJS 11 / TypeScript | references/tdd-patterns-nestjs.md | Writing tests for NestJS, TypeScript, Fastify |
| Python 3.14 / FastAPI | references/tdd-patterns-python.md | Writing tests for FastAPI, Pydantic, async Python |
| Flutter / Dart | references/tdd-patterns-flutter.md | Writing tests for Flutter widgets, Riverpod providers, Dart |
Quick Checklist
Before claiming a test is real:
