vitest-dev/vitest
github.com/vitest-dev/vitest ↗ · 3067 files · 8.6 MB
Vitest Next generation testing framework powered by Vite.
Overview
Vitest is an ESM-first testing framework for JavaScript and TypeScript applications that reuses Vite configuration, resolution, transforms, and plugins. At commit 4ee66c021e0592c886dbab727f0f8da9366f99ab, its Node coordinator resolves projects, schedules isolated workers or browser sessions, and aggregates test results, snapshots, coverage, and reports. Its distinctive combination is a familiar assertion and mocking API with configurable execution environments, real-browser testing, and a live Vue results interface.
System map
The system has a Node coordinator, interchangeable execution workers, browser infrastructure, and an optional Vue interface. Configuration resolution precedes server attachment and test scheduling. Persistent state is held in filesystem artifacts and caches, while active task state belongs to coordinator and client state managers. Distribution consists of built package entrypoints plus a separately built documentation site.
- The executable vitest.mjs loads dist/cli.js; its source entrypoint calls createCLI().parse(), while package exports separately expose built public APIs.
- createVitest constructs Logger, VitestPackageInstaller, PluginHarness, and Vitest around resolveConfig; setup failures close the instance before rethrowing.
- resolveConfig installs capture, test-config, core, and browser-loader plugins into Vite resolution, then resolves Vitest configuration and project entries.
- Vitest._start attaches root and project servers; _setRootConfig owns StateManager, VitestCache, SnapshotManager, tracing, resolver, and transform-service instances.
- Pool worker selection supports forks, threads, VM variants, TypeScript checking, and a custom poolRunner; fork workers launch child processes with advanced IPC serialization.
- Browser support contributes configuration, plugins, parent creation, and RPC to a core-created Vite server; Playwright and preview providers have separate package entrypoints.
- The Vue UI mounts through client/main.ts and chooses a live WebSocket client or static report client; live transport uses birpc and flatted serialization.
- Root scripts provide recursive package builds, linting, typechecking, and split test suites; VitePress builds documentation, and Netlify publishes docs/.vitepress/dist using pnpm ci:docs.
Feature catalog
The inspected public surface spans test authoring, command-line execution, project selection, browser testing, and result inspection. Assertions, mocking, fixtures, and snapshots integrate with the same runner lifecycle. Coverage and reporter outputs support both local feedback and CI consumption. The catalog groups related capabilities into eight areas and is bounded by the inspected sources.
- CLI commands include run, related, watch/dev, bench, init, doctor, and list; init accepts only browser, while list branches between collected tests and files-only output.
- Public APIs export describe/it/test/suite, before/after and around hooks, completion hooks, and artifact recording; test.extend supports fixture definitions with scoped dependency restrictions.
- The public assertion surface exports Chai, assert, expect, and vi; vi exposes fake timers, spies, and module mocking, and built-in environments include node, jsdom, happy-dom, and edge-runtime.
- Snapshots support external files, inline source updates, and raw files; custom composable matchers include standard, file, and domain snapshot helpers.
- Projects can nest through container configurations and expand into browser-instance and benchmark variants; CLI selection includes related files, filename/location filters, and sequencer-based sharding.
- Browser testing integrates provider initialization and bounded session scheduling, with registered commands for filesystem operations, screenshots, screenshot matching, and trace recording.
- Coverage supports v8, Istanbul, and a custom provider module; built-in browser loading selects a /browser provider entrypoint, and run finalization generates and reports coverage.
- Results are available through dashboard, file details, coverage, browser, and trace UI components, plus JSON, JUnit, TAP, GitHub Actions, and blob reporters; mergeReports replays saved runs.
Data flow
CLI arguments become resolved Vite and Vitest configuration before producing project-specific test specifications. Execution transports module requests toward the coordinator and task updates back from workers. Snapshot state remains local to a running file until its summary is aggregated, while result caches retain scheduling information across runs. The UI maintains its own reactive representation of coordinator events.
- CLI normalization converts exclude into cliExclude and enables locations for colon filters; prepareVitest sets TEST/VITEST and default NODE_ENV, then passes options into createVitest.
- Project definitions become resolved entries; undefined definitions use the root entry, nested containers contribute tracked configuration paths, and duplicate project names are checked.
- Worker fetch requests enter createMethodsRPC.fetchModule and project._transformService.fetch; returned externalizations, temporary paths, and direct-fetch durations populate project metadata.
- collectTests creates a file task, clears collector context, runs setupFiles, imports the test module, and assembles its collected tasks; specifications carry location, name, ID, and tag filters.
- resolveTestRunner wraps task-update callbacks with worker RPC; coordinator handlers route collection and updates either directly into StateManager or through _testRun, depending on collection mode.
- SnapshotClient stores SnapshotState by filepath, forwards matcher input into state.match, and finishes through state.pack; worker snapshotSaved results are added to the coordinator SnapshotManager.
- ResultsCache writes results.json under config.dir with versioned entries keyed by project name and root-relative filepath; each retained result stores duration and failure status.
- The live UI receives collected task trees, result packs, logs, artifacts, and completion events; it updates client state and explorer state, while static reports use a separate client factory.
Behavior traces
Three core flows were followed across their implementing files: CLI startup, primary test execution, and snapshot persistence. Additional traces cover UI authentication, report replay, and shutdown. Ordering matters because configuration, servers, workers, reporters, and filesystem artifacts have separate lifetimes. These are source-derived walkthroughs, not observed runtime executions.
- Startup begins vitest.mjs → cli.ts → createCLI().parse() → run/start → startVitest → prepareVitest; run preserves watch mode when --watch is supplied.
- prepareVitest → createVitest → resolveConfig → new Vitest → _start → _setRootConfig → _attachRootServer → _attachProjectServers establishes the coordinator before startVitest invokes start or an alternate maintenance mode.
- Vitest.start initializes coverage and reporters, discovers specifications, optionally preparses them, populates file statistics, and calls runFiles; empty discovery has special changed/related watch handling.
- runFiles creates the pool, clears invalidations/snapshot/errors, initializes global setup, and calls pool.runTests; worker run resolves runner/environment/coverage concurrently, then startTests collects modules and runs suites.
- Snapshot persistence follows TestRunner.onBeforeRunSuite → SnapshotClient.setup → SnapshotState.create, then matcher delegation → SnapshotClient.match; suite completion calls finish → pack → save and reports snapshotSaved.
- SnapshotState.save selects external, inline, or raw persistence; external saveSnapshotFile sorts and serializes entries, skips identical content, and NodeSnapshotEnvironment creates directories and writes UTF-8.
- UI login validates ?token=, sets an HttpOnly SameSite=strict cookie, redirects to the clean UI base, and injects the API token into authorized HTML; WebSocket upgrades separately require isValidApiRequest.
- Report replay reads blobs, reconstructs specifications, replays file events, and merges coverage; shutdown waits for the active run, tears down global setup in reverse project order, closes the pool, then closes project servers.
Testing signals
Tests and CI were inspected, not executed; test existence does not establish a passing result. The sampled tests exercise runner behavior, snapshots, API authentication, browser permissions, and lifecycle regressions. CI definitions provide platform and Node-version coverage, with separate browser jobs. Inspection also revealed conditional skips and typecheck exclusions, so the inventory is bounded rather than exhaustive coverage.
- Root pnpm test selects the unit threads script; unit configuration also defines forks and vmThreads projects, virtual-module plugins, snapshot-path customization, coverage, and typechecking.
- E2E suites use Vitest and runInlineTests; restart-coalescing.test.ts requests three simultaneous restarts and verifies a subsequent rerun remains functional.
- Snapshot CI tests spawn the CLI with CI enabled and expect a missing-snapshot failure, then disable CI and expect snapshot creation; these expectations were inspected only.
- Token tests cover reuse, empty or whitespace content, publication consistency, and intermediate-file cleanup; Playwright UI tests cover unauthenticated HTML/coverage rejection, token-file serving denial, and cookie bootstrap.
- Browser permission tests disable allowExec and allowWrite, then check filesystem-command failures, suppressed attachments, and blocked snapshot evaluation/saving; UI tests separately exercise disabled writes and execution.
- The large scoped-fixture suite checks invalid fixture dependencies, but installs a beforeEach skip when rolldownVersion is present, limiting what that suite exercises on that branch.
- CI defines Linux unit/e2e/coverage jobs on Node 24/26, a Node 22 e2e floor, macOS e2e, Windows suite legs, and separate Windows/Linux browser jobs; lint CI checks generated artifacts and UI types.
- Root TypeScript checking excludes e2e, browser, TypeScript-test, docs, and example paths; node-runner instead declares node --test, and UI client checking uses a separate vue-tsc script.
Risk map
The inspected sensitive boundaries include authenticated HTTP/WebSocket APIs, browser filesystem commands, executable snapshots, child processes, and persistent user-data files. Several paths already contain explicit permission checks and regression tests. The observations below identify review hotspots and existing safeguards, not confirmed vulnerabilities. Lifecycle and coverage hypotheses require targeted execution in a separately authorized environment.
- API tokens persist first in a platform-specific user-data directory, with workspace node_modules/.vitest fallback; creation uses UUIDs and restrictive modes, while configuration adds the token filename to Vite's deny list.
- API authentication uses a query token with timingSafeEqual; UI authentication additionally accepts a year-long HttpOnly strict cookie and injects the token into authorized HTML, making token-handling paths security-sensitive.
- Non-middleware API hosts other than localhost/127.0.0.1 default write and execute capabilities off; explicit settings remain effective, and API rerun, file-save, and snapshot-update handlers apply separate capability checks.
- Browser filesystem commands resolve paths against project.root and check file access; writes/removals additionally assert write permission, while browser RPC requires both project and root capabilities for CDP.
- Snapshot loading can execute file content through new Function('exports', content); Node raw snapshots accept absolute paths, and SnapshotClient documents that its same-file collision rejection is best-effort.
- Execution crosses process and command boundaries: fork workers receive env/execArgv, Git discovery invokes git through tinyexec, and interactive missing-dependency handling can call installPackage after confirmation.
- Lifecycle ordering is a coupling hotspot: source comments identify overlapping restarts and browser reconnection during shutdown as failure mechanisms; serialization of restarts and pool-before-server closure are intended safeguards.
- Hypothesis: relying on root typecheck or the scoped-fixture suite alone can miss branch-specific regressions, because several test trees are excluded and scoped-fixture tests skip under rolldownVersion. (inferred)
Extension points
Extension contracts span Vite plugins, runners, worker factories, environments, coverage providers, reporters, and browser commands. Most are configuration-selected and resolved before or during execution. Coordinator and worker hooks occupy different runtime boundaries, so extensions must preserve serialization and lifecycle rules. Snapshot customization additionally separates matching from storage.
- configureVitest receives project, vitest, injectTestProjects, and defineCacheKeyGenerator; it runs before reporter initialization, and resolved configuration mutations are not automatically re-resolved.
- config.runner selects a default-exported runner constructor; resolveTestRunner requires importFile, injects moduleRunner, loads serializers/diff options, and wraps callbacks to preserve Vitest RPC reporting.
- Custom worker execution plugs into project.config.poolRunner through a matching name and createPoolWorker(options), after built-in worker choices are exhausted.
- Custom environments resolve from a path or vitest-environment-{name}; loading branches between native and Vite module runners and validates the default export and supplied transformMode.
- Coverage extension modules supply getProvider and optional start/take/stopCoverage hooks; customProviderModule loads through the supplied loader and must provide a default export.
- Browser commands extend a built-in registry through config.browser.commands with identifier validation; triggerCommand prefers project commands, then parent commands, and rejects unsupported names.
- ReportersMap is the built-in output registry, while config.sequence.sequencer supplies shard and sort behavior before execution grouping; these are separate presentation and scheduling extension boundaries.
- Snapshot customization includes composable matcher helpers and storage environments; SnapshotState.create can consume readSnapshotFileData directly instead of evaluating text, and NodeSnapshotEnvironment accepts a custom snapshot-directory name.
Contributor handoff
Tests and CI were inspected, not executed, and this brief must not be treated as a passing validation record. Begin edits with the nearest instructions and the implementing runtime boundary, then choose the corresponding test project. Built distribution files, generated documentation, helper defaults, and conditional skips are important interpretation traps. The present assignment authorizes source inspection only; development commands below describe future workflows requiring appropriate task authorization.
- Read AGENTS.md and CONTRIBUTING.md before contribution work; external PRs, issues, or comments require manual operator approval, and contribution policy requires real-person ownership and AI disclosure.
- Use repository pnpm scripts and the declared Node range; package.json pins pnpm@11.28.2 and exposes build, lint, typecheck, unit, e2e, coverage, and browser checks.
- For core changes, first read create.ts, resolveConfig.ts, and the relevant core.ts lifecycle; worker changes require runtime/runBaseTests.ts and runner/run.ts because scheduling and test callbacks live in different processes.
- Rebuild before executing tests against package changes: public exports resolve dist, mocker is not inlined, runtime workers are built separately, and watch builds omit declaration bundling.
- Choose the smallest relevant filtered test command without an extra --; root test covers the unit threads selection, whereas browser execution has a separate test:browser:playwright script.
- Use runInlineTests for mutable multi-file setups; runVitest defaults cache off, one worker, watch off, verbose reporting, and NO_COLOR, with $cliOptions applied as overrides.
- Root typecheck does not cover all test trees or UI client code; CLI option edits require regenerating cli-generated.md, and CI checks stale build artifacts plus separate UI typechecking.
- Keep mutable fixtures isolated, use test-utils edits for watch tests, serialize Git-dependent fixtures, normalize Windows paths, and check focused tests manually; formatting uses oxfmt and fixture trees are excluded.
Languages
| Language | Files | Share of source |
|---|---|---|
| TypeScript | 2099 | 86% |
| JavaScript | 264 | 11% |
| Markdown | 264 | docs/config |
| JSON | 153 | docs/config |
| Vue | 73 | 3% |
| YAML | 29 | docs/config |
| CSS | 14 | docs/config |
| HTML | 14 | docs/config |
Start reading here
Probable source entrypoint: packages/ — inferred from the directory tree and manifest, not the upstream docs.
Source roots
packages/ (682 files)
Repository structure
| Top-level path | Files |
|---|---|
test/ | 1968 |
packages/ | 682 |
docs/ | 293 |
examples/ | 56 |
.github/ | 32 |
scripts/ | 7 |
patches/ | 4 |
.claude/ | 2 |
Docs found: AGENTS.mdCONTRIBUTING.mdREADME.mddocs/AGENTS.mddocs/api/advanced/artifacts.mddocs/api/advanced/import-example.mddocs/api/advanced/metadata.mddocs/api/advanced/plugin.mddocs/api/advanced/reporters.mddocs/api/advanced/runner.md
Package
package.json — @vitest/monorepo v5.0.3, 22 declared dependencies.
@rollup/plugin-commonjs@rollup/plugin-json@rollup/plugin-node-resolve@types/node@types/semverbumppchangelogithubknipoxfmtoxlintpremoverollup
CI & config entrypoints
README.md— Repository readmeAGENTS.md— Agent instructionstest/ui/playwright.config.ts— Playwright e2e configtest/unit/vite.config.ts— Vite configtest/typescript/fixtures/source-error/vite.config.ts— Vite configtest/workspaces/space_1/vite.config.ts— Vite configtest/workspaces/space_3/vite.config.ts— Vite configtest/browser/fixtures/inline-script/vite.config.ts— Vite configtest/workspaces-browser/space_1/vite.config.ts— Vite configtest/e2e/dts/config/vite.config.ts— Vite config
Structural health signals
Average score 6.8/10 across 96 analyzed source files; 40 hotspots surfaced.
packages/browser-playwright/src/playwright.ts— 866 lines, score 4.5 (Large file, Deep nesting)packages/vitest/src/runtime/runner/types.ts— 1583 lines, score 5 (Large file, Deep nesting)packages/vitest/src/node/ast-collect.ts— 614 lines, score 5.2 (Large file, Deep nesting)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
4ee66c021e052026-10-02 — fix(runner): don't cache failed fixture setups (fix #11237) (#11238)af903c65e4d12026-10-02 — fix(ui): store module graph once per environment (#11421)a627be498c332026-10-02 — fix(ui): simplify explorer filtering + fix nested tests when search matches a suite (#11262)b4e79fd7a3c72026-10-02 — fix(expect): fix `Map` and `Set` deep equality in some assertions (#11402)b0f2b3bb9d812026-10-02 — fix: track project files and mocks with --changed (#11432)