# writing-unit-tests

Guides an agent through writing or revising unit tests around observable behavior. Useful for flaky tests, confusing cases, and new test coverage.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 17800 installs · ★ 6
- Author: riekelt
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/riekelt/principal-engineer/tree/HEAD/plugins/principal-engineer/skills/writing-unit-tests/SKILL.md
- Updated: 2026-09-11
- HTML: https://affpapa.org/en/nevibecode/skills/writing-unit-tests

## What it does

The skill treats each unit test as a claim about what callers can observe. It recommends a separate, clearly named test for each behavior, with expected values worked out independently of production calculations. Tests should exercise the public contract rather than inspect private state or routine call order.

For repeatable results, it calls for isolating time, randomness, network access, and filesystem work, with mocks placed at boundaries to external resources. Replace timed sleeps with checks for an observable condition and a deadline. The `principal-engineering` skill is a prerequisite; `testing-changes` determines which tests a code change needs. If a test mostly wires up mocks, the tested boundary may need to move or be covered by an integration test instead.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add riekelt/principal-engineer --skill writing-unit-tests -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/writing-unit-tests/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/writing-unit-tests/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add riekelt/principal-engineer --skill writing-unit-tests -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/writing-unit-tests/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add riekelt/principal-engineer --skill writing-unit-tests -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/writing-unit-tests/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install riekelt/principal-engineer writing-unit-tests
```

2. **Manually: put the files in place**
- File: `.github/skills/writing-unit-tests/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add riekelt/principal-engineer --skill writing-unit-tests -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/riekelt/principal-engineer --path plugins/principal-engineer/skills/writing-unit-tests
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/writing-unit-tests/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add riekelt/principal-engineer --skill writing-unit-tests -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/riekelt/principal-engineer/tree/HEAD/plugins/principal-engineer/skills/writing-unit-tests/SKILL.md

## When to use it
- split multiple behavioral claims into focused tests
- replace sleep-based waiting with condition checks
- remove mocks of code owned by the project
- isolate tests from real time and randomness
- verify expected values without reproducing production calculations

## Example prompts
- Rewrite this unit test to check the public contract and state its claim in the test name.
- Diagnose this flaky test and replace its timed wait with a condition-based check.
- Add separate tests for the success case and the typed failure.

## Similar
- [improve-codebase-architecture](https://affpapa.org/en/nevibecode/skills/improve-codebase-architecture.md) — skill · 1163035 installs
- [design-taste-frontend](https://affpapa.org/en/nevibecode/skills/design-taste-frontend.md) — skill · 678700 installs
- [tdd](https://affpapa.org/en/nevibecode/skills/tdd.md) — skill · 1141062 installs
- [skill-creator](https://affpapa.org/en/nevibecode/skills/skill-creator.md) — skill · 414180 installs
- [agent-browser](https://affpapa.org/en/nevibecode/skills/vercel-labs-agent-browser.md) — skill · 1200000 installs
- [prototype](https://affpapa.org/en/nevibecode/skills/prototype.md) — skill · 986201 installs

From the same set: [riekelt/principal-engineer](https://affpapa.org/en/nevibecode/by/riekelt/principal-engineer.md) — 9 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md