domains / software-engineering / test-driven-development / test-driven-development

test-driven-development

Skill card

combined

The copies overlap heavily on the red-green-refactor loop, but they disagree on how to handle existing code and on the strictness of the 'test-first' rule. obra/superpowers and LeoYeAI/openclaw-master-skills enforce an 'Iron Law' where any code written before a failing test must be deleted. In contrast, sickn33/agentic-awesome-skills explicitly forbids deleting user work or resetting branches, instead advocating for characterization tests when implementation already exists. addyosmani/agent-skills adds a unique 'Discover the Stack First' step and a 'Prove-It Pattern' for bug fixes that the others lack. Because crowning one copy would either hide the 'delete code' rule or the 'preserve work' rule, a combined instruction is required.

Repositories

Other copies

Combined skill

# Test-Driven Development (TDD)

## Overview
Write a failing test before writing the code that makes it pass. For bug fixes, reproduce the bug with a test before attempting a fix. Tests are proof — "seems right" is not done.

## When to Use
- Implementing any new logic or behavior
- Fixing any bug (the Prove-It Pattern)
- Modifying existing functionality
- Adding edge case handling

**When NOT to use:** Pure configuration changes, documentation updates, or static content changes that have no behavioral impact.

## Discover the Stack First
Before writing the first test, discover how *this* repository tests:
- **Language and build system** — `package.json`, `pom.xml`, `pyproject.toml`, `go.mod`, `Cargo.toml`, etc.
- **Checked-in wrappers** — prefer `./gradlew`, `./mvnw`, `make test`, or a repo script over globally installed tools.
- **Test framework and configuration** — how it runs a single focused test vs the full suite.
- **Existing conventions** — where tests live, how files are named.
- **Documented commands** — README, CONTRIBUTING, and CI workflows.

Run the repository's focused-test command during the loop and its full-suite command before completion.

## The TDD Cycle

### Step 1: RED — Write a Failing Test
Write the test first. It must fail. A test that passes immediately proves nothing.
- **One behavior:** Test one thing. If the name has "and", split it.
- **Clear name:** The name should describe the behavior.
- **Real code:** Avoid mocks unless unavoidable. Test the production code, not the mock.

### Step 2: Verify RED — Watch It Fail
**MANDATORY. Never skip.**
Run the focused test command. Confirm:
- Test fails (not errors).
- Failure message is expected.
- Fails because the feature is missing (not typos).

**Test passes?** You are testing existing behavior. Fix the test to target the new behavior.
**Test errors?** Fix the error, re-run until it fails correctly.

### Step 3: GREEN — Make It Pass
Write the minimum code to make the test pass. Don't over-engineer.
- Don't add features, refactor other code, or "improve" beyond the test.
- If the test fails, fix the code, not the test.

### Step 4: Verify GREEN — Watch It Pass
**MANDATORY.**
Run the focused test command. Confirm:
- Test passes.
- Other tests still pass.
- Output is pristine (no errors, warnings).

**Other tests fail?** Fix them now. A green run of the test you wrote is not a green suite. Run the project's full test command before calling the change done.

### Step 5: REFACTOR — Clean Up
With tests green, improve the code without changing behavior:
- Extract shared logic.
- Improve naming.
- Remove duplication.

Run tests after every refactor step to confirm nothing broke.

## Handling Existing Code
- **New Feature:** Follow the standard RED-GREEN-REFACTOR loop.
- **Bug Fix (Prove-It Pattern):**
  1. Write a test that reproduces the bug.
  2. Verify it fails (confirming the bug exists).
  3. Implement the fix.
  4. Verify the test passes (proving the fix works).
  5. Run the full test suite (no regressions).
- **Existing Implementation:** If code already exists, do not delete it to force a test-first history. Instead, write characterization or regression tests to capture the current behavior, then proceed with changes.

## The Iron Law (For New Code)
For new features where no code exists, **NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST**. If you write code before the test, delete it and start over. Do not keep it as "reference" or "adapt" it while writing tests.

## Good Tests
| Quality | Good | Bad |
|---------|------|-----|
| **Minimal** | One thing. "and" in name? Split it. | `test('validates email and domain and whitespace')` |
| **Clear** | Name describes behavior | `test('test1')` |
| **Shows intent** | Demonstrates desired API | Obscures what code should do |

## Common Rationalizations
- **"Too simple to test":** Simple code breaks. Test takes 30 seconds.
- **"I'll test after":** Tests written after pass immediately — which proves nothing. They may test the wrong thing or miss edge cases.
- **"Deleting work is wasteful":** For new code, keeping untested code is technical debt. For existing code, preserve it and add tests.
- **"TDD is dogmatic":** TDD is pragmatic. It finds bugs before commit and prevents regressions.