# Vitest Runner

> Run Vitest tests and parse results into actionable output.

- Skill: `notque/vitest-runner` (Agent Skill)
- Install (CLI): `npx skillmds@latest add notque/vitest-runner`
- Raw SKILL.md: https://api.skillmd.com/api/skills/notque/vitest-runner/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: notque (https://skillmd.com/u/notque)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/notque/vitest-runner

---


# Vitest runner

Run existing Vitest tests and report results. A check-only request does not authorize changing tests, assertions, dependencies, or configuration.

## Run

Read repository instructions and package scripts. Check `package.json`, `vitest.config.*`, and `vite.config.*` to confirm Vitest and its test configuration. Use the installed project version; avoid implicit npx downloads. If Vitest is unavailable, report setup needed rather than installing it.

Use the repository test command or these defaults. Always use `run`; bare `vitest` can enter watch mode.

| Scope | Command |
|---|---|
| Whole configured suite | `npx vitest run --reporter=verbose 2>&1` |
| File or directory | `npx vitest run path/to/test.ts 2>&1` |
| Test-name pattern | `npx vitest run -t "pattern" 2>&1` |
| Requested coverage | `npx vitest run --coverage 2>&1` |

Capture the process exit code and full output. Report pass/fail, checked scope, passed/failed/skipped counts, and duration. For failures retain the file, full test name, assertion difference, and relevant stack location. Keep complete logs available; show useful excerpts instead of every passing test. Nonzero exit is failure, including discovery or tool failures; partial output is not a passing run.

## Recovery

- **Vitest missing/node_modules absent:** inspect dependencies. Setup may require `npm install` or `npm install -D vitest`; use the repository package manager during authorized setup.
- **No test files:** check file naming (`*.test.ts`, `*.spec.ts`, `*.test.js`) and configured include/exclude globs. Report discovery failure; do not change config to mask it.
- **Missing DOM environment:** inspect `environment` for `jsdom` or `happy-dom`. Suggest the matching devDependency (`npm install -D jsdom` or `npm install -D happy-dom`); `@testing-library/jest-dom` adds matchers, not an environment.
- **Out of memory:** diagnose with directory batches such as `npx vitest run src/unit/`, `--pool=forks`, or `--shard=1/N` when supported by the installed version. A full-suite claim requires all batches/shards; a diagnostic subset is not full verification.
- **Failing assertions:** report the mismatch. When fixing is authorized, determine whether implementation or test is wrong; never weaken assertions merely to make the run green.