tdd-guide

TDD Guide

The agent guides red-green-refactor TDD workflows, generates framework-specific test stubs from requirements, parses coverage reports to identify prioritized gaps, and calculates test quality metrics including smell detection and assertion density. Supports Jest, Pytest, JUnit, Vitest, and Mocha.

Core Capabilities

• Red-green-refactor guidance — phase validation (RED/GREEN/REFACTOR), cycle tracking, refactoring suggestions
• Test generation — produce test cases and framework-specific stubs from user stories, acceptance criteria, and API specs
• Coverage gap analysis — parse LCOV/JSON/XML reports, identify files below threshold, prioritize P0/P1/P2
• Test quality metrics — cyclomatic/cognitive complexity, assertion density, isolation, naming, and test smell detection
• Multi-framework support — convert tests and generate fixtures/mocks across Jest, Vitest, Pytest, JUnit, TestNG, Mocha, Jasmine

When to Use

• Writing a failing test first for a new feature (test-driven development)
• Analyzing coverage reports to find and prioritize gaps
• Generating test stubs from requirements or API specs
• Converting tests between frameworks or scaffolding fixtures/mocks
• Assessing test quality and detecting smells before merge

Clarify First

Before generating tests or analyzing coverage, confirm these inputs. If any is unknown or vague, ASK — do not assume:

• Framework & language — Jest / Vitest / Pytest / JUnit / Mocha (changes the generated stubs and any conversion)
• Task — generate from requirements / analyze coverage / guide a red-green-refactor cycle / convert tests (selects the tool)
• Source input — the user story / acceptance criteria, or the coverage report (LCOV/JSON/XML) to parse (the script's input)

Stop rule: ask only the 2-3 that most change the output. If the user says "just draft it," proceed and list your assumptions at the top of the artifact.

Quick Start

# Generate test cases from requirements (Python API)
from test_generator import TestGenerator, TestFramework
gen = TestGenerator(framework=TestFramework.PYTEST, language="python")
cases = gen.generate_from_requirements(requirements)

# Analyze coverage gaps from LCOV report
from coverage_analyzer import CoverageAnalyzer
analyzer = CoverageAnalyzer()
analyzer.parse_coverage_report(content, "lcov")
gaps = analyzer.identify_gaps(threshold=80.0)

# Guide TDD cycle
from tdd_workflow import TDDWorkflow
wf = TDDWorkflow()
wf.start_cycle("User can reset password via email")

References

Load the reference that matches the task — keep this file lean and pull detail on demand:

• references/workflows.md — step-by-step procedures for TDD-ing a feature, analyzing coverage gaps, and generating tests from requirements, each with validation checkpoints. Read when starting any of the three core workflows.
• references/tool-reference.md — complete API for all eight scripts (constructors, methods, parameters, worked examples) plus the tools summary table. Read when you need exact module names or method signatures.
• references/tdd-best-practices.md — red-green-refactor discipline, naming/structure guidelines, test quality principles, and coverage goals. Read when deciding how to write or evaluate tests.
• references/framework-guide.md — framework selection matrix, configuration, and test patterns for TypeScript/JS, Python, and Java, with version requirements. Read when setting up or choosing a test framework.
• references/ci-integration.md — coverage report flow, GitHub Actions examples (Jest/Pytest/JaCoCo), quality gates, and trend tracking. Read when wiring coverage and quality gates into CI.
• references/troubleshooting-and-quality.md — anti-patterns, troubleshooting table, and success criteria. Read when tests behave unexpectedly or when defining the test-quality bar.

Scope & Limitations

This skill covers:

• Unit test generation, scaffolding, and stub creation for Jest, Pytest, JUnit, Vitest, and Mocha
• Static coverage report parsing (LCOV, JSON/Istanbul, XML/Cobertura) with gap identification and prioritized recommendations
• Red-green-refactor workflow guidance with phase validation and cycle tracking
• Test quality assessment including complexity analysis, isolation scoring, naming quality, and test smell detection

This skill does NOT cover:

• Integration, end-to-end, or performance test generation -- see senior-qa for E2E patterns and senior-devops for load testing
• Runtime test execution or live coverage measurement -- scripts perform static analysis only; you must run your test suite externally
• Visual/snapshot testing or browser-based test workflows -- use Playwright, Cypress, or Storybook for UI-level testing
• Security-focused test generation (fuzz testing, penetration testing) -- see senior-security and senior-secops skills

Integration Points

Skill	Integration	Data Flow
senior-qa	Generated test stubs feed into QA review workflows; QA coverage standards inform threshold settings	test_generator.py output → QA review → approved test suite
code-reviewer	Metrics calculator output provides quantitative data for code review checklists	metrics_calculator.py quality report → code review scoring
senior-fullstack	Scaffolded projects include test infrastructure; TDD guide generates tests for scaffolded modules	project_scaffolder.py output → test_generator.py input
senior-devops	Coverage reports from CI pipelines are parsed by coverage analyzer; recommendations feed back into pipeline gates	CI coverage artifact → coverage_analyzer.py → pass/fail gate
senior-security	Edge-case fixtures for auth and API scenarios complement security-focused test plans	fixture_generator.py auth/API edge cases → security test plan
tech-stack-evaluator	Framework detection informs stack evaluation; test quality metrics feed into technology assessment	format_detector.py analysis → stack evaluation input