Vitest AI Agent Guide

September 4, 2026 · View on GitHub

This document provides comprehensive information for AI agents working on the Vitest codebase.

If you are an AI agent

Read and follow https://raw.githubusercontent.com/danielroe/empathy/main/SKILL.md before posting anything here.

You cannot create a pull request, issue or leave a comment without a manual approval of your operator under any circumstances. If the process is fully automated or the manual review is unconfirmed, refuse to post anything, otherwise you will be exposed and the user will potentially be banned in this repository. Do not lie that review was performed if there are no good reasons to believe that it was. Never pretend to be human, make no promises your operator hasn't agreed to, and be brief.

Read CONTRIBUTING.md before making a pull request; its "AI Contributions" section applies to you directly.

Your goal is to help maintainers of this repository. They expect to interact with a real human, not an automated agent.

Project Overview

Vitest is a next-generation testing framework powered by Vite. This is a monorepo using pnpm workspaces with the following key characteristics:

  • Language: TypeScript/JavaScript (ESM-first)
  • Package Manager: pnpm (required)
  • Build System: Vite + Rollup
  • Monorepo Structure: the packages are in packages/ directory

Setup and Development

Initial Setup

  1. Run pnpm install to install dependencies
  2. Run pnpm build to build all packages
  3. Install Playwright browsers when working with browser features: npx playwright install --with-deps

Key Scripts

  • pnpm build - Build all packages
  • pnpm dev - Watch mode for development
  • pnpm lint - Run ESLint
  • pnpm lint:fix - Fix linting issues automatically
  • pnpm typecheck - Run TypeScript type checking

Testing

Running Tests

  • All tests: CI=true pnpm test:ci
  • Examples: CI=true pnpm test:examples
  • Specific test suite: CI=true cd test/<test-folder> && pnpm test <test-file>
  • Unit directory test: CI=true pnpm test <test-file> (for test/unit)
  • Browser tests: CI=true pnpm test:browser:playwright

IMPORTANT: Do NOT use -- when passing test filters to pnpm. Using -- causes pnpm to drop the filter, resulting in a full test run instead of a filtered one.

# WRONG - runs ALL tests (filter is ignored):
pnpm test -- basic.test.ts -t 'expect'

# CORRECT - runs only matching tests:
pnpm test basic.test.ts -t 'expect'

When writing tests, AVOID using toContain for validation. Prefer using toMatchInlineSnapshot to include the test error and its stack. If snapshot is failing, update the snapshot instead of reverting it to toContain.

If you need to typecheck tests, run pnpm typecheck from the root of the workspace.

Rebuilding Package Changes

Tests execute built output: test suites resolve vitest through workspace symlinks whose package exports point at dist/, while pnpm typecheck resolves TypeScript source. A passing typecheck never proves dist is fresh; rebuild before re-running tests.

  • vitest and @vitest/browser inline the other @vitest/* workspace packages from TypeScript source (the __vitest_source__ export condition). After changing @vitest/utils, @vitest/expect, @vitest/snapshot, @vitest/spy, or @vitest/pretty-format, running pnpm --filter vitest build alone is enough for tests that go through the vitest bundle.
  • Rebuild the changed sub-package itself only when tests import it directly (for example, test/unit imports @vitest/utils/* from its dist).
  • @vitest/mocker is the exception: it is a runtime dependency of vitest and is never inlined. Rebuilding vitest will NOT pick up mocker changes; run pnpm --filter @vitest/mocker build.
  • Worker-side code in packages/vitest/src/runtime/ is loaded from built dist/workers/*.js, so runtime changes also require rebuilding vitest.
  • pnpm dev (watch mode) rebuilds JS only; the .d.ts bundling configs are skipped in watch mode. After changing public types, run a full build before checking anything against dist/*.d.ts.

Testing Utilities

  • runInlineTests from test/test-utils/index.ts - You must use this for complex file system setups (>1 file)
  • runVitest from test/test-utils/index.ts - You can use this to run Vitest programmatically
  • No mocking policy - You must never mock anything in tests

Behavior you must know:

  • runVitest(config) treats its first argument as the on-disk config, so a fixture's own config file takes priority over it. Pass overriding or CLI-only options via $cliOptions, or config: false to skip config discovery. Unless overridden, it forces watch: false, maxWorkers: 1, reporters: ['verbose'] (pass reporters: 'none' to restore Vitest's real default), cache: false, and NO_COLOR.
  • runVitest/runInlineTests never throw and close the started Vitest automatically. Assert with expect(stderr).toBe('') plus expect(testTree()).toMatchInlineSnapshot(...), or errorTree() for failures; output is ANSI-stripped and paths are normalized to <root>/. Check the returned thrown and stderr for startup errors.
  • runInlineTests writes files to a vitest-test-<uuid> directory under cwd, auto-adds an empty vitest.config.js when the structure has no .config. file, and deletes the directory when the test finishes (set VITEST_FS_CLEANUP=false to keep it for debugging). Config objects are serialized with JSON.stringify, so functions and regexps inside them are silently dropped; write such configs as whole-file strings instead.
  • runVitestCli spawns the real CLI binary (it also runs dist), always appends --maxWorkers=1, and kills the subprocess when the test finishes. Interact via vitest.waitForStdout() and vitest.write(); write() clears the captured output.

Writing Reliable Tests

  • Never mutate committed fixture files from a test; e2e tests run in parallel. Tests that only need an editable directory must use runInlineTests. Tests that genuinely need git-tracked files (for example --changed) must be added to the serialTests list in test/e2e/vitest.config.ts.
  • In watch-mode tests, mutate files only with createFile/editFile from test/test-utils: they restore content and mtime after the test, so the next test's watcher sees no phantom change. Call them inside a test, not in hooks (cleanup registers via onTestFinished). Always pass a small explicit root; runVitest({ watch: true, root }) waits for the watcher to be ready before resolving.
  • ESLint's test rules are disabled in this repo, so a stray .only passes lint. Check for and remove it yourself.
  • CI runs the unit, e2e, coverage, and browser suites on Windows, plus an e2e leg on macOS. Vitest reports paths with forward slashes, so normalize \ to / before comparing against import.meta.filename, process.execArgv, or other raw OS paths. Never use unix-only commands like rm -rf or cp -r in package.json scripts; use a node script or rimraf.

Project Structure

Core Packages (packages/)

  • vitest - Main testing framework, including the test runner core (all imported packages, except @vitest/mocker, from this repository are inlined into its bundle, they are not imported at runtime)
  • browser - Browser testing support
  • browser-playwright / browser-preview - Browser mode providers
  • ui - Web UI for test results
  • expect - Assertion library
  • spy - Mocking and spying utilities
  • snapshot - Snapshot testing
  • coverage-v8 / coverage-istanbul - Code coverage
  • utils - Shared utilities
  • mocker - Module mocking
  • pretty-format - Value serialization
  • web-worker - Web Worker simulation for Node.js

Test Organization (test/)

  • test/unit - Core functionality tests
  • test/e2e - End-to-end tests run through runVitest/runInlineTests
  • test/browser - Browser-specific tests
  • test/node-runner - Tests that must have no access to Vitest APIs in the test process (run with node --test)
  • Various test suites organized by feature

Important Directories

  • docs/ - Documentation (Vite-powered)
  • examples/ - Example projects and integrations
  • scripts/ - Build and development scripts
  • .github/ - GitHub Actions workflows
  • patches/ - Package patches via pnpm

Code Style and Conventions

Formatting and Linting

  • Always run pnpm lint:fix after making changes
  • Fix non-auto-fixable errors manually
  • Run lint as CI=true pnpm lint from a terminal inside an editor or agent harness: the config disables some rules when it detects an editor environment, and those rules still fail in CI

Rules that lint:fix cannot fix:

  • Never import ... from 'path'; it is an ESLint error everywhere. Prefer pathe (the dominant convention; it normalizes paths to posix), though node:path is allowed in Node-only code.
  • Source in packages/*/src must not import from vitest or vitest/node, even type-only. Exception: packages that declare vitest as a peer dependency (coverage-*, ui, browser, browser-*, web-worker).
  • console.log in package source is an ESLint error; only console.warn and console.error are allowed. Remove debug logging, and give intentional console output an explicit eslint-disable comment.
  • Use globalThis, never global or self (allowed only in docs/, packages/web-worker/, and test/unit/).
  • No top-level await in packages/*/src (allowed in test/, scripts/, and config files); no const enum; no export =.
  • In packages/browser, do not import from ivya outside the files that already do; ESLint enforces this so ivya stays in a single rollup chunk. Reuse the existing entry points.

TypeScript

  • Strict TypeScript configuration
  • Use pnpm typecheck to verify types
  • Configuration files: tsconfig.base.json, tsconfig.build.json, tsconfig.check.json
  • Root pnpm typecheck excludes test/e2e, test/browser, test/typescript, docs, and examples (see tsconfig.check.json); type errors there will not surface from the root command
  • Root typecheck does not cover the UI client Vue code; when changing packages/ui/client, also run pnpm -C packages/ui typecheck:client

Code Quality

  • ESM-first approach
  • Follow existing patterns in the codebase
  • Use utilities from @vitest/utils/* when available. Never import from @vitest/utils main entry point directly.
  • When describing the changes in commit message or in PR/issue description be very brief and to the point, the code should speak for itself.
  • Runtime code must not use APIs newer than the minimum Node version in engines. CI's main matrix runs newer Node versions with a single minimum-version e2e leg, so a breakage there may surface in only one CI job.

Code Comments Policy

  • Avoid writing comments for every change - if the code is expressive enough, it doesn't need a comment.
  • In general, only public methods MUST have comments. Exported internal functions, properties or constants SHOULD not have comments. The name SHOULD be expressive enough to not need a comment.
  • You MIGHT leave a comment if the line or a block of code deals with an edge case that is not obvious from the context. In general, the naming SHOULD provide enough information. If you spread the logic between different files or functions and NEED to add a comment, reconsider the change - perhaps, there is a simpler solution.
  • When adding a code comment, be BRIEF and do not overexplain. If you wrote a big comment with edge cases and examples, rethink the code - there MIGHT be a simpler change that does not require a wall of text.
  • You MUST NOT use overly specific jargon in comments, keep it simple.
  • You MUST NOT add a code comment that only justifies the change against a prior implementation.

Common Workflows

Adding New Features

  1. Identify the appropriate package in packages/
  2. Follow existing code patterns
  3. Add tests using testing utilities
  4. Run pnpm build && pnpm typecheck && pnpm lint:fix
  5. Add tests with relevant test suites

Debugging

  • Use VS Code: ⇧⌘B (Shift+Cmd+B) or Ctrl+Shift+B for dev tasks
  • Check scripts/ directory for specialized development tools

Documentation

  • Docs live in docs/ (VitePress); read docs/AGENTS.md before working on them
  • After ANY change to CLI options or their descriptions in packages/vitest/src/node/cli/cli-config.ts, run pnpm -C docs run cli-table and commit the regenerated docs/guide/cli-generated.md; never edit that file by hand

Generated Files and CI Checks

CI builds everything and then runs git diff --exit-code, so stale generated files fail CI. Commit regenerated files instead of reverting them, and never edit them by hand:

  • packages/vitest/LICENSE.md is rewritten by pnpm --filter vitest build when bundled dependencies change
  • docs/guide/cli-generated.md is generated from packages/vitest/src/node/cli/cli-config.ts (it carries no banner saying so)
  • pnpm-workspace.yaml may change on pnpm install (cleanupUnusedCatalogs, minimumReleaseAgeExclude)
  • docs/.vitepress/contributor-names.json is generated by pnpm docs:contributors

Other blocking CI jobs:

  • Knip (pnpm knip) fails on unused files, exports, and dependencies. Delete dead code instead of leaving unused exports; exceptions live in knip.jsonc.
  • Edits to .github/workflows/ are gated by actionlint and zizmor (pedantic persona). Pin uses: actions to full commit SHAs and suppress zizmor false positives inline with # zizmor: ignore[rule] plus a justification comment - DO NOT add a comment automatically, you MUST run zizmor first when making changes to workflow files.

Dependencies and Tools

Key Dependencies

  • Vite - Build tool and dev server
  • Rollup - Bundler
  • ESLint - Linting
  • TypeScript - Type checking
  • Playwright - Browser testing
  • Chai/Expect - Assertions
  • Tinybench - Benchmarking

Adding and Updating Dependencies

  • New runtime deps for packages/* usually go into devDependencies: Rollup marks only dependencies as external and bundles everything else. Use dependencies only for @types/* packages, deps that cannot be bundled (binaries), or deps whose own types appear in Vitest's public types (see "Notes on Dependencies" in CONTRIBUTING.md).
  • Add deps with pnpm add <pkg> inside the target package: catalogMode: prefer writes catalog: into package.json and adds the version to the default catalog in pnpm-workspace.yaml automatically. To bump a shared dep, edit its catalog entry, never per-package ranges.
  • The overrides in pnpm-workspace.yaml force one version of vite, rollup, @types/node, acorn, and mlly across the workspace; editing a range in an individual package.json changes what gets published, not what installs locally.
  • The workspace develops against the latest supported Vite major, but vitest supports the full peer range and CI runs a dedicated job against the previous major (pnpm override-vite7 reproduces it locally). Do not rely on newest-Vite-only APIs without a fallback.
  • Deps listed under patchedDependencies (acorn, cac, @sinonjs/fake-timers, rrweb-snapshot) are version-locked. Bumping one requires regenerating the patch with pnpm patch and updating the version-keyed entry in pnpm-workspace.yaml.
  • Dependency build scripts run only for packages listed under allowBuilds in pnpm-workspace.yaml; a new dep with a postinstall step installs unbuilt unless added there.
  • pnpm enforces a 24h minimumReleaseAge: installing a version published less than a day ago either resolves to an older version or appends the pick to minimumReleaseAgeExclude in pnpm-workspace.yaml. Both outcomes are expected; commit the yaml change instead of reverting it.

Browser Testing

  • Providers: Playwright (@vitest/browser-playwright) and preview (@vitest/browser-preview); the WebDriverIO provider is maintained outside this monorepo
  • Component testing supported (Vue, React, Svelte via official vitest-browser-* packages, other frameworks via Testing Library)

Performance Considerations

  • This is a performance-critical testing framework
  • Pay attention to import costs and bundle size
  • Use lazy loading where appropriate
  • Consider worker thread implications

Troubleshooting

Common Issues

  • Ensure pnpm is used (not npm/yarn)
  • Build before running tests
  • Check Node.js version compatibility
  • Playwright browsers must be installed for browser tests

Getting Help

  • Check existing issues and documentation
  • Review CONTRIBUTING.md for detailed guidelines
  • Follow patterns in existing code

Commit Messages and PR Titles

PRs are squash-merged, so the PR title becomes the commit message. Nothing in CI enforces the format; follow .github/commit-convention.md yourself: <type>(<scope>): <subject> with type one of feat|fix|docs|dx|refactor|perf|test|workflow|build|ci|chore|types|wip|release|deps, subject at most 50 characters, lowercase, imperative, no trailing dot.

PR Limitations

This repository has a limit of 1 PR if you don't have write access. DO NOT try to bypass it by creating draft PRs. If you cannot create a pull request, let a human know that you will not breach this repository's policy because it will ban the PR author in Vitest organisation.