---
name: test-driven-development
description: Enforce test-first development for features and bug fixes — no production
  code before a failing test
permalink: opencode-config/skills/test-driven-development/skill
---

# Test-Driven Development (TDD)

## When to Use

Use this skill when implementing behavior changes:
- New features
- Bug fixes
- Refactors that alter behavior

If the work introduces or changes production behavior, TDD applies.

## Core Rule

```
NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
```

If production code was written first, delete or revert it and restart from a failing test.

## Red → Green → Refactor Loop

### 1) RED: Write one failing test
- Write one small test that expresses the next expected behavior.
- Prefer clear test names describing observable behavior.
- Use real behavior paths where practical; mock only when isolation is required.

### 2) Verify RED (mandatory)
Run the new test and confirm:
- It fails (not just errors)
- It fails for the expected reason
- It fails because behavior is missing, not because the test is broken

If it passes immediately, the test is not proving the new behavior. Fix the test first.

### 3) GREEN: Add minimal production code
- Implement only enough code to make the failing test pass.
- Do not add extra features, abstractions, or speculative options.

### 4) Verify GREEN (mandatory)
Run the test suite scope needed for confidence:
- New test passes
- Related tests still pass

If failures appear, fix production code first unless requirements changed.

### 5) REFACTOR
- Improve names, remove duplication, and simplify structure.
- Keep behavior unchanged.
- Keep tests green throughout.

Repeat for the next behavior.

## Quality Checks Before Completion

- [ ] Each behavior change has a test that failed before implementation
- [ ] New tests failed for the expected reason first
- [ ] Production code was added only after RED was observed
- [ ] Tests now pass cleanly
- [ ] Edge cases for changed behavior are covered

## Practical Guardrails

- "I'll write tests after" is not TDD.
- Manual verification does not replace automated failing-then-passing tests.
- If a test is hard to write, treat it as design feedback and simplify interfaces.
- Keep test intent focused on behavior, not internals.

## Related Reference

For common mistakes around mocks and test design, see [testing-anti-patterns](./testing-anti-patterns.md).