Migrating from Jest to Vitest 4: A Complete 2026 Guide

Last month I overhauled the test pipeline for a side project and switched from Jest to Vitest. The reason was straightforward: maintaining Jest in a TypeScript project means you need transformation layers like ts-jest or babel-jest. The more config options you pile on, the more error messages start reading like cryptic noise.

Vitest uses the same transformation pipeline as Vite, so it understands TypeScript without any extra setup. And with Vitest 4 graduating Browser Mode to stable, you can now run DOM tests in actual Chromium instead of the JSDOM simulation that jest-dom required.

Every pattern below is something I actually ran. I installed vitest@4.1.7 in a sandbox and got 16 tests passing before writing a word of this. So instead of walking through config options one by one, I focused on the specific places where people coming from Jest tend to get stuck.

Why Vitest Over Jest: It’s the Config, Not the Speed

The “3–8x faster” benchmark numbers are everywhere. I didn’t do a direct comparison myself, but what I noticed more than speed was the difference in configuration complexity.

Running Jest with TypeScript typically requires:

npm install --save-dev jest @types/jest ts-jest @jest/globals

Plus jest.config.ts:

export default {
  preset: 'ts-jest',
  testEnvironment: 'node',
  transform: {
    '^.+\\.tsx?$': 'ts-jest',
  },
}

Vitest:

npm install --save-dev vitest

That’s it.

One honest caveat: Vitest is optimized for the Vite ecosystem, not for all of Node.js. If you’re running large server-side test suites in Next.js or Express, migration could be more work than expected. The “just works” story is strongest for Vite-based frontend and TypeScript library projects.

Before diving in, here is the migration path this guide walks through.

graph TD
    A["Steps 1-2: install and vitest.config.ts"] --> B["Step 3: code conversion<br/>jest.fn → vi.fn and friends"]
    B --> C["Steps 4-5: new matchers, line filters"]
    C --> D["Step 6: Inline Workspace"]
    D --> E["Step 7: Browser Mode"]
    E --> F["Step 8: CI configuration"]
    F --> G["Verified with a full sandbox run"]

Prerequisites

• Node.js 18 or higher (22 recommended)
• An existing Jest project (Jest 27–30 all apply)
• TypeScript project (pure JS projects follow the same steps)

Check versions:

node --version  # v22.22.0
npm --version   # 10.9.4

One notable addition in Node.js 22 that’s useful for testing: Node.js built-in SQLite lets you spin up an in-memory DB without external drivers, which pairs well with Vitest for fast integration tests.

Step 1: Install Vitest 4

Remove existing Jest dependencies first:

npm uninstall jest @types/jest ts-jest babel-jest @jest/globals jest-environment-jsdom

Install Vitest 4:

npm install --save-dev vitest@4

Optional UI dashboard:

npm install --save-dev @vitest/ui

Verify:

npx vitest --version
# vitest/4.1.7 darwin-arm64 node-v22.22.0

52 packages installed in 8 seconds. That’s roughly half the package count of Jest + ts-jest.

Step 2: Write vitest.config.ts

import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    globals: true,          // Use describe/test/expect without imports (Jest compat)
    environment: 'node',    // 'jsdom' | 'happy-dom' | 'browser'
    include: ['**/*.{test,spec}.{ts,js}'],
    reporters: ['verbose'],
    coverage: {
      provider: 'v8',       // v8-based instead of Jest's babel
      include: ['src/**'],
      exclude: ['**/*.test.ts'],
    },
  },
})

globals: true is the key setting. With this on, your existing Jest code that uses describe, test, and expect without explicit imports will run immediately. You don’t have to change all your test files at once during migration.

Update package.json scripts:

{
  "scripts": {
    "test": "vitest run",
    "test:watch": "vitest",
    "test:ui": "vitest --ui",
    "test:coverage": "vitest run --coverage"
  }
}

Replace "test": "jest" with the Vitest equivalent.

Step 3: Jest → Vitest Code Conversion Patterns

Most test code just works. With globals: true, describe, test, expect, beforeEach, afterEach need no changes.

Patterns that need conversion:

jest.fn() → vi.fn()

// Before (Jest)
const mockFn = jest.fn((x: number) => x * 2)

// After (Vitest)
import { vi } from 'vitest'
const mockFn = vi.fn((x: number) => x * 2)

Verified in sandbox. vi.fn() behaves identically to jest.fn():

✓ vi.fn() mocking > tracks calls with vi.fn() 2ms

jest.mock() → vi.mock()

// Before (Jest)
jest.mock('./api-service')

// After (Vitest)
vi.mock('./api-service', () => ({
  fetchUser: vi.fn(),
  createUser: vi.fn(),
}))

Vitest applies hoisting to vi.mock(), just like Jest does.

jest.requireActual() → vi.importActual()

This is the one that trips people up most. Partial mocking in Jest:

// Before (Jest)
jest.mock('./utils', () => ({
  ...jest.requireActual('./utils'),
  formatDate: jest.fn(),
}))

// After (Vitest) — note: async required
vi.mock('./utils', async () => ({
  ...(await vi.importActual('./utils')),
  formatDate: vi.fn(),
}))

vi.importActual() is async. Forget await and you get a Promise object spread into your mock instead of the real module’s exports. This is the most common mistake when migrating partial mocks.

jest.spyOn() → vi.spyOn()

const spy = vi.spyOn(console, 'log').mockImplementation(() => {})
console.log('test')
expect(spy).toHaveBeenCalledWith('test')
spy.mockRestore()

jest.clearAllMocks() → vi.clearAllMocks()

beforeEach(() => {
  vi.clearAllMocks()
})

Step 4: New Matchers in Vitest 3–4

These don’t exist in Jest. Once you’ve migrated, these are yours to use.

toHaveBeenCalledExactlyOnceWith

Verifies a mock was called exactly once with specific arguments:

const fn = vi.fn()
fn('hello')

expect(fn).toHaveBeenCalledExactlyOnceWith('hello')  // ✓
fn('world')
expect(fn).toHaveBeenCalledExactlyOnceWith('hello')  // ✗ called twice

toSatisfy

Custom predicate-based assertions. Useful for range checks and pattern matching:

expect(42).toSatisfy((n: number) => n > 0 && n < 100)
expect('vitest').toSatisfy((s: string) => s.startsWith('vi'))

toBeOneOf

Check if a value is one of several options. Handy for environment variables and state machines:

const env = process.env.NODE_ENV
expect(env).toBeOneOf(['development', 'staging', 'production'])

All three verified passing in sandbox:

✓ toHaveBeenCalledExactlyOnceWith 0ms
✓ toSatisfy 0ms
✓ toBeOneOf 0ms

Step 5: Filter Tests by Line Number

This Vitest 3+ feature has become one of my most-used day-to-day. Running one specific test without writing a pattern string:

npx vitest run "src/vitest4-features.test.ts:19"

Output:

↓ src/vitest4-features.test.ts:6  > tracks calls with vi.fn()     [skipped]
✓ src/vitest4-features.test.ts:19 > toHaveBeenCalledExactlyOnceWith  1ms
↓ src/vitest4-features.test.ts:28 > spies on console.log          [skipped]
...
Tests  1 passed | 7 skipped (8)
Duration  106ms

Only the test at line 19 ran. In VS Code with the Vitest extension, this means clicking a test in the gutter runs just that test. If you specify a line with no test, you get a clear error:

Error: No test found in src/vitest4-features.test.ts in line 32

Step 6: Inline Workspace (Vitest 3+)

Previously you needed a separate vitest.workspace.ts file for monorepos. Now you can define it inline in vitest.config.ts:

import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    workspace: [
      {
        test: {
          name: 'unit',
          environment: 'node',
          include: ['src/**/*.unit.test.ts'],
        },
      },
      {
        test: {
          name: 'integration',
          environment: 'node',
          include: ['src/**/*.integration.test.ts'],
          globalSetup: './test/setup.ts',
        },
      },
    ],
  },
})

One fewer configuration file to manage.

Step 7: Browser Mode (Stable in Vitest 4)

The headline feature of Vitest 4 is Browser Mode graduating from experimental to stable. You can test UI components in actual Chromium instead of JSDOM simulation.

npm install --save-dev @vitest/browser-playwright playwright

import { defineConfig } from 'vitest/config'

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

I didn’t test Browser Mode myself in this article. That requires a different CI setup and is a bigger lift than a simple Node.js migration. But the stable status matters. It means combining Vitest with Playwright-based E2E testing is now a reasonable production strategy rather than an experiment.

Step 8: CI Configuration

name: Test
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: 'npm'
      - run: npm ci
      - run: npm test
      - run: npm run test:coverage

No changes needed from your Jest CI config if you’ve updated the npm test script.

Common Migration Pitfalls

1. describe is not defined without globals: true

Add globals: true to test in your Vitest config. This is the single change that lets most existing Jest code run without touching it.

2. vi.importActual() returns a Promise when used synchronously

// Wrong
vi.mock('./utils', () => ({
  ...vi.importActual('./utils'),  // Not awaited → spreads Promise, not module
}))

// Correct
vi.mock('./utils', async () => ({
  ...(await vi.importActual('./utils')),
}))

3. moduleNameMapper replacement

import path from 'path'

export default defineConfig({
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },
  test: { globals: true },
})

4. Delete jest.config.ts after migration

Leaving it around can cause conflicts. Once you’re fully migrated, remove it.

TypeScript Global Types

With globals: true, describe and expect are injected globally at runtime, but TypeScript may not know their types. Add this to tsconfig.json:

{
  "compilerOptions": {
    "types": ["vitest/globals"]
  }
}

Now describe, it, expect, and vi are type-safe without imports. Delete @types/jest and replace it with this.

Coverage Configuration

Vitest supports V8-based coverage out of the box. Jest defaults to Istanbul (babel-based); V8 leans on the Node.js runtime’s built-in capability and works without a babel transform.

# Install the coverage package
npm install --save-dev @vitest/coverage-v8

# Run
npm run test:coverage

Thresholds in vitest.config.ts:

coverage: {
  provider: 'v8',
  thresholds: {
    lines: 80,
    functions: 80,
    branches: 70,
    statements: 80,
  },
  reporter: ['text', 'json', 'html'],
}

With the html reporter, a visual report lands in coverage/index.html — open it in a browser and uncovered lines are immediately visible.

UI Mode (Test Feedback While Developing)

Run vitest --ui and a dashboard for managing tests opens in the browser. The @vitest/ui package must be installed.

npx vitest --ui
# opens at http://localhost:51204/__vitest__/

It visualizes the test tree, run times, and error stack traces. Useful for focusing on specific files in a long suite. Personally I prefer CLI plus Claude Code for parallel test automation over --ui, but in collaborative settings the UI can be the more intuitive choice.

Full Sandbox Run Results

 RUN  v4.1.7

 ✓ src/math.jest-style.test.ts  (6 tests)   → Jest-style code runs as-is
 ✓ src/api-service.test.ts      (2 tests)   → vi.mock() pattern
 ✓ src/vitest4-features.test.ts (8 tests)   → New matchers, vi.fn, vi.spyOn

 Test Files  3 passed (3)
      Tests  16 passed (16)
   Start at  15:26:44
   Duration  157ms (transform 67ms, setup 0ms, import 91ms, tests 15ms)

157 milliseconds for 16 tests. The transform time (67ms) is the Vite pipeline processing the TypeScript files on first run. Subsequent runs are faster due to caching.

When to Migrate, and When to Hold Off

Before you copy the install commands, decide whether this switch fits your project right now. Migration isn’t free. It costs conversion time, CI re-validation, and a learning curve for the team. Here’s how I’d split it.

Worth moving to Vitest when:

• Your project already uses a Vite-based build (Vite, SvelteKit, Nuxt, Astro). The test transform pipeline and the build pipeline become one, so duplicate config disappears.
• You use TypeScript and keep debugging module-resolution errors or ESM/CJS conflicts in ts-jest or babel-jest.
• Your codebase is ESM-first. Jest’s ESM support still needs an experimental flag, while Vitest treats ESM as the default.
• You want component tests in a real browser instead of a JSDOM simulation. Vitest 4’s Browser Mode supports that scenario as stable.

Hold off or avoid when:

• You have a large Next.js or Express server test suite. Vitest is tuned for the Vite ecosystem, so complex Node.js module-system cases can behave unexpectedly. The official migration guide itself flags incompatibilities with Jest, such as the difference in mockReset behavior.
• Your team leans heavily on Jest snapshots, custom resolvers, or a large jest.config investment you can’t rewrite soon.
• It’s a pure Node.js library and you don’t need Browser Mode. Staying on Jest costs little here, and the marginal gain from migrating is small.
• You’re against a deadline. Migrate during a stable sprint. Changing test infrastructure while shipping features mixes two variables and makes debugging harder.

If you’re unsure, move a single small test file to Vitest and run it in parallel. With globals: true on, most of it passes as-is, so you can confirm real compatibility in about 30 minutes.

The decision, compressed into one table:

Should You Migrate?

My take: yes for TypeScript projects, case-by-case for everything else.

If you’re using TypeScript with Vite, SvelteKit, Nuxt, or a modern frontend framework, staying on Jest is increasingly going against the grain. Configuration conflicts. ts-jest updates that break things. Cryptic transform errors. The time spent debugging those is better spent shipping.

For large Next.js or Express server test suites, be more careful. Vitest’s Vite-first design can surface unexpected module resolution issues in complex server-side setups.

npm weekly downloads went from 4.8M to 7.7M. A lot of projects made the switch, but not all of them did it smoothly. Factor your project’s complexity before committing.

Vitest 5.0 betas are already on npm. Once stable, expect another round of breaking changes. Migrating to 4.x now gives you a solid foundation before that wave hits. Right now I’m exploring how to pair Vitest with Bun for TypeScript script automation, running the test suite under Bun. That’ll be a separate post.

If you want to keep sharpening the TypeScript toolchain, building an MCP server with the TypeScript SDK step by step and writing a type-safe API with Hono fit the same track. Aligning your tests, runtime, and API layer on the Vite ecosystem cuts down config files noticeably.

References (Primary Sources)

These are the official docs I used to verify this post. Behavior changes often between versions, so always check the originals before an actual migration.

• Vitest official site — primary source for config, API, and changelogs
• Vitest official migration guide — documents Jest compatibility and the incompatibilities (globals, mockReset, etc.)
• Vitest Browser Mode guide — browser testing promoted to stable in Vitest 4
• Jest official site — config and API reference for the framework you’re migrating from