/tdd-guide

name: "tdd-guide"
description: "Test-first development and test generation for Jest, Pytest, JUnit, Vitest or Mocha: red-green-refactor, fixtures and mocks, coverage gaps. Use whenever the user asks to write tests (before or after the code), mock a dependency or raise coverage."

TDD Guide

Test-driven development skill for generating tests, analyzing coverage, and guiding red-green-refactor workflows across Jest, Pytest, JUnit, and Vitest.

---

Workflows

Generate Tests from Code

1. Provide source code (TypeScript, JavaScript, Python, Java) 2. Specify target framework (Jest, Pytest, JUnit, Vitest) 3. Run `test_generator.py` with requirements 4. Review generated test stubs 5. **Validation:** Tests compile and cover happy path, error cases, edge cases

Analyze Coverage Gaps

1. Generate coverage report from test runner (`npm test -- --coverage`) 2. Run `coverage_analyzer.py` on LCOV/JSON/XML report 3. Review prioritized gaps (P0/P1/P2) 4. Generate missing tests for uncovered paths 5. **Validation:** Coverage meets target threshold (typically 80%+)

TDD New Feature

1. Write failing test first (RED) 2. Run `tdd_workflow.py --phase red` to validate 3. Implement minimal code to pass (GREEN) 4. Run `tdd_workflow.py --phase green` to validate 5. Refactor while keeping tests green (REFACTOR) 6. **Validation:** All tests pass after each cycle

---

Examples

Test Generation — Input → Output (Pytest)

**Input source function (`math_utils.py`):**

def divide(a: float, b: float) -> float:
    if b == 0:
        raise ValueError("Cannot divide by zero")
    return a / b

**Command:**

python scripts/test_generator.py --input math_utils.py --framework pytest

**Generated test output (`test_math_utils.py`):**

import pytest
from math_utils import divide

class TestDivide:
    def test_divide_positive_numbers(self):
        assert divide(10, 2) == 5.0

    def test_divide_negative_numerator(self):
        assert divide(-10, 2) == -5.0

    def test_divide_float_result(self):
        assert divide(1, 3) == pytest.approx(0.333, rel=1e-3)

    def test_divide_by_zero_raises_value_error(self):
        with pytest.raises(ValueError, match="Cannot divide by zero"):
            divide(10, 0)

    def test_divide_zero_numerator(self):
        assert divide(0, 5) == 0.0

---

Coverage Analysis — Sample P0/P1/P2 Output

**Command:**

python scripts/coverage_analyzer.py --report lcov.info --threshold 80

**Sample output:**

Coverage Report — Overall: 63% (threshold: 80%)

P0 — Critical gaps (uncovered error paths):
  auth/login.py:42-58   handle_expired_token()       0% covered
  payments/process.py:91-110  handle_payment_failure()   0% covered

P1 — High-value gaps (core logic branches):
  users/service.py:77   update_profile() — else branch  0% covered
  orders/cart.py:134    apply_discount() — zero-qty guard  0% covered

P2 — Low-risk gaps (utility / helper functions):
  utils/formatting.py:12  format_currency()            0% covered

Recommended: Generate tests for P0 items first to reach 80% threshold.

---

Key Tools

| Tool | Purpose | Usage | |------|---------|-------| | `test_generator.py` | Generate test cases from code/requirements | `python scripts/test_generator.py --input source.py --framework pytest` | | `coverage_analyzer.py` | Parse and analyze coverage reports | `python scripts/coverage_analyzer.py --report lcov.info --threshold 80` | | `tdd_workflow.py` | Guide red-green-refactor cycles | `python scripts/tdd_workflow.py --phase red --test test_auth.py` | | `fixture_generator.py` | Generate test data and mocks | `python scripts/fixture_generator.py --entity User --count 5` |

Additional scripts: `framework_adapter.py` (convert between frameworks), `metrics_calculator.py` (quality metrics), `format_detector.py` (detect language/framework), `output_formatter.py` (CLI/desktop/CI output).

---

Input Requirements

**For Test Generation:**

• Source code (file path or pasted content)
• Target framework (Jest, Pytest, JUnit, Vitest)
• Coverage scope (unit, integration, edge cases)

**For Coverage Analysis:**

• Coverage report file (LCOV, JSON, or XML format)
• Optional: Source code for context
• Optional: Target threshold percentage

**For TDD Workflow:**

• Feature requirements or user story
• Current phase (RED, GREEN, REFACTOR)
• Test code and implementation status

---

Spec-First Workflow

TDD is most effective when driven by a written spec. The flow:

1. **Write or receive a spec** — stored in `specs/<feature>.md` 2. **Extract acceptance criteria** — each criterion becomes one or more test cases 3. **Write failing tests (RED)** — one test per acceptance criterion 4. **Implement minimal code (GREEN)** — satisfy each test in order 5. **Refactor** — clean up while all tests stay green

Spec Directory Convention

project/
├── specs/
│   ├── user-auth.md          # Feature spec with acceptance criteria
│   ├── payment-processing.md
│   └── notification-system.md
├── tests/
│   ├── test_user_auth.py     # Tests derived from specs/user-auth.md
│   ├── test_payments.py
│   └── test_notifications.py
└── src/

Extracting Tests from Specs

Each acceptance criterion in a spec maps to at least one test:

| Spec Criterion | Test Case | |---------------|-----------| | "User can log in with valid credentials" | `test_login_valid_credentials_returns_token` | | "Invalid password returns 401" | `test_login_invalid_password_returns_401` | | "Account locks after 5 failed attempts" | `test_login_locks_after_five_failures` |

**Tip:** Number your acceptance criteria in the spec. Reference the number in the test docstring for traceability (`# AC-3: Account locks after 5 failed attempts`).

> **Cross-reference:** See `engineering/spec-driven-workflow` for the full spec methodology, including spec templates and review checklists.

---

Red-Green-Refactor Examples Per Language

TypeScript / Jest