test-driven-development

Test-Driven Development (TDD) Skill

This skill defines the proper TDD workflow: write test(s), run them (RED), implement minimal code (GREEN), run ALL tests (VERIFY), repeat.

Language-specific details:

• For Python projects: See test-driven-development/PYTHON.md for pytest patterns, running tests, and Python-specific examples
• Other languages: Add new files to test-driven-development/ directory as needed

TDD Cycle: RED → GREEN → REFACTOR

How Many Tests to Write at Once?

Write ONE test at a time when:

• Design is uncertain or exploratory
• Domain is complex and unfamiliar
• You need to review and course correct after each step
• Implementation approach is unclear

Write MULTIPLE tests upfront when:

• Requirements are clear and well-understood
• Domain is familiar
• Design is straightforward
• You're confident in the implementation approach

1. RED: Write Failing Test(s)

Write test(s) that fail.

Key principle: Each test must fail for the right reason (missing implementation, not syntax error).

CRITICAL - Run the tests - they MUST fail:

• ❌ DO NOT write implementation before running the tests
• ❌ DO NOT skip the RED phase
• ✅ DO run the tests to verify they fail
• Verify they fail with expected error (import error, assertion failure, etc.)
• Expected outcome: RED (tests fail)

Why RED is mandatory:

• Confirms the tests actually test something
• Prevents false positives (tests that always pass)
• Validates test setup is correct

2. GREEN: Write Minimal Implementation

Write the MINIMUM code to make the tests pass.

Key principle: Don't add features not yet tested. Don't over-engineer.

Run the tests again:

• Run the tests to verify they now pass
• Expected outcome: GREEN (tests pass)

3. VERIFY: Run ALL Tests

CRITICAL: After tests pass, run ALL tests to ensure nothing broke.

Key principle: Never break existing functionality.

Run complete test suite:

• Run all tests in the project
• Verify all tests pass (new and existing)
• Expected outcome: All tests GREEN

4. REFACTOR: Improve Code Quality

After tests pass, consider refactoring to improve code quality.

Use the refactoring-code skill for detailed refactoring guidance.

Key principle: Refactor only when tests are GREEN. Tests protect you during refactoring.

When to refactor:

• Code duplication exists
• Code is unclear or hard to understand
• Better patterns or abstractions are apparent
• Performance can be improved
• Before implementing new features that may duplicate existing patterns

Refactoring safety:

• Run ALL tests after each refactoring change
• If any test fails, revert and try a different approach
• Keep refactoring changes small and incremental

Note: Refactoring is optional on each cycle. You can skip if code is already clean.

5. REPEAT: Continue

After all tests pass, continue with next requirements and repeat the cycle.

TDD Rules

Rule 1: Update Spec as You Go

• ✅ DO update spec.yaml to mark requirements as tested after tests pass
• ✅ Keep spec in sync with implementation progress

Updating spec.yaml markers:

• After writing unit test that passes: test: to-implement → test: unit
• After code passes unit test: code: to-implement → code: done
• For acceptance test markers, see the acceptance-test skill

Rule 2: Always Run Tests

CRITICAL: Tests MUST go through the RED → GREEN → VERIFY cycle:

1. RED: Run tests to see them FAIL (before implementing)
2. GREEN: Run tests to see them PASS (after implementing)
3. VERIFY: Run ALL tests in the project to verify nothing broke

❌ NEVER skip the RED phase - Always see tests fail before implementing

Why this matters:

• RED phase confirms tests actually test something (prevents false positives)
• GREEN phase confirms implementation works
• VERIFY phase ensures no regression in existing functionality

Rule 3: Minimal Implementation

• Write ONLY enough code to make the current test pass
• Don't add features not yet tested
• Don't over-engineer solutions
• Prefer simple over clever

Rule 4: Test One Thing

• Each test validates ONE behavior
• One assertion per test (unless assertions are intrinsically coupled)
• Clear test names describe what's being tested
• Multiple tests enable better parallelization

Rule 5: Fail Fast

If all tests don't pass:

• Stop immediately
• Fix the broken tests
• Don't continue until all tests GREEN

TDD Workflow Diagram

See WORKFLOW.md for the full step-by-step diagram.

Test Organization

Unit Tests

• Test individual functions/classes in isolation
• Fast, focused, and run frequently
• Located within the feature directory
• Should cover the vast majority of your testing needs
• Marked with test: unit in spec.yaml

For acceptance tests and scenarios, use the acceptance-test skill.

Test Grouping

Organize tests by requirement sections:

• Group related tests together
• Use clear section/class names
• Mirror the spec structure

Test Naming

Follow project conventions for test names:

• Descriptive names that explain what's being tested
• Include requirement reference in documentation
• Use consistent naming pattern

Test Documentation

Each test should have:

• Clear name describing behavior
• Documentation linking to spec requirement

Integration with STDD Workflow

TDD is STEP 2 of the spec-test-driven development workflow:

1. Write Spec (use spec skill)
2. Write Tests ← (use this tdd skill)
3. Implement Code (minimal code to pass tests)

When writing tests:

1. Reference spec requirements in test documentation
2. Follow test organization from spec sections
3. Write tests for requirements from the spec
4. Decide whether to write one test at a time or multiple tests based on complexity and certainty (see "How Many Tests to Write at Once?" above)

Common Mistakes to Avoid

❌ Not Running Tests Enough

• Skipping the RED phase (not verifying test fails)
• Skipping the GREEN phase (not verifying test passes)
• Skipping the VERIFY phase (not running all tests)

❌ Over-Implementing

• Adding features not yet tested
• Writing more code than needed to pass the test
• Implementing based on assumptions rather than tests

❌ Writing Bad Tests

• Tests that don't fail when they should
• Tests with multiple assertions (unless intrinsically coupled)
• Tests that don't clearly document what they're testing
• Using mocks — always use real implementations instead of mocks

Checklist Before Moving Forward

Use this checklist for your TDD workflow in this exact order:

1. Tests written with clear names and documentation
2. Tests reference specific requirements from spec
3. Tests run and FAILED (RED) ✓ ← DO NOT SKIP THIS
4. Minimal implementation written (ONLY after seeing RED)
5. Tests run and PASSED (GREEN) ✓
6. ALL tests run and PASSED (VERIFY) ✓
7. spec.yaml updated with test markers (test: unit or test: acceptance) ✓
8. spec.yaml updated with implementation markers (code: done) if code complete ✓
9. Code refactored if needed (optional)
10. ALL tests still pass after refactoring
11. No broken tests
12. Ready to continue

Critical reminder: Steps 3-6 MUST happen in order:

• RED (tests fail) → then implement → GREEN (tests pass) → then VERIFY (all tests pass)