tdd-guide

Overview of tdd-guide skill

What tdd-guide is for

tdd-guide is a Test Driven Development skill for generating unit tests, finding coverage gaps, creating fixtures and mocks, and guiding red-green-refactor work across common stacks. It is most useful when you want an AI assistant to do more than “write some tests”: the skill pushes the conversation toward source code, requirements, target framework, coverage reports, and validation criteria.

Best-fit users and projects

The tdd-guide skill fits engineering teams, solo developers, and QA-focused contributors working in TypeScript, JavaScript, Python, or Java. It is especially relevant for Jest, Pytest, JUnit, Vitest, and Mocha-style workflows. Use it when you are adding tests to existing code, starting a new feature with tests first, improving coverage toward a threshold, or standardizing test output across a team.

What makes it different from a generic test prompt

A generic prompt may produce plausible tests but often misses framework conventions, edge cases, coverage priorities, or the TDD cycle itself. tdd-guide includes workflow structure, sample inputs, expected output patterns, coverage-analysis tooling, fixture generation, framework adaptation, and references for CI integration. That makes it better suited for repeatable engineering work than one-off prompt experimentation.

When tdd-guide may not be enough

tdd-guide for Test Driven Development is not a substitute for understanding domain behavior. If you cannot provide expected outcomes, dependencies, error rules, or framework details, generated tests may be shallow. It also does not automatically guarantee that tests compile in your repository; you still need to run your local test command and adjust imports, setup files, mocks, and environment-specific configuration.

How to Use tdd-guide skill

tdd-guide install and repository preview

Install the skill in a Claude Skills-compatible environment with:

npx skills add alirezarezvani/claude-skills --skill tdd-guide

Then review the upstream skill folder at engineering-team/skills/tdd-guide. Start with SKILL.md for activation rules and workflows, then read HOW_TO_USE.md for invocation examples. If you need framework-specific setup, inspect references/framework-guide.md; if your goal is build enforcement, read references/ci-integration.md; if you want better TDD habits, review references/tdd-best-practices.md.

Inputs that make tdd-guide usage stronger

The skill performs best when you provide four things: the code or feature requirement, the language, the test framework, and the expected behavior. Strong inputs include happy paths, error cases, boundary values, external dependencies, and coverage goals.

A weak prompt is: “Write tests for my auth service.”

A stronger prompt is: “Use tdd-guide to generate Jest tests for src/auth/password-validator.ts. Cover valid password, too short password, missing uppercase, missing number, missing special character, and null or empty input. Target 90% branch coverage. Use existing project style: describe, beforeEach, and expect(...).toBe(...).”

Practical tdd-guide workflow

For existing code, use this sequence:

1. Paste or reference the source file.
2. Specify language, framework, and test file naming convention.
3. Ask for tests grouped by priority: P0 behavior, P1 edge cases, P2 regressions.
4. Run the generated tests locally.
5. Paste compile errors, failing assertions, or coverage output back into the assistant.
6. Ask the skill to refine imports, mocks, fixtures, and missing branches.

For a new feature, use red-green-refactor: ask first for failing tests from acceptance criteria, implement the smallest passing code, then ask for refactor-safe improvements while keeping tests green.

Useful files and scripts to inspect first

The repository contains practical support files that are worth reading before serious use:

• assets/sample_input_python.json and assets/sample_input_typescript.json show the level of structured input that improves output quality.
• assets/expected_output.json shows the kind of test, coverage, and quality summary the skill is designed to produce.
• scripts/test_generator.py supports test generation patterns.
• scripts/coverage_analyzer.py is relevant when you have LCOV, JSON, or XML coverage data.
• scripts/fixture_generator.py, framework_adapter.py, and tdd_workflow.py indicate how the skill thinks about mocks, framework conventions, and TDD phases.

tdd-guide skill FAQ

Is tdd-guide good for beginners?

Yes, if the beginner has a concrete feature or function to test. The tdd-guide skill can teach the rhythm of red, green, and refactor while producing usable examples. However, beginners should still run every generated test and read the failures. The learning value comes from comparing expected behavior, generated assertions, and actual implementation.

Which frameworks does tdd-guide support best?

The strongest fit is Jest, Pytest, JUnit, and Vitest, with Mocha also mentioned in the skill description. The included framework reference covers TypeScript/JavaScript, Python, and Java patterns. If you use a less common framework, provide an example test file from your repository so the skill can match imports, naming, setup hooks, and assertion style.

Can it analyze coverage reports?

Yes. tdd-guide is designed to work with coverage reports such as LCOV, JSON, and XML. For best results, paste the relevant uncovered files and branches rather than only a percentage. A prompt like “coverage is 65%” is less useful than sharing coverage/lcov.info, uncovered line ranges, and the source files tied to those gaps.

When should I not use tdd-guide?

Do not use it as the only quality gate for security-critical, financial, medical, or compliance-sensitive behavior. It can help draft tests and expose gaps, but it cannot confirm business correctness without authoritative rules. It is also a poor fit when the codebase cannot be shared, no public behavior is defined, or the project relies heavily on hidden integration environments.

How to Improve tdd-guide skill

Improve tdd-guide results with better prompts

The fastest way to improve tdd-guide output is to provide behavior, not just code. Include examples of valid input, invalid input, expected exceptions, boundary values, and any existing test conventions. If mocks are needed, name the dependency and define what should be stubbed versus exercised for real.

Useful prompt additions include:

• “Do not mock the pure calculation function.”
• “Mock the payment gateway and assert it is called once.”
• “Use parameterized Pytest cases for boundary values.”
• “Prefer behavior-focused test names over implementation names.”

Fix common failure modes after first output

Common issues are wrong imports, over-mocking, brittle implementation assertions, missing async handling, and tests that improve line coverage without improving confidence. After the first result, paste the test failure or compile error and ask for a targeted correction. For example: “These Jest tests fail because the service constructor requires a repository dependency. Revise using a typed mock and keep the same behavioral coverage.”

Use coverage data to prioritize work

If your goal is coverage improvement, ask the skill to rank gaps by risk rather than generating tests for every uncovered line. Prioritize untested conditionals, error branches, public methods, and business rules before trivial getters or defensive branches. The repository’s coverage workflow supports P0/P1/P2 prioritization, which is more useful than chasing a raw percentage alone.

Iterate toward maintainable TDD practice

The best tdd-guide usage is iterative. First ask for failing tests from requirements, then ask for the minimal implementation shape, then ask for refactor suggestions that keep tests stable. Keep the assistant focused on observable behavior: inputs, outputs, side effects, exceptions, and integration boundaries. This produces tests that remain useful after the implementation changes.