Vitest — Agent Skill by Anthony Fu

From the author

Vitest fast unit testing framework powered by Vite with Jest-compatible API. Use when writing tests, mocking, configuring coverage, or working with test filtering and fixtures.

— the description by Anthony Fu

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

Vitest is a testing framework built for the Vite ecosystem. It provides a Jest-compatible API and supports ESM, TypeScript, and JSX by default. It shares configuration, transformers, and plugins with Vite applications, allowing for integrated testing workflows. The framework includes features for mocking, snapshot testing, code coverage, and multi-threaded test execution.

What it does

Provides a Jest-compatible API for writing and running unit tests
Supports native ESM, TypeScript, and JSX without additional configuration
Enables mocking of functions, modules, timers, and dates
Offers built-in code coverage reporting using V8 or Istanbul
Supports multi-project workspaces and varied test environments like Node, jsdom, and happy-dom
Includes utilities for snapshot testing, test filtering, and benchmarking

When to use it

When you need a testing framework that integrates directly with your Vite configuration
When migrating existing test suites that rely on Jest-compatible APIs
When you require specific test environments like jsdom or happy-dom for DOM-related testing
When managing complex test setups across monorepos or multiple projects

Advantages

Shares configuration and plugins with Vite projects
Supports parallel test execution via multi-threaded workers
Provides flexible test environment configuration per file or project
Includes built-in support for snapshot testing and mocking utilities

Usage examples

“How do I configure Vitest to use the jsdom environment for my tests?”: The agent provides the vitest.config.ts configuration snippet using the environment: 'jsdom' property and explains how to install the necessary jsdom package.
“Can I run different test configurations in the same Vitest process?”: The agent explains how to use the projects field in the vitest.config.ts file to define multiple test suites with different environments or include patterns.

Install

Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/antfu/vitest/download
Unzip it into the cross-client skills folder of your project:
```
mkdir -p .agents/skills && unzip vitest.zip -d .agents/skills
```

Documentation by Anthony Fu

Vitest is a next-generation testing framework powered by Vite. It provides a Jest-compatible API with native ESM, TypeScript, and JSX support out of the box. Vitest shares the same config, transformers, resolvers, and plugins with your Vite app.

Key Features:

Vite-native: Uses Vite's transformation pipeline for fast HMR-like test updates
Jest-compatible: Drop-in replacement for most Jest test suites
Smart watch mode: Only reruns affected tests based on module graph
Native ESM, TypeScript, JSX support without configuration
Multi-threaded workers for parallel test execution
Built-in coverage via V8 or Istanbul
Snapshot testing, mocking, and spy utilities

The skill is based on Vitest 5.1.0-beta.1, generated at 2026-10-23.

Core

Topic	Description	Reference
Configuration	Vitest and Vite config integration, defineConfig usage	core-config
CLI	Command line interface, commands and options	core-cli
Test API	test/it function, modifiers like skip, only, concurrent	core-test-api
Describe API	describe/suite for grouping tests and nested suites	core-describe
Expect API	Assertions with toBe, toEqual, matchers and asymmetric matchers	core-expect
Hooks	beforeEach, afterEach, beforeAll, afterAll, aroundEach	core-hooks

Features

Topic	Description	Reference
Mocking	Mock functions, modules, timers, dates with vi utilities	features-mocking
Snapshots	Snapshot testing with toMatchSnapshot and inline snapshots	features-snapshots
Coverage	Code coverage with V8 or Istanbul providers	features-coverage
Test Context	Test fixtures, context.expect, test.extend for custom fixtures	features-context
Concurrency	Concurrent tests, parallel execution, sharding	features-concurrency
Filtering	Filter tests by name, file patterns, tags	features-filtering
Test Tags	Label tests with tags to filter runs and apply shared options	features-test-tags
Reporters	Built-in reporters, default selection, CI/output config	features-reporters
Benchmarking	Write benchmarks with the bench fixture (Tinybench)	features-benchmarking

Advanced

Topic	Description	Reference
Vi Utilities	vi helper: mock, spyOn, fake timers, hoisted, waitFor	advanced-vi
Environments	Test environments: node, jsdom, happy-dom, custom	advanced-environments
Type Testing	Type-level testing with expectTypeOf and assertType	advanced-type-testing
Projects	Multi-project workspaces, different configs per project	advanced-projects

Files

ATTRIBUTION.mdAdded by AutoGineer895 B
GENERATION.md136 B
LICENSELicence file added by AutoGineer1.1 KiB
SKILL.md3.6 KiB
references/advanced-environments.md4.9 KiB
references/advanced-projects.md7.4 KiB
references/advanced-type-testing.md4.6 KiB
references/advanced-vi.md5.8 KiB
references/core-cli.md4.9 KiB
references/core-config.md7.7 KiB
references/core-describe.md3.5 KiB
references/core-expect.md8.8 KiB
references/core-hooks.md4.8 KiB
references/core-test-api.md5.5 KiB
references/features-benchmarking.md3.9 KiB
references/features-concurrency.md4.7 KiB
references/features-context.md5.3 KiB
references/features-coverage.md5.0 KiB
references/features-filtering.md4.8 KiB
references/features-mocking.md9.8 KiB
references/features-reporters.md4.0 KiB
references/features-snapshots.md5.2 KiB
references/features-test-tags.md3.6 KiB

references/advanced-environments.md

name: test-environments description: Configure environments like jsdom, happy-dom for browser APIs

Test Environments

Available Environments

node (default) - Node.js environment
jsdom - Browser-like with DOM APIs
happy-dom - Faster alternative to jsdom
edge-runtime - Vercel Edge Runtime

Configuration

// vitest.config.ts
defineConfig({
  test: {
    environment: 'jsdom',
    
    // Environment-specific options
    environmentOptions: {
      jsdom: {
        url: 'http://localhost',
      },
    },
  },
})

Installing Environment Packages

# jsdom
npm i -D jsdom

# happy-dom (faster, fewer APIs)
npm i -D happy-dom

Per-File Environment

Use magic comment at top of file:

// @vitest-environment jsdom

import { expect, test } from 'vitest'

test('DOM test', () => {
  const div = document.createElement('div')
  expect(div).toBeInstanceOf(HTMLDivElement)
})

jsdom Environment

Full browser environment simulation:

// @vitest-environment jsdom

test('DOM manipulation', () => {
  document.body.innerHTML = '<div id="app"></div>'
  
  const app = document.getElementById('app')
  app.textContent = 'Hello'
  
  expect(app.textContent).toBe('Hello')
})

test('window APIs', () => {
  expect(window.location.href).toBeDefined()
  expect(localStorage).toBeDefined()
})

jsdom Options

defineConfig({
  test: {
    environmentOptions: {
      jsdom: {
        url: 'http://localhost:3000',
        html: '<!DOCTYPE html><html><body></body></html>',
        userAgent: 'custom-agent',
        resources: 'usable',
      },
    },
  },
})

happy-dom Environment

Faster but fewer APIs:

// @vitest-environment happy-dom

test('basic DOM', () => {
  const el = document.createElement('div')
  el.className = 'test'
  expect(el.className).toBe('test')
})

Multiple Environments per Project

Use projects for different environments:

defineConfig({
  test: {
    projects: [
      {
        test: {
          name: 'unit',
          include: ['tests/unit/**/*.test.ts'],
          environment: 'node',
        },
      },
      {
        test: {
          name: 'dom',
          include: ['tests/dom/**/*.test.ts'],
          environment: 'jsdom',
        },
      },
    ],
  },
})

Custom Environment

Create custom environment package:

// vitest-environment-custom/index.ts
import type { Environment } from 'vitest/runtime'

export default <Environment>{
  name: 'custom',
  viteEnvironment: 'ssr', // or 'client'
  
  setup() {
    // Setup global state
    globalThis.myGlobal = 'value'
    
    return {
      teardown() {
        delete globalThis.myGlobal
      },
    }
  },
}

Use with:

defineConfig({
  test: {
    environment: 'custom',
  },
})

Environment with VM

For full isolation:

export default <Environment>{
  name: 'isolated',
  viteEnvironment: 'ssr',
  
  async setupVM() {
    const vm = await import('node:vm')
    const context = vm.createContext()
    
    return {
      getVmContext() {
        return context
      },
      teardown() {},
    }
  },
  
  setup() {
    return { teardown() {} }
  },
}

Browser Mode (Separate from Environments)

For real browser testing, use Vitest Browser Mode. In v4 the provider is an object (not a string), and the context imports from vitest/browser:

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

defineConfig({
  test: {
    browser: {
      enabled: true,
      provider: playwright({ launchOptions: { slowMo: 100 } }),
      instances: [{ browser: 'chromium' }], // or 'firefox', 'webkit'
    },
  },
})

import { page } from 'vitest/browser' // v4: was '@vitest/browser/context'

v5: DOM-environment global assignments (e.g. window.innerWidth) now propagate to the underlying jsdom/happy-dom implementation. Locators are exact/strict by default (getByText('Item') no longer matches Item 1). browser.api is deprecated — move it to the top-level api option. Browser mode adds a built-in Trace View (browser.traceView: true).

CSS and Assets

In jsdom/happy-dom, configure CSS handling:

defineConfig({
  test: {
    css: true, // Process CSS
    
    // Or with options
    css: {
      include: /\.module\.css$/,
      modules: {
        classNameStrategy: 'non-scoped',
      },
    },
  },
})

Fixing External Dependencies

If external deps fail with CSS/asset errors:

defineConfig({
  test: {
    server: {
      deps: {
        inline: ['problematic-package'],
      },
    },
  },
})

Key Points

Default is node - no browser APIs
Use jsdom for full browser simulation
Use happy-dom for faster tests with basic DOM
Per-file environment via // @vitest-environment comment
Use projects for multiple environment configurations
Browser Mode is for real browser testing, not environment

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Node.js

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Migrate To Shoehorn
Matt Pocock· Community
Automate the migration of TypeScript test assertions from unsafe as-casting to the type-safe shoehorn library.
Software developmentClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository317.5k
Tdd
Matt Pocock· Community
A reference guide for implementing the red-green-refactor loop in test-driven development.
Software developmentClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository317.5k
Test Driven Development
Jesse Vincent (obra)· Community
A rigorous framework for Test-Driven Development, mandating that failing tests precede all production code.
Software developmentClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository314k
Webapp Testing
AnthropicOfficial
A toolkit for automating local web application testing using Playwright and server management helpers.
Software developmentClaude CodeClaude appsOpenAI Codex+14 more
Apache-2.0Low riskHas scriptsGitHub stars of the source repository188.6k
Test Driven Development
Addy Osmani· Community
A systematic approach to software development using the red-green-refactor cycle to ensure code reliability and maintainability.
Software developmentClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository113.9k
Browser Testing With Devtools
Addy Osmani· Community
Integrate Chrome DevTools to enable live browser inspection, debugging, and automated UI verification for your AI agent.
Software developmentClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository113.9k

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download vitest.zip