tdd-guide – Coding skill for AI agents

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

// test/cart.test.ts
describe("Cart", () => {
  describe("addItem", () => {
    it("should add a new item to an empty cart", () => {
      const cart = new Cart();
      cart.addItem({ id: "sku-1", name: "Widget", price: 9.99, qty: 1 });

      expect(cart.items).toHaveLength(1);
      expect(cart.items[0].id).toBe("sku-1");
    });

    it("should increment quantity when adding an existing item", () => {
      const cart = new Cart();
      cart.addItem({ id: "sku-1", name: "Widget", price: 9.99, qty: 1 });
      cart.addItem({ id: "sku-1", name: "Widget", price: 9.99, qty: 2 });

      expect(cart.items).toHaveLength(1);
      expect(cart.items[0].qty).toBe(3);
    });

    it("should throw when quantity is zero or negative", () => {
      const cart = new Cart();
      expect(() =>
        cart.addItem({ id: "sku-1", name: "Widget", price: 9.99, qty: 0 })
      ).toThrow("Quantity must be positive");
    });
  });
});

Python / Pytest (Advanced Patterns)

# tests/conftest.py — shared fixtures
import pytest
from app.db import create_engine, Session

@pytest.fixture(scope="session")
def db_engine():
    engine = create_engine("sqlite:///:memory:")
    yield engine
    engine.dispose()

@pytest.fixture
def db_session(db_engine):
    session = Session(bind=db_engine)
    yield session
    session.rollback()
    session.close()

# tests/test_pricing.py — parametrize for multiple cases
import pytest
from app.pricing import calculate_discount

@pytest.mark.parametrize("subtotal, expected_discount", [
    (50.0, 0.0),       # Below threshold — no discount
    (100.0, 5.0),      # 5% tier
    (250.0, 25.0),     # 10% tier
    (500.0, 75.0),     # 15% tier
])
def test_calculate_discount(subtotal, expected_discount):
    assert calculate_discount(subtotal) == pytest.approx(expected_discount)

Go — Table-Driven Tests

// cart_test.go
package cart

import "testing"

func TestApplyDiscount(t *testing.T) {
    tests := []struct {
        name     string
        subtotal float64
        want     float64
    }{
        {"no discount below threshold", 50.0, 0.0},
        {"5 percent tier", 100.0, 5.0},
        {"10 percent tier", 250.0, 25.0},
        {"15 percent tier", 500.0, 75.0},
        {"zero subtotal", 0.0, 0.0},
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            got := ApplyDiscount(tt.subtotal)
            if got != tt.want {
                t.Errorf("ApplyDiscount(%v) = %v, want %v", tt.subtotal, got, tt.want)
            }
        })
    }
}

---

Bounded Autonomy Rules

When generating tests autonomously, follow these rules to decide when to stop and ask the user:

Stop and Ask When

• Ambiguous requirements — the spec or user story has conflicting or unclear acceptance criteria
• Missing edge cases — you cannot determine boundary values without domain knowledge (e.g., max allowed transaction amount)
• Test count exceeds 50 — large test suites need human review before committing; present a summary and ask which areas to prioritize
• External dependencies unclear — the feature relies on third-party APIs or services with undocumented behavior
• Security-sensitive logic — authentication, authorization, encryption, or pay

… (full content is in the download package)