playbooks

home / skills / vadimcomanescu / codex-skills / test-driven-development

test-driven-development skill

/skills/.curated/quality/test-driven-development

This skill guides you through test-driven development, writing failing tests first and making minimal changes to drive design and prevent regressions.

npx playbooks add skill vadimcomanescu/codex-skills --skill test-driven-development

Review the files below or copy the command above to add this skill to your agents.

Files (3)
SKILL.md
1.3 KB
---
name: test-driven-development
description: "Test-driven development workflow (red → green → refactor) for features, bug fixes, and refactors. Use when implementing behavior changes and you want to drive design via tests, prevent regressions, and keep code modular and well-factored."
---

# Test-Driven Development

Write the test first, then write the smallest change that makes it pass, then refactor safely.

## Core loop
1) **Red**: write a failing test that expresses the desired behavior.
2) **Green**: implement the minimum change to pass.
3) **Refactor**: improve structure while keeping tests green.

## Quick Start
- Start from the public interface (API, function, UI behavior), not private helpers.
- Prefer “behavioral” test names (what), not “implementation” names (how).
- When fixing bugs: reproduce with a test first.

## Guardrails
- Don’t over-mock: prefer integration at boundaries; mock only slow/flaky externals.
- Keep tests deterministic: control time, randomness, and network.
- If a test is hard to write, your design likely needs an interface seam.

## Red/Green/Refactor checklist
- Red: test fails for the right reason (not setup errors).
- Green: smallest change to pass, no extra behavior.
- Refactor: improve structure without changing behavior or tests.

## References
- Common anti-patterns: `references/testing-anti-patterns.md`

Overview

This skill teaches a practical test-driven development (TDD) workflow: red → green → refactor. It focuses on driving design through tests to implement features, fix bugs, and perform refactors while preventing regressions and keeping code modular. The guidance is tailored for Python projects and emphasizes small, safe steps that keep tests fast and deterministic.

How this skill works

Begin by writing a failing test that specifies the desired public behavior (Red). Implement the smallest possible change to make that test pass (Green). Then refactor code and tests to improve clarity and design while keeping the test suite green (Refactor). Repeat the loop for each behavior change, using tests as the primary design driver and safety net.

When to use it

  • Implementing new features where behavior should be specified before code
  • Fixing bugs—reproduce the bug with a failing test before changing code
  • Refactoring legacy code while ensuring no regressions
  • Designing APIs or public interfaces that must remain stable
  • Onboarding team members to a disciplined, test-first workflow

Best practices

  • Write tests against the public interface, not private helpers or internals
  • Name tests for expected behavior, not implementation details
  • Make the minimal change to pass a test; avoid adding unrelated features during Green
  • Keep tests deterministic: control time, randomness, and external IO
  • Mock only slow, flaky, or non-deterministic externals; prefer integration at boundaries
  • If a test is hard to write, introduce a seam or rethink the design

Example use cases

  • Add a new API endpoint: write a test describing the request/response, implement the handler, then refactor routing and shared logic
  • Fix a reported bug: create a failing unit or integration test that reproduces the issue, patch the bug, and add regression coverage
  • Refactor a large function: write tests for current behavior, refactor into smaller functions, and ensure tests pass throughout
  • Introduce a new CLI option: author behavioral tests for expected output, implement option parsing, then clean up internal helpers

FAQ

How small should the Green change be?

Make the tiniest change that causes the failing test to pass—no extra features or broad refactors during Green.

When is it appropriate to mock?

Mock when dependencies are slow, flaky, or non-deterministic (network, time, external services). Prefer real integration at clear boundaries when practical.