Vitest
Use this skill when work touches Vitest: writing/running tests, config, mocks/snapshots, coverage, browser mode, projects/pools, reporters, or migrating from Jest / Vitest 3.
Workflow
- Inspect the local Vitest surface:
- Package versions:
vitest and aligned @vitest/* (snapshot 4.1.10). Node ^20 || ^22 || >=24. Vite peer ^6 || ^7 || ^8.
- Config: dedicated
vitest.config.* (overrides vite.config entirely) vs test: {} inside Vite config.
- Scripts: prefer
vitest run for CI; do not use bun test (Bun’s runner) when the project uses Vitest — use bun run test / bunx vitest.
- Environment:
node (default) vs jsdom / happy-dom vs Browser Mode projects.
- For day-to-day how-to, follow usage-guide.md first.
- Refresh docs when versions drift or the task is browser/coverage/migration. Start from source-map.md.
- Route deeper detail:
- Config, CLI, test API, environments, setup: config-cli-api.md.
vi mocks, timers, env stubs, snapshots: mocking-snapshots.md.- Coverage, browser mode, projects, pools, reporters: coverage-browser-projects.md.
- Jest / Vitest 3 → 4: migration.md.
- Prefer Vitest 4.x APIs (
projects, maxWorkers, browser provider factories). Keep @vitest/* packages on the same version as vitest.
- Verify with the narrowest useful command (
vitest run path -t "name", coverage, or browser project).
Core Judgment
- Vitest is a Vite-powered test runner with a Jest-compatible API — not Bun’s built-in
bun test.
- CI / hooks: always
vitest run (or --run). Plain vitest watches and hangs non-interactively unless CI/non-TTY forces run.
- Import from
vitest unless globals: true. Prefer explicit imports for agent clarity.
vi.mock / vi.hoisted are hoisted — factories cannot close over non-hoisted locals.- Concurrent tests + snapshots/asserts: use context
expect from the test callback, not global expect.
- Default pool is
forks. Prefer it over threads when native addons misbehave.
- A dedicated
vitest.config.* ignores vite.config options — use mergeConfig when extending Vite plugins/aliases.
- Coverage is root-only in projects; set
coverage.include explicitly (v4 no longer has coverage.all).
- Browser Mode is not
environment: 'jsdom' — use browser.enabled + provider packages.
- Vite transforms tests but does not typecheck — use optional
typecheck or project tsc separately.
Verification
Prefer repository-owned commands. For meaningful Vitest work, cover the relevant subset:
bunx vitest --version and confirm @vitest/* version alignment.- Focused
vitest run <file> -t "<name>" (or :line filter).
- Snapshot updates only with deliberate
-u / watch u; review diffs.
- Coverage:
vitest run --coverage when thresholds or reports matter.
- Browser project: headless chromium smoke when UI/component tests change.
- Migration: no remaining
workspace, string browser providers, poolOptions, or test(name, fn, options).
Report which checks ran, which did not, and any Vitest version assumptions that remain.
1---2name: vitest3description: Build, review, debug, configure, migrate, teach, or plan Vitest testing with current docs and a full usage guide. Use for vitest, vitest.config, defineConfig from vitest/config, describe/it/test/expect, vi mocks, snapshots, coverage (@vitest/coverage-v8), browser mode (@vitest/browser-playwright), projects, pools/maxWorkers, reporters, UI, bench, typecheck, and Jest or Vitest 3 to Vitest 4 migration.4---56# Vitest78Use this skill when work touches Vitest: writing/running tests, config, mocks/snapshots, coverage, browser mode, projects/pools, reporters, or migrating from Jest / Vitest 3.910## Workflow11121. Inspect the local Vitest surface:13 - Package versions: `vitest` and aligned `@vitest/*` (snapshot **4.1.10**). Node `^20 || ^22 || >=24`. Vite peer `^6 || ^7 || ^8`.14 - Config: dedicated `vitest.config.*` (overrides `vite.config` entirely) vs `test: {}` inside Vite config.15 - Scripts: prefer `vitest run` for CI; do **not** use `bun test` (Bun’s runner) when the project uses Vitest — use `bun run test` / `bunx vitest`.16 - Environment: `node` (default) vs `jsdom` / `happy-dom` vs Browser Mode projects.172. For day-to-day how-to, follow [usage-guide.md](references/usage-guide.md) first.183. Refresh docs when versions drift or the task is browser/coverage/migration. Start from [source-map.md](references/source-map.md).194. Route deeper detail:20 - Config, CLI, test API, environments, setup: [config-cli-api.md](references/config-cli-api.md).21 - `vi` mocks, timers, env stubs, snapshots: [mocking-snapshots.md](references/mocking-snapshots.md).22 - Coverage, browser mode, projects, pools, reporters: [coverage-browser-projects.md](references/coverage-browser-projects.md).23 - Jest / Vitest 3 → 4: [migration.md](references/migration.md).245. Prefer Vitest **4.x** APIs (`projects`, `maxWorkers`, browser provider factories). Keep `@vitest/*` packages on the **same version** as `vitest`.256. Verify with the narrowest useful command (`vitest run path -t "name"`, coverage, or browser project).2627## Core Judgment2829- Vitest is a **Vite-powered** test runner with a Jest-compatible API — not Bun’s built-in `bun test`.30- CI / hooks: always **`vitest run`** (or `--run`). Plain `vitest` watches and hangs non-interactively unless CI/non-TTY forces run.31- Import from `vitest` unless `globals: true`. Prefer explicit imports for agent clarity.32- `vi.mock` / `vi.hoisted` are **hoisted** — factories cannot close over non-hoisted locals.33- Concurrent tests + snapshots/asserts: use **context** `expect` from the test callback, not global `expect`.34- Default pool is **`forks`**. Prefer it over `threads` when native addons misbehave.35- A dedicated `vitest.config.*` **ignores** `vite.config` options — use `mergeConfig` when extending Vite plugins/aliases.36- Coverage is root-only in projects; set `coverage.include` explicitly (v4 no longer has `coverage.all`).37- Browser Mode is **not** `environment: 'jsdom'` — use `browser.enabled` + provider packages.38- Vite transforms tests but does **not** typecheck — use optional `typecheck` or project `tsc` separately.3940## Verification4142Prefer repository-owned commands. For meaningful Vitest work, cover the relevant subset:4344- `bunx vitest --version` and confirm `@vitest/*` version alignment.45- Focused `vitest run <file> -t "<name>"` (or `:line` filter).46- Snapshot updates only with deliberate `-u` / watch `u`; review diffs.47- Coverage: `vitest run --coverage` when thresholds or reports matter.48- Browser project: headless chromium smoke when UI/component tests change.49- Migration: no remaining `workspace`, string browser providers, `poolOptions`, or `test(name, fn, options)`.5051Report which checks ran, which did not, and any Vitest version assumptions that remain.
dobroslavradosavljevic