domains / software-engineering / tdd-workflow / tdd-guide

tdd-guide

Skill card

combined

The two copies overlap on the RED -> GREEN -> REFACTOR cycle and an 80% coverage target, but each contains material steps the other lacks. The first copy is a routing and discipline guide (no production code before a failing test, minimum test set, required edge cases, and explicit routing boundaries to other skills). The second copy is a tooling and generation guide (specific Python scripts for test generation, coverage analysis, and TDD phase validation, framework-specific examples, and input/limitation constraints). Crowning one would hide the other's real alternative approach.

Repositories

Other copies

Combined skill

---
name: tdd-guide
description: Test-first development route for TDD, writing failing tests first, RED -> GREEN -> REFACTOR, and behavior-changing feature/bug/refactor work. Includes tooling for test generation, coverage analysis, and phase validation across Jest, Pytest, JUnit, Vitest, and Mocha.
---

# TDD Guide

Use this skill for all feature work, bug fixes, and refactors that change behavior.

## Routing Boundary

Use this skill when the user wants to build or change behavior through tests:
- TDD / test-driven development
- write failing tests first
- test-first implementation
- RED -> GREEN -> REFACTOR

Do not use it when tests are already failing and the user wants root cause; route that to `systematic-debugging`. Do not use it when the user only wants a test/coverage report; route that to `generating-test-reports`.

## Core Rule

No production code before a failing test.

## Workflow

1. RED
- Write one failing test for one behavior.
- Confirm the failure is expected.
- Optionally run `tdd_workflow.py --phase red` to validate.

2. GREEN
- Implement the minimal code to pass.
- Re-run tests and keep scope narrow.
- Optionally run `tdd_workflow.py --phase green` to validate.

3. REFACTOR
- Improve structure/naming without changing behavior.
- Keep all tests green.

4. COVERAGE
- Verify coverage target (recommended >=80% for lines/functions/branches).
- Add missing tests for edge/error paths.
- Optionally run `coverage_analyzer.py` on LCOV/JSON/XML report to identify prioritized gaps (P0/P1/P2).

## Minimum Test Set

- Unit: public functions and core logic.
- Integration: API/data/service boundaries.
- E2E: critical user path only when relevant.

## Required Edge Cases

- Null/undefined input
- Empty values
- Invalid types
- Boundary values
- Error paths (network/DB/file)
- Concurrency-sensitive behavior

## Tooling (Optional)

| 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` |

## 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

## Limitations

- Unit test focus; integration and E2E tests require different patterns.
- Static analysis; cannot execute tests or measure runtime behavior.
- Best for TypeScript, JavaScript, Python, Java.
- Report formats: LCOV, JSON, XML only.
- Generated tests provide scaffolding; require human review for complex logic.