test-driven-development

Files (1)

• SKILL.md

SKILL.md (first lines)

# Test-Driven Development

## 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. A codebase with good tests is an AI agent's superpower; a codebase without tests is a liability.

Concretely: a failing test **in the touched package's language** first, then the minimal code to make it pass, then the **resolver-selected gates** to keep the tree green. The exact test command, test-file naming, fixtures, and the invariants your tests must respect are **project-specific** — read them from this project's config and convention template, not from this skill (see [Project specifics](#project-specifics)).

## When to Use

- Implementing any new logic or behavior
- Fixing any bug (the Prove-It Pattern)
- Modifying existing functionality
- Adding edge case handling
- Any change that could break existing behavior

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

**Related:** For multi-file work, combine TDD with the `incremental-implementation` skill (one thin slice, tested, then expand). For end-to-end behavior, exercise the real path — including any project-level threshold/e2e gates the resolver emits.

## The TDD Cycle

```
    RED                GREEN              REFACTOR
 Write a test    Write minimal code    Clean up the
 that fails  ──→  to make it pass  ──→  implementation  ──→  (repeat)
      │                  │                    │
      ▼                  ▼                    ▼
   Test FAILS        Test PASSES       resolver gates PASS
```

### Step 1: RED — Write a Failing Test

Write the test first, in the language of the package you're touching. It must fail. A test that passes immediately proves nothing. Run the narrow test target and **confirm it fails**.

```python
# RED: a single, focused failing case (Python example shown — use the touched
# package's language and your project's test-file pattern).
import pytest
from billing.discount import apply_discount

@pytest.mark.parametrize(
    "name, price, pct, want",
    [
        ("ten percent off",   100.0, 10, 90.0),
        ("zero percent",      100.0, 0,  100.0),
        ("clamps above 100",  100.0, 150, 0.0),
    ],
)
def test_apply_discount(name, price, pct, want):
    assert apply_discount(price, pct) == want, name
```

The same shape applies in any language — a table/parametrized failing case beside the unit (e.g. table-driven `*_test.go`, or a `*.test.ts(x)` for a web app). Use your project's test-file pattern.

### Step 2: GREEN — Make It Pass

Write the minimum code to make the test pass. Don't over-engineer:

```python
# GREEN: minimal implementation — only what the test demands.
def apply_discount(price: float, pct: float) -> float:
    pct = max(0.0, min(pct, 100.0))
    return round(price * (1 - pct / 100), 2)
```

Re-run the narrow test target and confirm it now PASSES.

### Step 3: REFACTOR — Clean Up

With the test green, improve the code without changing behavior:

- Extract shared logic
- Improve naming
- Remove duplication
- Optimize only if necessary

Then confirm the **resolver-selected gates** are still green. Get the exact commands for the files you touched from the gate resolver — don't hand-type or guess them:

```bash
git diff --name-only <base>...HEAD | node .claude/workflows/lib/gate-resolver.js --stdin
# → prints the exact per-toolchain gate commands (lint/type/test) from mzspec.config.json,
#   plus any project gates and `openspec validate "<change>" --strict`. Run each; each must exit 0.
```

Run the gates after every refactor step. (See the note on environment-dependent tests under "Verification" — a *skip* is not a failure.)

## The Prove-It Pattern (Bug Fixes)

When a bug is reported, **do not start by trying to fix it.** Start by writing a test that reproduces it.

```
Bug report arrives
       │
       ▼
  Write a test (in the touched package's language) that demonstrates the bug
       │
       ▼
  Run the narrow test target  →  FAILS (confirming the bug exists)
       │
       ▼
  Implement the fix
       │
       ▼
  Run the narrow test target  →  PASSES (proving the fix works)
       │
       ▼
  Resolver gates green (no regressions across the touched packages)
```

Writing the reproduction test *before* the fix — ideally without knowledge of the fix — makes it robust: it pins the behavior, not your implementation. If your project has a hard invariant the bug violated (data isolation, a refusal rule, determinism), the reproduction test must assert that boundary, drawn from your project's invariants (see below).

## The Test Pyramid

Invest testing effort according to the pyramid — most tests should be small and fast, with progressively fewer tests at higher levels:

```
          ╱╲
         ╱  ╲         E2E / product-threshold (~5%)

From minhlucvan/emdesign, Apache-2.0.

More from minhlucvan/emdesign