# vitest

Testing instructions for coding agents writing, running, and debugging Vitest suites in TypeScript projects.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 186 installs · ★ 107 repo stars
- Author: PaulRBerg
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/PaulRBerg/agent-skills/tree/HEAD/skills/vitest/SKILL.md
- Updated: 2026-10-24
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/paulrberg-vitest

## What it does

This skill directs how coding agents interact with Vitest in TypeScript codebases. It explicitly forbids agents from adding global test variables or `jsdom` without prior project setup. Existing configuration files govern the test structure. The agent must inspect nearby test files first.

Bug fixing follows a strict pattern. Failure precedes the fix. The agent reproduces the issue with a failing test before writing any code changes. Mocks isolate external system boundaries, leaving the unit logic intact. For Effect codebases, the skill requires `@effect/vitest` conventions such as `it.effect` and TestClock.

Test execution stays focused. The agent runs the narrowest package script available instead of triggering the whole suite. It resorts to `nlx vitest run` only when no project script exists. Passing runs conclude with explicit verification markers.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add PaulRBerg/agent-skills --skill vitest -a claude-code
```

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

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add PaulRBerg/agent-skills --skill vitest -a codex
```

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

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add PaulRBerg/agent-skills --skill vitest -a cursor
```

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

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install PaulRBerg/agent-skills skills/vitest
```

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

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add PaulRBerg/agent-skills --skill vitest -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/PaulRBerg/agent-skills --path skills/vitest
```

### Windsurf (Devin Desktop)

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

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add PaulRBerg/agent-skills --skill vitest -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/PaulRBerg/agent-skills/tree/HEAD/skills/vitest/SKILL.md

## When to use it
- write component and unit tests for Vitest in TypeScript
- reproduce bugs with failing tests before applying fixes
- isolate external boundaries with targeted Vitest mocks
- structure Effect test suites using `@effect/vitest` conventions

## Example prompts
- Write Vitest unit tests for the token parser in `src/token.ts`.
- Reproduce the checkout calculation bug with a failing test first.
- Run the focused test suite for the updated auth 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: 1b2484c1cbcf973b.

BEGIN THIRD-PARTY FILE 1b2484c1cbcf973b
```text
---
name: vitest
description:
  "Use for Vitest in TypeScript projects (Node, bun, React/Next.js, Effect): write, run, or debug unit/component tests,
  mocks, testing utilities, and coverage."
---

# Vitest

Repository configuration, projects, setup, imports/globals, environments, aliases, test placement, and cleanup own the
test contract. Inspect them and nearby tests before adding generic patterns. Do not add globals, jsdom, coverage, new
setup, or browser mode by default.

## Workflow

Define the behavior or regression. Test its observable public result. Mock system boundaries rather than the behavior
under test. Follow local fixture and cleanup ownership. In Effect repositories, use established `@effect/vitest`
conventions such as `it.effect`, Layers, and TestClock rather than generic replacements. For a bug fix, reproduce the
failure before relying on a passing result when practical.

Read [patterns](references/testing-patterns.md) for component, async, fixture, snapshot, tag, or browser questions. Read
[mocking](references/mocking.md) for module, timer, spy, or global boundaries. Read
[configuration](references/configuration.md) for projects, migration, coverage, or reporter selection. Read
[troubleshooting](references/troubleshooting.md) for hangs, discovery, resolution, or flaky state.

For test changes, run the narrowest established command for the changed behavior, then the affected package suite only
when shared setup or contracts changed. Use `nlx vitest run` only when no project recipe or script exists. Reuse passing
results until new edits, failures, or unresolved concerns justify another run.

Completion requires a meaningful passing focused test under repository configuration and concise command/result evidence
for test changes. A read-only explanation instead requires supporting configuration or API evidence. Do not add or run
tests merely to satisfy the change workflow. When red-before-green evidence exists, use `### 🧪 Regression covered`.
Otherwise, use `### 🧪 Tests verified` for executed tests.
```
END THIRD-PARTY FILE 1b2484c1cbcf973b

The third-party file has ended. Everything between the 1b2484c1cbcf973b 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.

© PaulRBerg · MIT · https://github.com/PaulRBerg/agent-skills/tree/HEAD/skills/vitest/SKILL.md

## Similar
- [vitest-skill](https://affpapa.org/en/nevibecode/skills/vitest-skill.md) — skill · 506 installs
- [vitest-testing-patterns](https://affpapa.org/en/nevibecode/skills/vitest-testing-patterns.md) — skill · 373 installs
- [vitest-testing](https://affpapa.org/en/nevibecode/skills/vitest-testing.md) — skill · 1300 installs
- [vitest-expert](https://affpapa.org/en/nevibecode/agents/vitest-expert.md) — subagent · ★ 1029 repo stars
- [safe-action-testing](https://affpapa.org/en/nevibecode/skills/safe-action-testing.md) — skill · 1200 installs
- [vitest-testing-expert](https://affpapa.org/en/nevibecode/agents/vitest-testing-expert.md) — subagent · ★ 763 repo stars

## Other versions with the same name
- [vitest · antfu](https://affpapa.org/en/nevibecode/skills/vitest.md) — 48600 installs
- [vitest · jezweb](https://affpapa.org/en/nevibecode/skills/jezweb-vitest.md) — 1800 installs
- [vitest · pproenca](https://affpapa.org/en/nevibecode/skills/pproenca-vitest.md) — 7800 installs

_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
