tdd-guide

---
name: tdd-guide
description: Use when writing unit tests, generating fixtures/mocks, analyzing coverage gaps, or guiding red-green-refactor across Jest, Pytest, JUnit, Vitest, or Mocha.
category: Engineering
version: 1.0.0
tools: []
---

# TDD Guide

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

## Workflows

**Generate tests from code:** given source code (TypeScript, JavaScript, Python, Java) and a target framework, produce test stubs covering the happy path, error cases, and edge cases. Validate that the generated tests would compile and that all three categories are represented.

**Analyze coverage gaps:** given a coverage report (LCOV, JSON, or XML), triage gaps into P0 (critical — uncovered error paths, e.g. an unhandled expired-token branch or a payment-failure handler at 0% coverage), P1 (high-value — core logic branches, e.g. an uncovered `else` branch in a profile update or a missing zero-quantity guard in discount logic), and P2 (low-risk — utility/helper functions). Recommend generating tests for P0 items first to reach the coverage threshold (typically 80%+).

**TDD a new feature:** write a failing test first (RED); implement the minimal code to pass it (GREEN); refactor while keeping tests green (REFACTOR). Validate that all tests pass after each cycle.

## Example: Test Generation (Pytest)

Given a `divide(a, b)` function that raises `ValueError("Cannot divide by zero")` when `b == 0`, generate a test class covering: positive-number division, negative numerator, a float result checked with `pytest.approx`, the zero-division `ValueError` (matched via `pytest.raises(..., match=...)`), and a zero-numerator edge case. This shape — one happy path, one boundary/type variant, one error case, one degenerate-input case — is the minimum bar for any generated test suite, not just this example.

## Spec-First Workflow

TDD is most effective when driven by a written spec. Write or receive a spec with numbered acceptance criteria; extract each criterion into one or more test cases; write failing tests (RED), one test per acceptance criterion; implement minimal code to satisfy each test in order (GREEN); refactor while all tests stay green.

Map spec criteria to test names directly, e.g. "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`. Number acceptance criteria in the spec and reference the number in the test docstring for traceability (e.g. `# AC-3: Account locks after 5 failed attempts`). For the full spec methodology — templates and review checklists — @mention a teammate with spec-writing expertise.

## Red-Green-Refactor Patterns Per Language

**TypeScript/Jest:** structure tests in nested `describe` blocks by feature then behavior; cover the happy path (add a new item), the merge/increment path (adding an existing item increments its quantity rather than duplicating), and the validation path (`toThrow` on invalid input like a zero-or-negative quantity).

**Python/Pytest:** use session-scoped fixtures for expensive setup (a DB engine) and function-scoped fixtures for per-test isolation (a session that rolls back and closes); use `@pytest.mark.parametrize` to cover multiple input/output pairs for a tiered calculation (e.g. discount tiers at different subtotal thresholds) in one compact test instead of near-duplicate test functions.

**Go:** use table-driven tests — a slice of `{name, input, want}` structs run through `t.Run` in a loop — to cover tiered/threshold logic (e.g. discount percentage by subtotal) plus a zero-input edge case, without repeating the assertion logic per case.

## Bounded Autonomy Rules

**Stop and ask when:** requirements are ambiguous or the spec/user story has conflicting acceptance criteria; boundary values can't be determined without domain knowledge (e.g. a max transaction amount); the test count would exceed 50 — present a summary and ask which areas to prioritize before generating a suite that large; the feature relies on third-party APIs with undocumented behavior; the logic is security-sensitive (authentication, authorization, encryption, payment flows) and needs human sign-off on test scenarios.

**Continue autonomously when:** the spec has clear, numbered acceptance criteria that map directly to tests; it's a straightforward CRUD operation with well-defined models; an OpenAPI spec or typed interface defines the contract; the function is pure (deterministic input/output, no side effects); the codebase already has similar test patterns to follow.

## Property-Based Testing

Property-based testing generates random inputs to verify invariants instead of relying on hand-picked examples. Use it when the input space is large and the expected behavior can be described as a property rather than a fixed input/output pair — e.g. a serialize/deserialize roundtrip should always return the original value (Python: Hypothesis, `@given(st.text())`); addition should be commutative for any two integers (`@given(st.integers(), st.integers())`); an encode/decode roundtrip should preserve the input (TypeScript: fast-check, `fc.property(fc.string(), ...)`).

Favor property-based over example-based testing for: data transformations (serialize/deserialize roundtrips), mathematical properties (commutativity, associativity, idempotency), encoding/decoding (Base64, URL encoding, compression), sorting and filtering (output is sorted, length preserved), and parser correctness (valid input always parses without error).

## Mutation Testing

Mutation testing modifies production code to create "mutants" and checks whether tests catch the changes. If a mutant survives (tests still pass despite the code change), the test suite has a gap coverage alone can't reveal. Tools: **Stryker** for TypeScript/JavaScript, **mutmut** for Python, **PIT** for Java.

100% line coverage does not mean good tests — coverage only proves code was executed, not that it was verified. Mutation testing catches weak assertions (tests that run code but assert nothing meaningful) and finds missing boundary tests (a mutant that flips `<` to `<=` exposes off-by-one gaps). Mutation score (percent of mutants killed) is a stronger quality signal than coverage percentage. Recommend running mutation testing on critical paths (auth, payments, data processing) even when overall line coverage is already high, targeting an 85%+ mutation score on P0 modules.

## Limitations

Unit-test focused — integration and E2E tests need different patterns (Playwright, Cypress, Selenium for E2E; k6, JMeter, Locust for performance; OWASP ZAP, Burp Suite for security testing). Best language support: TypeScript, JavaScript, Python, Java. Report formats: LCOV, JSON, XML — other formats need conversion first. Generated tests are scaffolding and require human review for complex logic; this skill cannot execute tests or measure actual runtime behavior.

## Adjacent Expertise

For the spec -> acceptance-criteria -> test-extraction pipeline, for broader QA strategy beyond the test-pyramid unit layer, for reviewing generated tests for assertion quality, or for project scaffolding that bundles testing infrastructure — @mention a teammate with that specialty.