vitest-skilld

name: vitest-skilld description: "ALWAYS use when writing code importing "vitest". Consult for debugging, best practices, or modifying vitest." metadata: version: 4.1.0 generated_by: cached generated_at: 2026-03-22

vitest-dev/vitest vitest

Version: 4.1.0 Deps: es-module-lexer@^2.0.0, expect-type@^1.3.0, magic-string@^0.30.21, obug@^2.1.1, pathe@^2.0.3, picomatch@^4.0.3, std-env@^4.0.0-rc.1, tinybench@^2.9.0, tinyexec@^1.0.2, tinyglobby@^0.2.15, tinyrainbow@^3.0.3, vite@^6.0.0 || ^7.0.0 || ^8.0.0-0, why-is-node-running@^2.3.0, @vitest/expect@4.1.0, @vitest/mocker@4.1.0, @vitest/runner@4.1.0, @vitest/snapshot@4.1.0, @vitest/pretty-format@4.1.0, @vitest/spy@4.1.0, @vitest/utils@4.1.0 Tags: latest: 4.1.0, beta: 4.1.0-beta.6

References: package.json — exports, entry points • README — setup, basic usage • Docs — API reference, guides • GitHub Issues — bugs, workarounds, edge cases • GitHub Discussions — Q&A, patterns, recipes • Releases — changelog, breaking changes, new APIs

Search

Use skilld search instead of grepping .skilld/ directories — hybrid semantic + keyword search across all indexed docs, issues, and releases. If skilld is unavailable, use npx -y skilld search.

skilld search "query" -p vitest
skilld search "issues:error handling" -p vitest
skilld search "releases:deprecated" -p vitest

Filters: docs:, issues:, releases: prefix narrows by source type.

API Changes

This section documents version-specific API changes — prioritize recent major/minor releases.

Breaking Changes v4.0

• BREAKING: test() and describe() third argument — options must be the second argument, not third source

• BREAKING: Pool configuration options restructured — maxThreads/maxForks → maxWorkers, singleThread/singleFork → maxWorkers: 1, isolate: false, poolOptions removed, vmMemoryLimit replaces nested config source

• BREAKING: @vitest/browser/context and @vitest/browser/utils moved — import from vitest/browser instead source

• BREAKING: Browser provider now accepts factory function instead of string — provider: 'playwright' → provider: playwright({ launchOptions: {...} }) source

• BREAKING: workspace config option renamed to projects — move code from vitest.workspace.js to vitest.config.ts source

• BREAKING: Module environment now uses viteEnvironment property instead of transformMode source

• BREAKING: vi.fn().getMockName() returns 'vi.fn()' by default instead of 'spy' — affects snapshots with mock names source

• BREAKING: vi.restoreAllMocks no longer resets automocks — only restores manual vi.spyOn spies source

• BREAKING: Coverage coverage.all and coverage.extensions removed — use coverage.include to specify source file pattern source

• BREAKING: Verbose reporter now prints as flat list — use 'tree' reporter for previous hierarchical output source

• BREAKING: Removed deprecated config options — poolMatchGlobs, environmentMatchGlobs, deps.external, deps.inline, deps.fallbackCJS replaced with projects and server.deps.* source

• BREAKING: Snapshots with custom elements now include shadow root contents — set printShadowRoot: false to restore previous behavior source

New Features v4.0

• NEW: vi.spyOn() and vi.fn() support constructors — can now spy on and mock constructor functions with new keyword source

• NEW: toMatchScreenshot() for visual regression testing in browser mode source

• NEW: toBeInViewport() browser utility to assert element visibility source

• NEW: onUnhandledError callback hook for handling unhandled errors source

• NEW: onConsoleLog callback now receives entity parameter source

• NEW: expect.assert() for type narrowing in assertions source

• NEW: Custom screenshot comparison algorithms support in browser mode source

• NEW: Module Runner replaces vite-node — provides moduleRunner instance injected into test runners instead of __vitest_executor source

• NEW: API method enableCoverage() and disableCoverage() for dynamic coverage control source

• NEW: API method getGlobalTestNamePattern() to access current test name filter source

• NEW: API method getSeed() to retrieve random seed value source

• NEW: experimental_parseSpecifications API for parsing test specifications source

Deprecation & Removal

• DEPRECATED: Reporter APIs onCollected, onSpecsCollected, onPathsCollected, onTaskUpdate, onFinished — migrate to new reporter API source

• DEPRECATED: --browser.provider CLI option removed source

• DEPRECATED: test.poolOptions config — use top-level options instead source

Also changed: vi.mockObject() adds spy option · recordArtifact() exported from vitest package · toBeNullable() matcher · Module graph UI fixes in HTML reporter · Playwright tracing support · Separate browser provider packages (@vitest/browser-playwright, etc.)

Best Practices

• Disable test isolation selectively with isolate: false for projects without side effects or that properly cleanup state — reduces test run time by eliminating per-file VM/worker overhead source

• Use context.expect instead of global expect when running concurrent snapshot tests — ensures each test's snapshots are tracked independently and prevents conflicts source

• Define test tags in configuration to apply shared options (timeout, retry, priority) to grouped tests — enables filtering and automatic configuration without repeating test options source

• Return a cleanup function from beforeEach instead of using afterEach — simpler syntax and keeps setup/teardown logic in one place source

beforeEach(() => {
  const resource = setupResource()
  return () => resource.cleanup()
})

• Use dynamic import() syntax with vi.mock for better TypeScript support and IDE integration — allows the compiler to validate the module path and type the importOriginal helper source

• Use vi.hoisted to declare variables referenced in vi.mock factories — allows bypassing the hoisting limitation and referencing setup code source

• Choose the threads pool over forks for larger projects to improve test run time — threads pool is faster for parallelization on multi-core machines source

• Await importOriginal() inside mock factories to properly handle async module loading — mock factory receives an async helper that must be awaited to access the real module source

• Apply retry conditions to tests with transient failures using regex or function-based matching — enables automatic retry only for specific error patterns without blanket retries source