test-driven-development

name	test-driven-development
description	Guides test-first workflows for bugs and features: write a minimal failing test that encodes contracts and clear failure messages, confirm the gap is not already covered, implement and document the fix, then verify green. Use when fixing bugs with tests, adding features via TDD, writing regression tests, or when the user asks for red-green-refactor or test-driven development.

Test-Driven Development (TDD)

Use this workflow when implementing a fix or feature test-first, so the change is provable and regressions stay visible.

Core loop

Work in this order unless the user’s repo has a mandated variant (e.g. always run full CI locally).

Task progress:
- [ ] Minimal failing test(s) for the bug or gap
- [ ] Stub or placeholder implementation + doc of the gap (if useful before green)
- [ ] Run new test — expect failure with a clear message
- [ ] Confirm existing tests did not already encode this behavior
- [ ] Implement the real fix or feature
- [ ] Re-run tests — new test passes; no regressions

---

1. Minimal reproducible test(s)

• Scope: One focused scenario (or a tiny set) that reproduces the bug or encodes the missing contract. Avoid testing unrelated paths in the same change unless necessary.
• Contracts: When behavior is specified (APIs, invariants, error semantics), assert those explicitly—inputs, outputs, edge cases, and error types/messages where the project cares.
• Failure messages: Prefer assertions and matchers that print actionable context on failure (expected vs actual, relevant inputs, identifiers). Avoid bare assert x without a message when the framework allows a custom string or rich matcher.
• Location: Place tests where the project already groups similar cases (same file/directory patterns, naming conventions).

---

2. Implementation sketch and documentation

• Code: Add the smallest change that can eventually satisfy the test—often starting with a failing state is enough before step 3; then replace with the real implementation after the red phase is validated.
• Documentation: In code (docstring or comment near the fix) or in the test name/docstring, briefly state what was wrong or missing and what behavior is now guaranteed. Link to issue/ticket if the project does that.

---

3. Run the new test (expect red)

• Run only the new test(s) first for speed, then widen as needed.
• Confirm the failure explains the gap (message, stack, diff)—not a flaky or unrelated error (imports, env, timeouts).

---

4. Validate existing tests do not cover this case

Before treating the new test as redundant:

• Search for overlapping cases (test names, similar assertions).
• If an existing test should have failed but did not, the bug may be in test setup, feature flags, or the scenario is not actually exercised—adjust before duplicating.
• Goal: one clear test that would have caught the bug if it had existed before the fix, without useless duplication.

---

5. Apply the fix or enhancement

• Implement the minimal correct behavior to satisfy the test and real requirements.
• Avoid widening scope (refactors, drive-by cleanups) unless required for the fix or requested by the user.

---

6. Re-run and verify green

• Run the new test(s) again — must pass.
• Run the relevant suite (module/package/project standard) to catch regressions.
• If CI differs from local commands, align with project docs or existing scripts.

---

Quick reference: red-green-refactor

Phase	Action
Red	New test fails for the right reason
Green	Smallest change that passes
Refactor	Clean up with tests still green (only if in scope)

---

Optional deep dive

For framework-specific assertion patterns (e.g. pytest, Jest, Go testing), see reference.md.