21 KiB
name, description
| name | description |
|---|---|
| engineering-test-driven-development | Test-Driven Development methodology, red-green-refactor cycle, unit testing best practices, and mocking strategies |
Test-Driven Development (TDD)
Scope: Comprehensive guide to TDD methodology, red-green-refactor cycle, unit testing, mocking, and test design Lines: ~380 Last Updated: 2025-10-27 Format Version: 1.0 (Atomic)
When to Use This Skill
Activate this skill when:
- Starting new features or projects from scratch
- Improving test coverage in existing code
- Designing highly testable code
- Establishing testing culture in a team
- Reducing bug rates through disciplined testing
- Clarifying requirements through test cases
- Refactoring with confidence
- Building critical business logic that must be correct
Core Concepts
Concept 1: The Red-Green-Refactor Cycle
The TDD Mantra: Red → Green → Refactor
1. RED: Write a failing test
↓
2. GREEN: Write minimal code to make it pass
↓
3. REFACTOR: Improve code without changing behavior
↓
4. REPEAT
Rules:
- Don't write production code without a failing test
- Don't write more test than sufficient to fail
- Don't write more production code than sufficient to pass
Example Cycle:
# RED: Write failing test
def test_add_two_numbers():
calculator = Calculator()
assert calculator.add(2, 3) == 5 # Fails - Calculator doesn't exist
# GREEN: Minimal code to pass
class Calculator:
def add(self, a, b):
return 5 # Hardcoded - but test passes!
# RED: Write another test
def test_add_different_numbers():
calculator = Calculator()
assert calculator.add(10, 20) == 30 # Fails with hardcoded 5
# GREEN: Real implementation
class Calculator:
def add(self, a, b):
return a + b # Now all tests pass
# REFACTOR: Clean up if needed (none needed here)
Concept 2: Test Structure (AAA Pattern)
Arrange-Act-Assert:
def test_user_login():
# Arrange: Set up test data
user = User(email="[email protected]", password="secret123")
user.save()
# Act: Execute the action being tested
result = authenticate(email="[email protected]", password="secret123")
# Assert: Verify the result
assert result.success is True
assert result.user.email == "[email protected]"
Given-When-Then (BDD style):
describe("User Login", () => {
it("should authenticate user with correct credentials", () => {
// Given: A registered user
const user = createUser({ email: "[email protected]", password: "secret" });
// When: User attempts to login
const result = authenticate("[email protected]", "secret");
// Then: Authentication succeeds
expect(result.success).toBe(true);
expect(result.user.email).toBe("[email protected]");
});
});
Concept 3: Test Doubles (Mocks, Stubs, Fakes)
Stub: Returns predefined data
class StubEmailService:
def send(self, to, subject, body):
return True # Always succeeds
Mock: Verifies interactions
mock_email = Mock()
service.send_welcome_email(user)
mock_email.send.assert_called_once_with(
to="[email protected]",
subject="Welcome!",
body="Welcome to our app!"
)
Fake: Working implementation (simplified)
class FakeDatabase:
def __init__(self):
self.data = {}
def save(self, key, value):
self.data[key] = value
def get(self, key):
return self.data.get(key)
Patterns
Pattern 1: Testing Pure Functions (Easiest)
Pure Function: Same inputs → Same outputs, no side effects
# RED: Write test first
def test_calculate_tax():
assert calculate_tax(100, 0.08) == 8.0
assert calculate_tax(50, 0.10) == 5.0
assert calculate_tax(0, 0.08) == 0.0
# GREEN: Implement
def calculate_tax(amount: float, rate: float) -> float:
return amount * rate
# REFACTOR: Add edge case tests
def test_calculate_tax_negative():
with pytest.raises(ValueError):
calculate_tax(-100, 0.08)
def calculate_tax(amount: float, rate: float) -> float:
if amount < 0:
raise ValueError("Amount cannot be negative")
return amount * rate
Pattern 2: Testing with Dependencies (Mocking)
Before TDD (hard to test):
class UserService:
def create_user(self, email):
db = PostgresDatabase() # Hard-coded dependency!
email_service = SendGridEmailService() # Another one!
user = db.save({"email": email})
email_service.send(user.email, "Welcome!")
return user
TDD Approach (test first drives design):
# RED: Write test with mocks
def test_create_user():
mock_db = Mock()
mock_email = Mock()
mock_db.save.return_value = User(id=1, email="[email protected]")
service = UserService(db=mock_db, email_service=mock_email)
user = service.create_user("[email protected]")
# Verify interactions
mock_db.save.assert_called_once_with({"email": "[email protected]"})
mock_email.send.assert_called_once_with("[email protected]", "Welcome!")
assert user.email == "[email protected]"
# GREEN: Implement with dependency injection
class UserService:
def __init__(self, db, email_service):
self.db = db
self.email_service = email_service
def create_user(self, email):
user = self.db.save({"email": email})
self.email_service.send(user.email, "Welcome!")
return user
TDD Forced Good Design: Dependency injection makes code testable!
Pattern 3: Table-Driven Tests (Go Style)
func TestCalculateDiscount(t *testing.T) {
tests := []struct {
name string
amount float64
userType string
want float64
}{
{"Premium user, large purchase", 1000, "premium", 200},
{"Premium user, small purchase", 50, "premium", 5},
{"Regular user, large purchase", 1000, "regular", 100},
{"Regular user, small purchase", 50, "regular", 0},
{"Guest user", 1000, "guest", 0},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
got := CalculateDiscount(tt.amount, tt.userType)
if got != tt.want {
t.Errorf("CalculateDiscount(%v, %v) = %v, want %v",
tt.amount, tt.userType, got, tt.want)
}
})
}
}
Pattern 4: Testing Async Code
Python (async/await):
import pytest
@pytest.mark.asyncio
async def test_fetch_user_data():
# Arrange
user_id = "123"
mock_api = AsyncMock()
mock_api.get_user.return_value = {"id": "123", "name": "John"}
service = UserService(api=mock_api)
# Act
user = await service.fetch_user_data(user_id)
# Assert
assert user["name"] == "John"
mock_api.get_user.assert_called_once_with(user_id)
TypeScript (Promises):
describe("fetchUserData", () => {
it("should fetch user from API", async () => {
// Arrange
const mockApi = {
getUser: jest.fn().mockResolvedValue({ id: "123", name: "John" }),
};
const service = new UserService(mockApi);
// Act
const user = await service.fetchUserData("123");
// Assert
expect(user.name).toBe("John");
expect(mockApi.getUser).toHaveBeenCalledWith("123");
});
});
Pattern 5: Testing Error Conditions
def test_divide_by_zero():
calculator = Calculator()
with pytest.raises(ZeroDivisionError):
calculator.divide(10, 0)
def test_invalid_email():
with pytest.raises(ValidationError) as exc_info:
create_user(email="invalid-email")
assert "Invalid email format" in str(exc_info.value)
def test_user_not_found():
result = find_user(user_id="nonexistent")
assert result is None # Or raises UserNotFoundError
Pattern 6: Parameterized Tests
Python (pytest):
@pytest.mark.parametrize("input,expected", [
("hello", "HELLO"),
("WORLD", "WORLD"),
("TeSt", "TEST"),
("", ""),
])
def test_uppercase(input, expected):
assert uppercase(input) == expected
TypeScript (Jest):
test.each([
[1, 1, 2],
[2, 2, 4],
[5, 3, 8],
])("add(%i, %i) should return %i", (a, b, expected) => {
expect(add(a, b)).toBe(expected);
});
Pattern 7: Test Fixtures and Setup
Python (pytest fixtures):
@pytest.fixture
def sample_user():
"""Create a test user for multiple tests"""
return User(email="[email protected]", name="Test User")
@pytest.fixture
def database():
"""Set up and tear down test database"""
db = create_test_database()
yield db
db.drop_all()
def test_save_user(database, sample_user):
database.save(sample_user)
assert database.count() == 1
def test_find_user(database, sample_user):
database.save(sample_user)
found = database.find_by_email("[email protected]")
assert found.name == "Test User"
TypeScript (Jest):
describe("UserService", () => {
let service: UserService;
let mockDb: Database;
beforeEach(() => {
mockDb = createMockDatabase();
service = new UserService(mockDb);
});
afterEach(() => {
mockDb.clear();
});
it("should save user", () => {
const user = { email: "[email protected]" };
service.save(user);
expect(mockDb.count()).toBe(1);
});
});
Pattern 8: Testing Private Methods (Don't!)
Bad Approach:
# DON'T: Testing private methods directly
def test_private_validation():
obj = MyClass()
assert obj._validate_input("test") is True # Testing private method
Good Approach:
# DO: Test through public interface
def test_public_method_with_valid_input():
obj = MyClass()
result = obj.process("test") # Public method
assert result.success is True # Private validation tested indirectly
def test_public_method_with_invalid_input():
obj = MyClass()
result = obj.process("") # Public method
assert result.success is False # Private validation tested indirectly
Principle: Tests should verify behavior, not implementation details
TDD Workflow Examples
Example 1: Building a String Calculator (Classic Kata)
Requirement: Create a calculator that adds numbers in a string
# Iteration 1: Empty string
def test_empty_string_returns_zero():
assert string_calculator("") == 0
def string_calculator(numbers):
return 0 # Minimal code to pass
# Iteration 2: Single number
def test_single_number():
assert string_calculator("5") == 5
def string_calculator(numbers):
if not numbers:
return 0
return int(numbers)
# Iteration 3: Two numbers
def test_two_numbers():
assert string_calculator("1,2") == 3
def string_calculator(numbers):
if not numbers:
return 0
return sum(int(n) for n in numbers.split(","))
# Iteration 4: Multiple numbers
def test_multiple_numbers():
assert string_calculator("1,2,3,4") == 10
# Already passes with current implementation!
# Iteration 5: New line delimiter
def test_newline_delimiter():
assert string_calculator("1\n2,3") == 6
def string_calculator(numbers):
if not numbers:
return 0
numbers = numbers.replace("\n", ",")
return sum(int(n) for n in numbers.split(","))
# Iteration 6: Negative numbers throw exception
def test_negative_numbers_throw():
with pytest.raises(ValueError, match="Negatives not allowed: -2, -5"):
string_calculator("1,-2,3,-5")
def string_calculator(numbers):
if not numbers:
return 0
numbers = numbers.replace("\n", ",")
nums = [int(n) for n in numbers.split(",")]
negatives = [n for n in nums if n < 0]
if negatives:
raise ValueError(f"Negatives not allowed: {', '.join(map(str, negatives))}")
return sum(nums)
TDD Benefits Demonstrated:
- Requirements clarified through tests
- Code grows organically
- Always working (green) state
- Refactoring is safe
Example 2: TDD for API Endpoints
# RED: Test first
def test_create_user_endpoint(client):
response = client.post("/users", json={
"email": "[email protected]",
"name": "Test User"
})
assert response.status_code == 201
assert response.json["email"] == "[email protected]"
assert "id" in response.json
# GREEN: Implement minimal endpoint
@app.post("/users")
def create_user(request):
data = request.json
user = User(email=data["email"], name=data["name"])
db.save(user)
return {"id": user.id, "email": user.email}, 201
# RED: Test validation
def test_create_user_invalid_email(client):
response = client.post("/users", json={
"email": "invalid-email",
"name": "Test"
})
assert response.status_code == 400
assert "Invalid email" in response.json["error"]
# GREEN: Add validation
@app.post("/users")
def create_user(request):
data = request.json
if not is_valid_email(data["email"]):
return {"error": "Invalid email format"}, 400
user = User(email=data["email"], name=data["name"])
db.save(user)
return {"id": user.id, "email": user.email}, 201
Best Practices
TDD Guidelines
Do's:
- Write tests first (red → green → refactor)
- Keep tests simple and focused
- Test behavior, not implementation
- Use descriptive test names
- One assertion per test (when practical)
- Run tests frequently (every few minutes)
- Commit after each green state
Don'ts:
- Don't skip the refactor step
- Don't test private methods
- Don't write tests after implementation (that's not TDD!)
- Don't make tests depend on each other
- Don't test framework code
- Don't write overly complex test setups
Test Naming Conventions
Good Test Names:
def test_add_returns_sum_of_two_numbers()
def test_divide_raises_error_when_divisor_is_zero()
def test_create_user_saves_to_database()
def test_authenticate_fails_with_invalid_password()
Pattern: test_[method]_[scenario]_[expected_result]
Anti-Patterns
Common TDD Mistakes
❌ Writing all tests upfront
→ Write one test at a time, see it fail, make it pass
❌ Testing getters/setters
→ Test actual behavior, not trivial code
❌ Overly complex test setup
→ Simplify with fixtures or factory functions
❌ Tests that depend on each other
→ Each test should be independent
❌ Not seeing tests fail first
→ Always see red before green (ensures test works)
❌ Skipping refactor step
→ Refactor to keep code clean
❌ Testing implementation details
→ Test through public interface
❌ Slow tests
→ Use mocks/stubs for fast unit tests
Tools & Frameworks
Python
# pytest: Most popular Python test framework
pytest tests/
# Coverage
pytest --cov=src --cov-report=html
# Watch mode (rerun on changes)
pytest-watch
# Mocking
from unittest.mock import Mock, patch
TypeScript/JavaScript
# Jest: Popular testing framework
npm test
# Watch mode
npm test -- --watch
# Coverage
npm test -- --coverage
# Mocking
jest.mock('./module')
Go
# Built-in testing
go test ./...
# Coverage
go test -cover ./...
# Table-driven tests (idiomatic Go)
Test Runners
# Continuous testing
npm install -g wallaby.js # IDE integration
npm install -g jest --watch # CLI watch mode
Level 3: Resources
Comprehensive Reference
Location: skills/engineering/test-driven-development/resources/REFERENCE.md (~900 lines)
Complete reference covering:
- TDD fundamentals and the three laws
- Red-Green-Refactor cycle in depth
- Test-first development principles
- Unit test design patterns (fixtures, builders, object mothers)
- Test doubles and mocking strategies (dummies, stubs, spies, mocks, fakes)
- Inside-Out vs Outside-In TDD approaches
- ATDD (Acceptance Test-Driven Development)
- BDD (Behavior-Driven Development)
- TDD with different paradigms (OOP, functional, property-based)
- Common TDD mistakes and solutions
- Refactoring safely with tests
- TDD metrics and benefits (coverage, defect density, velocity)
- TDD in different contexts (Web APIs, frontend, databases, CLI tools)
- Advanced TDD techniques (mutation testing, contract testing, characterization tests)
- TDD anti-patterns (Free Ride, The Liar, The Mockery, The Inspector, The Slowpoke)
Scripts
Location: skills/engineering/test-driven-development/resources/scripts/
1. TDD Session Tracker (tdd_session.py)
- Interactive tracker for Red-Green-Refactor cycles
- Times each phase (RED, GREEN, REFACTOR)
- Tracks cycle metrics and session statistics
- Identifies slow phases and suggests improvements
- Exports session data to JSON for analysis
# Start interactive TDD session
./tdd_session.py start
# Analyze completed session
./tdd_session.py analyze --session-file session.json
# Get session statistics
./tdd_session.py stats --session-file session.json --json
2. TDD Metrics Analyzer (analyze_tdd_metrics.py)
- Calculate test-to-code ratios
- Analyze coverage trends and progression
- Detect test smells and anti-patterns
- Generate TDD health scores (0-100)
- Track metrics across git history
# Calculate test-to-code ratio
./analyze_tdd_metrics.py ratio --source-dir src/ --test-dir tests/
# Analyze TDD health
./analyze_tdd_metrics.py health --source-dir src/ --test-dir tests/ --coverage-file .coverage
# Track metrics across commits
./analyze_tdd_metrics.py history --repo-dir . --commits 10 --json
3. Test Template Generator (generate_test_template.sh)
- Generate language-specific test templates
- Support for Python (pytest), TypeScript (Jest), Rust, Go
- BDD (Given-When-Then) or AAA (Arrange-Act-Assert) styles
- Includes fixtures, parameterized tests, and best practices
# Python pytest template
./generate_test_template.sh python Calculator --framework pytest
# TypeScript Jest template with BDD style
./generate_test_template.sh typescript UserService --style bdd
# Rust test template
./generate_test_template.sh rust string_utils
# Go table-driven test template
./generate_test_template.sh go Validator
Examples
Location: skills/engineering/test-driven-development/resources/examples/
Python (python/tdd_example.py)
- String Calculator kata showing full TDD progression
- Before/after comparison (implementation-first vs test-first)
- Complete Red-Green-Refactor cycles for each requirement
- Demonstrates incremental development and continuous refactoring
- Test suite evolution from simple to comprehensive
TypeScript (typescript/tdd_example.test.ts)
- Bowling Game kata in TypeScript with Jest
- Shows TDD rhythm in a stateful object
- Demonstrates test organization with describe blocks
- Helper functions to reduce test duplication
- Complete progression from gutter game to perfect game
Rust (rust/tdd_example.rs)
- Stack implementation showing TDD with Rust's type system
- Demonstrates Result<T, E> error handling in tests
- Shows how ownership/borrowing influences test design
- Property-based testing examples (with proptest)
- Nested test modules for organization
Workflow Guide (workflows/tdd-workflow.md)
- Daily TDD workflow (morning routine, core cycle, end of day)
- Project setup for TDD (frameworks, configuration, IDE setup)
- Feature development step-by-step guide
- Debugging workflow when tests fail
- Refactoring workflow with TDD safety net
- Code review checklist for TDD
- Common scenarios (new feature, bug fix, validation, legacy code, external dependencies)
Usage
Start a TDD session:
cd skills/engineering/test-driven-development/resources
./scripts/tdd_session.py start
Generate test template for new feature:
./scripts/generate_test_template.sh python UserAuthentication --framework pytest --style bdd
Check TDD health:
./scripts/analyze_tdd_metrics.py health \
--source-dir ../../../src \
--test-dir ../../../tests \
--coverage-file ../../../.coverage
Study examples:
# Python example with full TDD progression
cat examples/python/tdd_example.py
# TypeScript kata
cat examples/typescript/tdd_example.test.ts
# Rust with type system
cat examples/rust/tdd_example.rs
# Complete workflow guide
cat examples/workflows/tdd-workflow.md
Related Skills
- engineering-code-review: Reviewing tests in PRs
- engineering-refactoring-patterns: Refactoring with test safety net
- engineering-code-quality: Tests improve code quality
- engineering-continuous-integration: Automating test execution
- engineering-design-patterns: Testing pattern implementations