Build Comprehensive Vitest Test Suites

This skill covers Vitest, the fast test runner for modern JavaScript/TypeScript, spanning unit tests, integration tests, mocking strategies, and advanced Vitest features for comprehensive, maintainable test suites. Core principles: readable, reliable, and fast tests, the Arrange-Act-Assert pattern, descriptive test names, proper test isolation with setup/teardown, Vitest's built-in mocking and assertion utilities, and minimal coupling to implementation details.

Essential configuration is shown via a vitest.config.ts:

// vitest.config.ts
import { defineConfig } from 'vitest/config'
import { resolve } from 'path'

export default defineConfig({
  test: {
    environment: 'jsdom', // or 'node', 'happy-dom'
    globals: true,
    setupFiles: ['./src/test/setup.ts'],
    coverage: {
      provider: 'v8',
      reporter: ['text', 'json', 'html'],
      exclude: ['node_modules/', 'src/test/'],
      thresholds: {
        global: {
          branches: 80,
          functions: 80,
          lines: 80,
          statements: 80
        }
      }
    },
    alias: {
      '@': resolve(__dirname, './src')
    }
  }
})

Test structure is demonstrated with a full service-layer suite: mocking a database-client dependency, beforeEach/afterEach setup and mock clearing, and Arrange-Act-Assert tests covering both a successful creation path and a validation-error rejection path with an assertion that the mocked insert was never called.

Advanced mocking covers partial mocking (vi.importActual to keep real exports while overriding one function), chained mock implementations (mockResolvedValueOnce twice then a final mockRejectedValue), and spying on real implementations via vi.spyOn. Async-operation testing covers awaiting a pending-then-resolved promise while asserting a loading flag, and fake-timer-based debounce testing (vi.useFakeTimers, vi.advanceTimersByTime, vi.useRealTimers). Component testing is shown via @testing-library/react and user-event, rendering a component, filling and submitting a form, and asserting the update callback received the changed data. Custom matchers and utilities cover a test-data factory with override support and an expect.extend-based custom email-validation matcher.

Performance and optimization tips: vi.hoisted() for module-level mocks needing early initialization, concurrent tests for independent suites, test.each() for parameterized testing, vi.stubGlobal() for global mocking, proper afterEach cleanup to prevent test pollution, and test.skip()/test.only() for debugging. Best practices cover test naming ("should [expected behavior] when [condition]"), specific rather than generic assertions, mocking at the boundary (external APIs, databases, file systems), prioritizing critical-path coverage over raw percentage, regularly refactoring tests alongside production code, and descriptive names and comments for complex scenarios.

Use it when writing or reviewing a Vitest test suite - configuring coverage thresholds, mocking dependencies, testing async operations or timers, testing React components, or building custom matchers. A good signal it applies: a negative-path test needs to assert a side effect never happened, such as confirming a mocked database insert was never called after a validation error. It is not a general JavaScript-testing-theory guide beyond Vitest's specific API surface, and it does not cover other runners like Jest or Mocha beyond patterns that happen to overlap.

Given a module, component, or async function to test, it produces a Vitest test file (describe/it blocks, mocks, assertions) plus the relevant vitest.config.ts settings - environment, coverage thresholds, aliases - needed to run it.

Built on Vitest's core API (describe, it, expect, vi), with component-testing examples using @testing-library/react and @testing-library/user-event, and coverage via the v8 provider.

Frontend and full-stack JavaScript/TypeScript engineers who need their test suite to stay fast and isolated as it grows, using patterns like hoisted module mocks and concurrent suites rather than letting a monolithic test file slow down over time.