---
name: unit-test-writer
description: Writes focused unit tests for existing code by finding its public behavior, covering edge cases and errors, using meaningful assertions and following the project's test framework and style. Use when asked to add tests for a function, module or class.
---

# Unit Test Writer

You are adding tests to code that already exists. The tests must describe what the code is supposed to do, not merely repeat what it currently does.

## Workflow

### 1. Learn the conventions

- Find the test runner and how to run one file: `package.json`, `pyproject.toml`, `go.mod`, `pom.xml`, `Makefile`.
- Open two or three existing tests near the target. Copy: file naming and location, import style, describe/it vs plain functions, fixtures, factories, mocking library, assertion style.
- Run the existing suite first so you know the baseline.
- Do not add a new test framework or dependency. Use what the project has; ask the user if there is none.

### 2. Understand the target

- Read the code under test and its callers. Note the public interface: inputs, outputs, thrown errors, side effects.
- Read docs, comments, types and any spec to learn the intended behavior. If the code and the documented behavior disagree, do not encode the bug as expected. Report it.
- List the dependencies: network, database, clock, filesystem, randomness. Decide which to fake.

### 3. Plan the cases

Write the list before the code. For each public function or behavior cover:

- Typical valid input (the main happy path).
- Empty and minimal input: empty string, empty list, zero, null or undefined where allowed.
- Boundaries: limits, off-by-one, first and last element, maximum length, negative numbers.
- Invalid input and the exact error raised or returned.
- Unicode and text edge cases where strings are handled: non-ASCII, emoji, combining characters, whitespace, very long text, mixed case.
- Dates and numbers where relevant: time zones, month ends, leap years, rounding, floating point, overflow.
- State and ordering: repeated calls, idempotency, input not mutated.
- Concurrency only when the code claims to be thread-safe or async: parallel calls, ordering of promises, cancellation.
- Failure of dependencies: the fake throws, times out, returns empty.

Skip cases that only test the language or a trivial getter.

### 4. Write the tests

- One behavior per test, named like a sentence: `returns 0 for an empty cart`, `rejects a negative quantity`.
- Structure: arrange, act, assert, with a blank line between parts.
- Assert specific values, not just "does not throw" or "is truthy". Check the exact result, error type and message where the message is part of the contract.
- Keep inputs small and readable; use table-driven or parameterized tests for many similar cases (`it.each`, `@pytest.mark.parametrize`, Go subtests).
- Fake only the boundaries (HTTP, database, clock, file system). Do not mock the object under test or its pure helpers.
- Make tests independent and deterministic: fixed times, seeded randomness, no shared mutable state, clean up temp files.
- Do not test private functions directly; reach them through the public behavior.

### 5. Check that the tests can fail

- Run the new tests; they must pass.
- Prove they have teeth: temporarily break the code (flip a condition, change a constant) and confirm at least one test fails, then restore it exactly. Do this on code you can restore with certainty, such as with a clean `git diff` check afterwards.
- Run the whole suite to check for interference between tests.

## Report format

- Files added or changed and the command to run them.
- The cases covered, grouped, in one short list.
- Suspected bugs found in the code (with the input that shows them). Do not silently fix production code unless asked.
- What is not covered and why (needs integration test, needs credentials, needs real service).

## Pitfalls

- Snapshot tests of large objects that nobody reads; prefer explicit assertions.
- Copying the implementation into the test (computing the expected value with the same formula).
- Assertions inside loops or callbacks that never run; check the assertion count if the framework supports it.
- Tests that pass because of the order they run in or leftover state from a previous test.
- Over-mocking so the test verifies the mocks, not the code.
- Changing production code to make it testable without telling the user; small seams like injecting a clock are fine, but state the change.
- Sleeping in tests; use fake timers or wait for a condition.

Source: [AnyModel skills catalog](https://anymodel.org/en/skills) · License: [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)
