Skip to content

Vitest — Unit & Integration Testing in GE

OWNER: marije, judith ALSO_USED_BY: antje LAST_VERIFIED: 2026-03-26 GE_STACK_VERSION: vitest ^4.0.18, @vitest/coverage-v8 ^4.0.18

Overview

Vitest is the standard unit and integration testing framework for all GE projects. It runs on the same Vite pipeline as the dev server — zero config duplication. Agents use this page when writing tests, configuring coverage, or debugging test failures.

GE Testing Conventions

CHECK: A new feature is being developed. THEN: Tests are written alongside the feature — same PR, same commit. THEN: Unit tests go in __tests__/ directories adjacent to source files or in *.test.ts co-located files. THEN: Integration tests go in tests/integration/.

CHECK: A test file is being created. THEN: Name it {module}.test.ts or {module}.test.tsx. THEN: Use describe blocks to group related tests. THEN: Use it (not test) for individual test cases. THEN: Test names read as sentences: it("returns null when user is not found").

Vitest v4 Configuration

// vitest.config.ts
import { defineConfig } from "vitest/config"
import react from "@vitejs/plugin-react"
import path from "path"

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "./src"),
    },
  },
  test: {
    globals: true,
    environment: "jsdom",
    setupFiles: ["./tests/setup.ts"],
    include: ["**/*.test.{ts,tsx}"],
    coverage: {
      provider: "v8",
      include: ["src/**/*.{ts,tsx}"],
      exclude: ["src/**/*.d.ts", "src/**/index.ts"],
      thresholds: {
        statements: 80,
        branches: 75,
        functions: 80,
        lines: 80,
      },
    },
    // v4: pool options are now top-level
    isolate: true,
    maxWorkers: "75%",
  },
})

CHECK: You are configuring Vitest for a GE project. THEN: Use environment: "jsdom" for React component tests. THEN: Use globals: true so describe, it, expect are available without imports. THEN: Set coverage.provider: "v8" — faster than Istanbul, good enough for GE. THEN: Set path aliases to match the project's tsconfig.json.

Vitest v4 Breaking Changes (From v3)

CHECK: Migrating from Vitest v3 to v4. IF: Using poolOptions in config. THEN: Move all pool options to top level — poolOptions is removed in v4. IF: Using coverage.all. THEN: Removed in v4 — define coverage.include explicitly instead. IF: Using VITEST_MAX_THREADS or VITEST_MAX_FORKS env vars. THEN: Replaced with VITEST_MAX_WORKERS.

Setup File

// tests/setup.ts
import "@testing-library/jest-dom/vitest"
import { cleanup } from "@testing-library/react"
import { afterEach, vi } from "vitest"

afterEach(() => {
  cleanup()
  vi.restoreAllMocks()
})

CHECK: The setup file exists. THEN: It MUST call vi.restoreAllMocks() in afterEach — prevents mock leaks between tests. THEN: It MUST call cleanup() for React Testing Library.

Running Tests

# Run all tests
npx vitest

# Run specific file
npx vitest src/lib/utils.test.ts

# Run with coverage
npx vitest --coverage

# Run in watch mode (default)
npx vitest --watch

# Run once (CI)
npx vitest run

Cross-References

READ_ALSO: wiki/docs/stack/vitest/patterns.md READ_ALSO: wiki/docs/stack/vitest/coverage.md READ_ALSO: wiki/docs/stack/vitest/pitfalls.md READ_ALSO: wiki/docs/stack/vitest/checklist.md READ_ALSO: wiki/docs/stack/playwright/index.md