Ring:test Driven Development

Test-Driven Development (TDD)

When to use

• Starting implementation of new feature
• Starting implementation of bugfix
• Writing new production code

Skip when

• Reviewing/modifying existing tests
• Exploratory/spike work — TDD is for known requirements, not exploration.

Write the test first. Watch it fail. Write minimal code to pass.

Core principle: If you didn't watch the test fail, you don't know if it tests the right thing.

The Iron Law

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

RED → GREEN → REFACTOR

RED: Write Failing Test

Write one minimal test showing what should happen. Name describes behavior. Tests real code (not mocks unless unavoidable).

Time limit: # remove new files git restore --staged --worktree # discard changes to tracked files

Destructive operations (e.g., git reset --hard) require user confirmation.

**Delete means gone forever.** These are NOT deleting: git stash, mv to .bak, commenting out, keeping as "reference."

**No asking permission. No alternatives. No exceptions.**
- Deadline? Delete, communicate delay, do it right.
- 4 hours of work? Sunk cost fallacy. Delete.
- Manager pressure? Delete, explain TDD prevents bugs.

Then start over with TDD.

## Good Test Qualities

| Quality | Good | Bad |
|---------|------|-----|
| Minimal | One thing ("and" in name = split) | `test('validates email and domain and whitespace')` |
| Clear | Describes behavior | `test('test1')` |
| Fails correctly | Expected failure matches missing feature | Test errors out from typo |

## Verification Checklist

Before marking work complete:
- [ ] Every new function/method has a test
- [ ] Watched each test fail before implementing
- [ ] Each test failed for expected reason (feature missing, not typo)
- [ ] Wrote minimal code to pass each test
- [ ] All tests pass, output pristine
- [ ] Edge cases and errors covered

## When Stuck

| Problem | Solution |
|---------|----------|
| Don't know how to test | Write wished-for API first, then assertion |
| Test too complicated | Design too complicated — simplify interface |
| Must mock everything | Code too coupled — use dependency injection |
| Test setup huge | Extract helpers; still complex = simplify design |

## Bug Fix TDD

Write failing test reproducing the bug. Follow TDD cycle. Never fix bugs without a test.

Bug: empty email accepted
RED: `test('rejects empty email')` → FAIL: `expected 'Email required', got undefined`
GREEN: `if (!data.email?.trim()) return { error: 'Email required' }`
VERIFY: PASS

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [LerianStudio](https://github.com/LerianStudio)
- **Source:** [LerianStudio/ring](https://github.com/LerianStudio/ring)
- **License:** Apache-2.0
- **Homepage:** https://lerian.studio

Install and usage instructions live in the source repository linked above.