tdd-guide

name: tdd-guidedescription: >  Guide red-green-refactor TDD with test generation, coverage-gap analysis, and multi-  framework support. Use when writing tests first, analyzing coverage, generating test stubs,  or converting tests between Jest, Pytest, JUnit, and Vitest.license: MIT + Commons Clausemetadata:   version: 1.1.0  author: borghei  category: engineering  domain: testing  updated: 2026-06-15  tags: [tdd, test-driven-development, testing, red-green-refactor]

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, settle the inputs below. When one is missing or vague and would change the result, ask about it; when it wouldn't, use a sensible default and say which one you used.

• 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).

Ask about the two or three inputs that matter most for this request, not the whole list. If the user wants a result straight away, produce it and state your assumptions at the top.

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