Vitest in Core
Use the repository harness as the source of truth. Core currently resolves
Vitest 5.0.5 from bun.lock; verify the exact version before relying on a newly
introduced API.
Authority and test surface
Read these before changing tests or configuration:
vitest.config.mts — include globs, aliases, Node default environment,
timeouts, mock clearing, setup, and the supported V8 coverage provider.
tests/setup/unit-env.ts — safe env defaults and browser shims.
scripts/verify/unit-tests.mjs — the full unit gate and platform behavior.
docs/ai/rules/testing.md — repository-wide test and CI policy.
.next-docs/01-app/02-guides/testing/vitest.mdx when testing Next.js code.
Do not use bun test; that selects Bun's test runner. Use Vitest through the
committed scripts or bunx vitest.
Commands
# Full CI-equivalent unit suite with the supported V8 coverage provider
bun run test:unit
# Focused file or directory while iterating
bunx vitest run tests/unit/path/to/example.test.ts
# Focused test name
bunx vitest run tests/unit/path/to/example.test.ts -t "expected behavior"
# Watch a focused surface
bunx vitest tests/unit/path/to/example.test.ts
# Structured failure report and targeted reruns
bun run test:unit:feedback
Workflow
- Choose the boundary. Test observable behavior at the smallest stable
public boundary. Prefer pure logic/unit coverage; use Playwright when the
claim depends on a real browser, routing, hydration, or an async Server
Component.
- Place the test in an included path. Match the existing
tests/unit,
packages/api/tests/unit, or packages/auth conventions from
vitest.config.mts; do not invent a disconnected test root.
- Control the environment. The default is
node. Add
// @vitest-environment jsdom only to files that need DOM APIs, and clean up
rendered components and mutated globals.
- Mock boundaries, not the unit's internals. Remember that
vi.mock is
hoisted. Use vi.hoisted for shared mock state, dynamic imports when a module
must load after mocks, and vi.importActual for intentional partial mocks.
- Reset all changed state.
clearMocks: true clears call history but does
not restore globals, timers, dates, env values, or spy implementations. Undo
those changes in hooks.
- Run focused, then full. Iterate on the smallest file/name filter and run
bun run test:unit before handoff.
Core-specific guardrails
- Unit tests must not call live Supabase, Stripe, Resend, Payload, or network
services. Use deterministic fakes at repository boundaries.
- Keep real credentials out of tests. The committed env defaults are
placeholders and intentionally clear the Supabase service-role key.
- Assert behavior and durable contracts, not incidental class strings or
implementation order unless that order is itself the contract.
- Prefer explicit test data builders/helpers over large untyped fixture blobs.
- Avoid
.only; use .skip/.todo only with a documented reason and no hidden
loss of required coverage.
- Coverage runs under Node with exact-version
@vitest/coverage-v8 and produces
measured line, statement, branch and function reports. The default denominator
is imported source under the configured filters, not all repository files.
Do not infer whole-repository coverage or retrofit measured percentages onto
historical fallback reports. Missing, malformed or zero-total reports are
unavailable. The isolated-suite regression proves remapping and threshold
enforcement; keep it passing when changing providers or worker behavior.
Checklist
Provenance
See references/upstream.md for the reviewed upstream
source, version compatibility decision, license, and refresh workflow.
1---2name: vitest3description: Write, review, filter, mock, and debug Core unit tests with the repository's installed Vitest 5 configuration. Use for tests under Core's Vitest include paths, `vi.mock`/spies/timers, jsdom component tests, coverage output, focused reruns, or unit-test failures. Do not use for browser E2E flows or async Next.js Server Components.4metadata:5 source: https://skillmd.com/skills/asymmetric-al/vitest6---78# Vitest in Core910Use the repository harness as the source of truth. Core currently resolves11Vitest 5.0.5 from `bun.lock`; verify the exact version before relying on a newly12introduced API.1314## Authority and test surface1516Read these before changing tests or configuration:1718- `vitest.config.mts` — include globs, aliases, Node default environment,19 timeouts, mock clearing, setup, and the supported V8 coverage provider.20- `tests/setup/unit-env.ts` — safe env defaults and browser shims.21- `scripts/verify/unit-tests.mjs` — the full unit gate and platform behavior.22- `docs/ai/rules/testing.md` — repository-wide test and CI policy.23- `.next-docs/01-app/02-guides/testing/vitest.mdx` when testing Next.js code.2425Do not use `bun test`; that selects Bun's test runner. Use Vitest through the26committed scripts or `bunx vitest`.2728## Commands2930```bash31# Full CI-equivalent unit suite with the supported V8 coverage provider32bun run test:unit3334# Focused file or directory while iterating35bunx vitest run tests/unit/path/to/example.test.ts3637# Focused test name38bunx vitest run tests/unit/path/to/example.test.ts -t "expected behavior"3940# Watch a focused surface41bunx vitest tests/unit/path/to/example.test.ts4243# Structured failure report and targeted reruns44bun run test:unit:feedback45```4647## Workflow48491. **Choose the boundary.** Test observable behavior at the smallest stable50 public boundary. Prefer pure logic/unit coverage; use Playwright when the51 claim depends on a real browser, routing, hydration, or an async Server52 Component.532. **Place the test in an included path.** Match the existing `tests/unit`,54 `packages/api/tests/unit`, or `packages/auth` conventions from55 `vitest.config.mts`; do not invent a disconnected test root.563. **Control the environment.** The default is `node`. Add57 `// @vitest-environment jsdom` only to files that need DOM APIs, and clean up58 rendered components and mutated globals.594. **Mock boundaries, not the unit's internals.** Remember that `vi.mock` is60 hoisted. Use `vi.hoisted` for shared mock state, dynamic imports when a module61 must load after mocks, and `vi.importActual` for intentional partial mocks.625. **Reset all changed state.** `clearMocks: true` clears call history but does63 not restore globals, timers, dates, env values, or spy implementations. Undo64 those changes in hooks.656. **Run focused, then full.** Iterate on the smallest file/name filter and run66 `bun run test:unit` before handoff.6768## Core-specific guardrails6970- Unit tests must not call live Supabase, Stripe, Resend, Payload, or network71 services. Use deterministic fakes at repository boundaries.72- Keep real credentials out of tests. The committed env defaults are73 placeholders and intentionally clear the Supabase service-role key.74- Assert behavior and durable contracts, not incidental class strings or75 implementation order unless that order is itself the contract.76- Prefer explicit test data builders/helpers over large untyped fixture blobs.77- Avoid `.only`; use `.skip`/`.todo` only with a documented reason and no hidden78 loss of required coverage.79- Coverage runs under Node with exact-version `@vitest/coverage-v8` and produces80 measured line, statement, branch and function reports. The default denominator81 is imported source under the configured filters, not all repository files.82 Do not infer whole-repository coverage or retrofit measured percentages onto83 historical fallback reports. Missing, malformed or zero-total reports are84 unavailable. The isolated-suite regression proves remapping and threshold85 enforcement; keep it passing when changing providers or worker behavior.8687## Checklist8889- [ ] The test exercises an observable contract at the right test layer.90- [ ] The file is inside a configured include path and uses the correct env.91- [ ] Mocks intercept external boundaries and respect Vitest hoisting.92- [ ] Globals, env, timers, dates, spies, DOM, and module state are isolated.93- [ ] Assertions are deterministic and do not depend on network or test order.94- [ ] Focused tests pass, then `bun run test:unit` passes.95- [ ] Coverage output is described without overstating its current signal.9697## Provenance9899See [references/upstream.md](references/upstream.md) for the reviewed upstream100source, version compatibility decision, license, and refresh workflow.