Vitest Knowledge Patch (3.0 – 4.1) Skill

Vitest Knowledge Patch (3.0 – 4.1)

Supplementary knowledge for Vitest features released after Claude's training cutoff. Covers versions 3.0 through 4.1 (January 2025 – March 2026).

Reference Files

references/projects-config.md — workspace replaced by projects, inline config, sequence.groupOrder, watchTriggerPatterns, defineProject
references/browser-mode.md — Stable browser mode (v4), provider packages, locators, visual regression testing, Playwright traces, frame locators
references/test-fixtures-hooks.md — Scoped fixtures, test.extend builder pattern, aroundEach/aroundAll hooks, type-aware hooks, vi.defineHelper, test signal API
references/matchers-mocking.md — expect.assert, expect.schemaMatching, Matchers type, mockThrow, using with vi.spyOn/fn, v4 mocking changes
references/test-organization.md — Test tags (v4.1), test annotations, agent reporter, GitHub Actions job summary, --detect-async-leaks
references/migration-v4.md — Breaking changes, coverage overhaul, simplified exclude, viteModuleRunner: false, Node.js 20+ requirement

Projects (replaces Workspace)

The workspace config and separate vitest.workspace files are deprecated (v3.2) and removed in v4. Use projects instead:

import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    projects: [
      'packages/*',
      {
        extends: true, // inherit root config
        test: {
          name: 'unit',
          include: ['**/*.unit.test.ts'],
        },
      },
      {
        test: {
          name: { label: 'browser', color: 'green' },
          browser: { enabled: true, /* ... */ },
        },
      },
    ],
  },
})

Use defineProject (not defineConfig) in per-project config files — it enforces project-level type safety.

Browser Mode (Stable in v4)

Provider is now a function from a dedicated package, not a string. @vitest/browser is included automatically.

import { defineConfig } from 'vitest/config'
import { playwright } from '@vitest/browser-playwright'

export default defineConfig({
  test: {
    browser: {
      provider: playwright(),
      enabled: true,
      instances: [{ browser: 'chromium' }],
    },
  },
})

Packages: @vitest/browser-playwright, @vitest/browser-webdriverio, @vitest/browser-preview. Import context from vitest/browser (not @vitest/browser/context).

Test Tags (v4.1)

Define tags in config with optional test options. Filter with --tags-filter:

// vitest.config.ts
export default defineConfig({
  test: {
    tags: [
      { name: 'db', timeout: 60_000 },
      { name: 'flaky', retry: process.env.CI ? 3 : 0, priority: 1 },
    ],
  },
})

// test file
test('flaky db test', { tags: ['flaky', 'db'] }, () => { /* ... */ })

vitest --tags-filter="frontend && !flaky"
vitest --tags-filter="(unit || e2e) && !slow"

Supports and/&&, or/||, not/!, * wildcards, () grouping.

`test.extend` Builder Pattern (v4.1)

Return a value instead of calling use() — TypeScript infers fixture types automatically:

const test = baseTest
  .extend('config', { port: 3000, host: 'localhost' })
  .extend('server', async ({ config }) => {
    return `http://${config.host}:${config.port}`
  })
  .extend('tempFile', async ({}, { onCleanup }) => {
    const path = `/tmp/test-${Date.now()}.txt`
    await fs.writeFile(path, 'data')
    onCleanup(() => fs.unlink(path))
    return path
  })

`aroundEach` / `aroundAll` Hooks (v4.1)

Wrap tests in a context (transactions, AsyncLocalStorage, tracing spans):

test.aroundEach(async (runTest, { db }) => {
  await db.transaction(runTest)
})

test('insert user', async ({ db }) => {
  await db.insert({ name: 'Alice' }) // runs inside transaction
})

Key New APIs

| API | Version | Purpose | |-----|---------|---------| | expect.schemaMatching(schema) | 4.0 | Asymmetric matcher for Standard Schema v1 (Zod, Valibot, ArkType) | | expect.assert(condition) | 4.0 | Type-narrowing assertion (like Chai assert on expect) | | vi.fn().mockThrow(error) | 4.1 | Concise mock throwing (replaces mockImplementation(() => { throw })) | | vi.defineHelper(fn) | 4.1 | Removes helper internals from stack traces | | using spy = vi.spyOn(...) | 3.2 | Explicit Resource Management — auto-restores on block exit | | context.signal | 3.2 | AbortSignal aborted on timeout, bail, or Ctrl+C | | context.annotate(msg) | 3.2 | Attach messages/files to test results for reporters | | page.mark(name, fn?) | 4.1 | Add named markers to Playwright trace timeline | | toMatchScreenshot(name) | 4.0 | Visual regression testing in browser mode | | page.frameLocator(loc) | 4.0 | Locate elements inside iframes (Playwright only) | | locator.length | 4.0 | Use toHaveLength on locators |

Visual Regression Testing (v4)

import { page } from 'vitest/browser'
await expect(page.getByTestId('hero')).toMatchScreenshot('hero-section')

Screenshots stored in __screenshots__/ next to tests, named {name}-{browser}-{platform}.png. Update with vitest --update. See references/browser-mode.md for configuration.

Coverage Changes (v4)

coverage.all and coverage.extensions removed — define coverage.include explicitly
V8 provider now uses AST-aware remapping (identical accuracy to Istanbul)
coverage.ignoreEmptyLines removed
New: coverage.changed — limit coverage to modified files only
/* v8 ignore start/stop */ and /* istanbul ignore start/stop */ comments restored (v4.1)

Agent Reporter (v4.1)

Auto-enabled when running inside AI coding agents. Only shows failed tests and errors, reducing token usage:

AI_AGENT=copilot vitest

`experimental.viteModuleRunner: false` (v4.1)

Disable Vite's module runner to run tests with native Node.js import. Faster startup, closer to production. Requires Node.js 22.15+ for vi.mock/vi.hoisted. No import.meta.env, plugins, or aliases.

export default defineConfig({
  test: {
    experimental: { viteModuleRunner: false },
  },
})

`--detect-async-leaks` (v4.1)

Detect leaked timers, handles, and unresolved async resources with source locations:

vitest --detect-async-leaks

Reporter Changes (v4)

basic reporter removed — use ['default', { summary: false }]
verbose now always prints tests one-by-one (not just CI)
New tree reporter for always-on tree output
github-actions reporter auto-generates Job Summary with flaky test details (v4.1)

Agent Skills: Vitest Knowledge Patch (3.0 – 4.1)

Install this agent skill to your local

Skill Files