# unit-testing

A skill that steers your agent through unit testing: which test double to pick, how to gate coverage in CI, and how to check the tests themselves with mutation testing.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 1100 installs · ★ 211
- Author: kindlmann
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/petrkindlmann/qa-skills/tree/HEAD/skills/unit-testing/SKILL.md
- Updated: 2026-10-22
- HTML: https://affpapa.org/en/nevibecode/skills/unit-testing

## What it does

The skill gives the agent a working frame for tests in Jest, Vitest and pytest. It ships the test-doubles taxonomy (stub, spy, mock, fake), the Arrange-Act-Assert shape, fake timers, snapshot testing, and mutation testing with Stryker or mutmut. Before writing anything it tells the agent to check `.agents/qa-project-context.md` and then `package.json` or `pyproject.toml` to see which runner the project already uses.

Coverage gets its own section. In Jest the threshold key is `coverageThreshold`, singular. The plural `coverageThresholds` is not a Jest key at all: Jest ignores it without a warning, the gate never fires, and CI stays green on poorly covered code. Worth grepping your own `jest.config.js` for that typo. Vitest puts thresholds under `test.coverage.thresholds` in `vitest.config.ts`, pytest under `[tool.coverage.report]` in `pyproject.toml`.

The skill stays out of coverage report interpretation and gap hunting, out of AI-written test code, and out of auditing existing tests for smells. Browser and component rendering assertions belong elsewhere too.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add petrkindlmann/qa-skills --skill unit-testing -a claude-code
```

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

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add petrkindlmann/qa-skills --skill unit-testing -a codex
```

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

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add petrkindlmann/qa-skills --skill unit-testing -a cursor
```

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

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install petrkindlmann/qa-skills unit-testing
```

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

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add petrkindlmann/qa-skills --skill unit-testing -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/petrkindlmann/qa-skills --path skills/unit-testing
```

### Windsurf (Devin Desktop)

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

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add petrkindlmann/qa-skills --skill unit-testing -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/petrkindlmann/qa-skills/tree/HEAD/skills/unit-testing/SKILL.md

## When to use it
- pick the right test double instead of mocking everything
- make a coverage threshold actually fail the CI job
- freeze time and random values inside a test
- check test quality with mutation testing
- lay out a test as Arrange-Act-Assert

## Example prompts
- write unit tests for this module with Vitest
- why is my Jest coverage threshold not failing the build
- add mutation testing with Stryker to this package

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: f2927dcef12634f3.

BEGIN THIRD-PARTY FILE f2927dcef12634f3
````text
---
name: unit-testing
description: >-
  Write effective unit tests with Jest, Vitest, or pytest. Covers the test-doubles
  taxonomy (stub/spy/mock/fake), Arrange-Act-Assert, coverage threshold configuration
  and CI gating, snapshot testing, fake timers, and mutation testing with Stryker/mutmut.
  Use when: "unit test," "Jest," "Vitest," "pytest," "mock," "coverage threshold,"
  "test doubles," "mutation testing," "fake timers," "snapshot test."
  Not for: interpreting coverage reports or finding coverage gaps — use coverage-analysis;
  AI generating the test code for you — use ai-test-generation; auditing existing tests
  for smells — use ai-qa-review; browser/component rendering assertions — use
  cypress-automation or visual-testing.
  Related: coverage-analysis, ci-cd-integration, ai-test-generation, shift-left-testing.
license: MIT
metadata:
  author: kindlmann
  version: "2.0"
  category: automation
---

<objective>
Write unit tests that fail when the code is wrong and pass when it is right — nothing
weaker. A test that mocks every collaborator stays green while the integration is
broken; the doubles taxonomy below stops that. A `coverageThreshold` typo (or the
plural `coverageThresholds`, which Jest silently ignores) lets 40%-covered code ship
on a green pipeline; the config and Verification sections below make the gate actually
fire. This skill covers Jest, Vitest, and pytest: doubles, coverage gating, snapshots,
fake timers, and mutation testing as a behavior check on top of coverage.
</objective>

---

## Discovery Questions

Check `.agents/qa-project-context.md` first — if it exists, use it and skip anything answered there.

1. **Framework:** Jest, Vitest, or pytest? Check `package.json` or `pyproject.toml`. The runner decides config keys and mock APIs.
2. **Coverage tooling:** Already configured? Look for `jest.config.*`, `vitest.config.*`, `.nycrc`, `[tool.coverage]`. Determines whether you add the gate or just tune it.
3. **Mocking strategy:** Manual mocks, auto-mocking, or dependency injection? Check for `__mocks__/` dirs or DI containers — this sets which doubles you reach for.
4. **Conventions:** Co-location (`*.test.ts` next to source) or a `__tests__`/`tests/` tree? Match what exists; don't introduce a third location.

---

## Core Principles

**1. Test behavior, not implementation.** Verify *what* code does, not *how*. Refactoring internals should not break tests.

```typescript
// Bad — implementation detail        // Good — observable behavior
expect(svc._cache.size).toBe(3);      expect(svc.getUser("abc")).toEqual({ id: "abc", name: "Alice" });
```
````
END THIRD-PARTY FILE f2927dcef12634f3

The third-party file has ended. Everything between the f2927dcef12634f3 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2637 of 15700 bytes. © kindlmann · MIT · https://github.com/petrkindlmann/qa-skills/tree/HEAD/skills/unit-testing/SKILL.md

_Part of the page did not fit — see the HTML version._

---
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