SKILL

---
name: test-writer
description: Write tests for existing code. Test behaviour not implementation, AAA structure, mock at boundaries, no flaky tests.
category: delivery
version: 0.1.0
triggers: ["write tests", "add tests", "test coverage", "test for X", "missing tests"]
applies_to: [openclaw, cursor, claude-code]
---

# Test Writer

You write tests for existing code. Tests document behaviour and catch regressions; they
are not a coverage-percentage box to tick. You test what the code is supposed to *do*,
not how it's currently structured. Implementation-coupled tests rot the moment refactors
happen and become a tax on every change.

## When to use

- Adding tests to existing untested code
- Filling a coverage gap on a specific function / component / endpoint
- Writing tests that should have caught a bug just fixed (regression tests)
- Pre-launch test pass for a feature

Do not invoke for:
- Writing code with tests included — that's part of `architecture/frontend-feature`,
  `architecture/backend-api`, or whichever skill is doing the work
- E2E test infrastructure setup — flag as separate work
- Snapshot-only changes (regenerating snapshots without thinking is not testing)

## Scope

In scope:
- Unit tests for pure logic (functions, hooks, utilities, components)
- Integration tests at module / API / data-layer boundary
- Regression tests for fixed bugs
- Test fixtures and factories
- Mocking at the right boundary

Out of scope:
- E2E / browser / Playwright / Cypress test infrastructure (delegate or flag)
- Performance / load / chaos tests
- Test framework selection — match what the project uses

## Inherits

- [`meta/engineering-principles`](../../meta/engineering-principles/SKILL.md) — naming, file size, single responsibility apply to tests too.
- [`meta/reuse-before-create`](../../meta/reuse-before-create/SKILL.md) — before writing a new fixture, factory, mock, or test helper, search for an existing one in the test tree; tests duplicate setup more than any other code.
- [`meta/token-discipline`](../../meta/token-discipline/SKILL.md) — read the unit under test and 1–2 sibling tests for style; not the whole test suite.
## Token discipline (specific)

- Read the **unit under test** and its direct dependencies. Don't recursively read the
  whole module graph.
- Read **1–2 existing tests** in the same project to learn conventions:
  - Test file location (colocated vs `__tests__/` vs mirrored structure)
  - Naming style (`describe('X')` vs `test('does Y')`)
  - Setup / teardown patterns
  - Fixture / factory helpers in use
- Read the test framework config (`vitest.config.*`, `jest.config.*`, `pytest.ini`, etc.)
  once, only if needed.
- Do NOT read tests of unrelated features.

## Test taxonomy — pick the right level

| Level | What it tests | When to write | Where to mock |
|---|---|---|---|
| **Unit** | One function/hook/component in isolation | Pure logic, deterministic transforms | External I/O, time, randomness |
| **Integration** | Multiple units together at a boundary | API route, data hook with cache, form + validation flow | At the seam (DB driver, fetch, file system) |
| **Contract** | API request/response matches a schema | Public endpoints, RPCs, message queues | Don't mock the schema validator |
| **E2E** | Full user flow through real stack | Smoke tests, critical paths only | Avoid mocking — real stack is the point |

Default to the lowest level that covers the behaviour. Higher levels are slower, harder
to debug, and shouldn't substitute for unit tests of pure logic.

## Process

1. **Identify the unit and its contract.** What inputs does it take, what outputs/effects
   does it produce, what errors does it raise?
2. **List behaviours to test, not branches to cover.** "Returns the user when found",
   "raises NotFoundError when missing" — not "covers line 42".
3. **Pick the level.** Unit unless the behaviour spans a boundary.
4. **Read sibling tests.** Match style, file location, fixture/factory usage.
5. **Write the tests in AAA structure** (Arrange / Act / Assert), one behaviour per test.
6. **Run them.** Confirm they pass on the current code. If a regression test, confirm it
   fails on the broken code first, then on the fixed code.
7. **Hand off.** Report what behaviours are covered, what's deliberately not covered, and
   any gaps that need follow-up.

## Test structure — AAA