Test Driven Development

Test-Driven Development

Purpose

• Drive implementation from observable behavior.
• Reproduce bugs before fixing them.
• Keep code changes tightly coupled to expected outcomes.
• Use tests as design tools, not just safety nets.
• Reduce regressions by proving each behavior change.

Activation Signals

• Use this skill when adding a new feature with clear acceptance behavior.
• Use this skill when fixing a bug that should never recur.
• Use this skill when API shape is easier to design from usage than internals.
• Use this skill when reviewers will ask for evidence.
• Use this skill when the codebase already has a strong test culture.

Core Cycle

1. Write a failing test.
2. Run the smallest test scope and watch it fail for the right reason.
3. Implement the smallest change that makes it pass.
4. Re-run the test.
5. Refactor while keeping tests green.
6. Expand coverage only when a new behavior boundary appears.

Red Phase

• Express one behavior at a time.
• Name the test after the behavior, not the implementation.
• Ensure the failure is caused by missing behavior, not a broken fixture.
• Keep setup minimal.
• Prefer explicit assertions over snapshot sprawl unless snapshots are already standard.
• For bug fixes, make the failing test mirror the actual defect.

Green Phase

• Implement the smallest viable change.
• Do not optimize before the test passes.
• Avoid speculative abstractions.
• If several code paths fail, make one behavior pass first.
• Keep the first passing diff small enough to reason about.

Refactor Phase

• Remove duplication exposed by the passing test.
• Improve names and structure.
• Preserve behavior while simplifying code.
• Re-run relevant tests after each meaningful refactor.
• Stop refactoring once readability improves and the tests still describe the behavior clearly.

Bug-Fix TDD

• Reproduce the bug in a failing test before touching the fix.
• If reproduction is expensive, build a narrow harness.
• If the bug is timing-sensitive, isolate the timing dependency rather than sleeping more.
• If the bug cannot be reproduced, treat the fix as higher risk and document why.

Test Selection Rules

• Use unit tests for pure behavior and deterministic branching.
• Use integration tests for component boundaries and data flow.
• Use end-to-end tests only when lower layers cannot express the guarantee.
• Put the regression test at the lowest layer that still captures the defect.

Assertion Rules

• Assert the most important observable outcome first.
• Prefer stable assertions over implementation detail checks.
• Avoid asserting on incidental formatting unless formatting is the feature.
• For collections, assert the contract that matters: count, key values, order, or identity.

Good Test Names

• test_search_returns_ranked_results_for_partial_match
• test_login_redirect_does_not_loop_when_session_is_hydrated
• test_serializer_rejects_missing_required_field

Bad Test Names

• test_fix
• test_works
• test_api
• test_stuff

Useful Commands

bashCopy code
pytest tests/test_module.py::test_specific_behavior -vv
pytest tests/ -k "auth and redirect" -vv
ruff check path/to/file.py

Design Benefits To Exploit

• Tests clarify API ergonomics.
• Tests reveal hidden dependencies.
• Tests pressure functions toward clean inputs and outputs.
• Tests expose when code is too coupled to mock cleanly.

Decision Rules

• If a feature request has no acceptance behavior, clarify before writing code.
• If the first test is too hard to write, the design seam may be missing.
• If the code needed to pass the test is huge, the test scope is probably too broad.
• If refactoring requires changing many tests, the tests may be overfit to internals.

Anti-Patterns

• writing tests after the implementation and calling it TDD
• changing the test to match a broken implementation
• asserting on private internals instead of behavior
• creating giant fixture setups for simple behavior
• using TDD language while skipping the red phase

Output Contract

When reporting TDD progress, include:

• failing test added
• implementation change
• verification command
• refactor notes
• remaining coverage gaps

Example Status Block

markdownCopy code
TDD status:
- Red: added failing regression test for partially hydrated session redirect
- Green: updated middleware guard to wait for token presence
- Refactor: simplified session-check helper naming
- Verify: pytest tests/test_auth.py::test_login_redirect_does_not_loop_when_session_is_hydrated -vv

Coverage Guidance

• Start with one high-signal test.
• Add neighboring tests only when the bug or feature has multiple edges.
• Do not explode the matrix on the first pass.
• Prefer targeted new tests over broad rewrites of existing suites.

Failure Modes

• wrong failure reason in red phase
• massive green-phase implementation
• no refactor after a crude passing patch
• tests too brittle to survive harmless refactors
• overuse of mocks where real data flow would be clearer

Recovery Moves

• Rewrite the test if it fails for the wrong reason.
• Split one large behavior into multiple smaller tests.
• Move down a layer if end-to-end setup is hiding the real contract.
• Replace mocks with real collaborators when possible.

Checklist

1. Name the behavior.
2. Write the failing test.
3. Confirm the right failure.
4. Implement the smallest fix.
5. Re-run the narrow test.
6. Refactor with tests green.
7. Run adjacent coverage.
8. Report evidence, not confidence alone.