Vitest as a Jest Replacement in TypeScript: Fast Setup, Speed Optimization, and In-source Testing

Development tutorial - IT technology blog
Development tutorial - IT technology blog

Jest Still Works, But There’s a Problem

If you’re using Jest with TypeScript, you’ve probably seen this scenario: running the test suite for the first time takes 10–15 seconds just to start up, then every time you edit a small file you wait a few more seconds. The reason is that Jest needs to transpile TypeScript through Babel or ts-jest before running, while its module system still operates in the old CommonJS style.

Vitest addresses exactly that. TypeScript is processed by esbuild — many times faster than Babel. More importantly, the entire transform pipeline only starts once, without resetting every time you edit a file.

I tried migrating a recently completed web app project — around 180 test files, 5 developers working together — from Jest to Vitest. Full test suite runtime dropped from 47 seconds down to 11 seconds. Watch mode is nearly instantaneous. The whole team noticed the difference after the first day.

Installing Vitest in a TypeScript Project

Projects already using Vite have an easier time, but it’s not required — Vitest runs standalone just fine. Installation is like any other dev dependency:

Adding Vitest to Your Project

# If using npm
npm install -D vitest

# If using pnpm
pnpm add -D vitest

# If using yarn
yarn add -D vitest

Testing UI components (React, Vue…) requires the jsdom environment:

npm install -D @vitest/ui jsdom

Adding Scripts to package.json

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

vitest without run runs in watch mode — it auto-detects file changes and re-runs related tests. vitest run runs once then exits, used for CI/CD.

Detailed Configuration

Integrating into vite.config.ts

Already have a vite.config.ts? Add the test block directly — no need for a separate config file:

/// <reference types="vitest" />
import { defineConfig } from 'vite'

export default defineConfig({
  test: {
    globals: true,          // use describe/it/expect without importing
    environment: 'jsdom',   // remove this line for pure Node.js tests
    setupFiles: './src/test/setup.ts',
    include: ['**/*.{test,spec}.{ts,tsx}'],
    coverage: {
      reporter: ['text', 'html'],
      exclude: ['node_modules/', 'src/test/']
    }
  }
})

The /// <reference types="vitest" /> line at the top tells TypeScript to recognize types for describe, it, expect… without any extra declarations.

Or Use a Separate vitest.config.ts File

Not using Vite? Create a standalone vitest.config.ts file:

import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    globals: true,
    environment: 'node',
    include: ['src/**/*.test.ts'],
    reporters: ['verbose']
  }
})

Updating tsconfig.json

Add Vitest types to tsconfig.json so the IDE doesn’t report errors:

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

Writing Tests — Syntax Nearly 100% Identical to Jest

This is why migrating to Vitest is less painful than you’d expect: old Jest test files run immediately without any changes. If you already know Jest, there’s nothing new to learn.

// src/utils/format.test.ts
import { describe, it, expect } from 'vitest'
import { formatCurrency } from './format'

describe('formatCurrency', () => {
  it('formats VND amount correctly', () => {
    expect(formatCurrency(1500000)).toBe('1,500,000 ₫')
  })

  it('returns 0 ₫ when input is 0', () => {
    expect(formatCurrency(0)).toBe('0 ₫')
  })

  it('handles negative numbers', () => {
    expect(formatCurrency(-50000)).toBe('-50,000 ₫')
  })
})

Enable globals: true in config to drop the import line entirely — use it just like Jest.

In-source Testing — A Unique Feature Exclusive to Vitest

Jest doesn’t have this. In-source Testing lets you write tests directly inside the source file, without creating a separate .test.ts file. Small utility function? The test sits right below the function definition — anyone reading the code immediately sees what the function does without opening another file.

How It Works

Vitest uses an if (import.meta.vitest) block. In production builds, Vite tree-shakes the entire block out — bundle size is unaffected:

// src/utils/math.ts
export function clamp(value: number, min: number, max: number): number {
  return Math.min(Math.max(value, min), max)
}

// Test lives directly in the source file
if (import.meta.vitest) {
  const { it, expect } = import.meta.vitest

  it('clamp keeps value within [min, max] range', () => {
    expect(clamp(5, 0, 10)).toBe(5)
    expect(clamp(-1, 0, 10)).toBe(0)
    expect(clamp(15, 0, 10)).toBe(10)
  })
}

Enabling In-source Testing in Config

// vite.config.ts
export default defineConfig({
  test: {
    includeSource: ['src/**/*.ts']  // add this line
  },
  define: {
    // Remove test code from production build
    'import.meta.vitest': 'undefined'
  }
})

I use this pattern for helper functions in projects: instead of creating a separate date-utils.test.ts file, tests live right below the function definition. During code review, readers immediately see what the function does and what results to expect — no need to open another file.

Running Tests and Tracking Coverage

Running Tests for the First Time

# Watch mode (development)
npm test

# Run once (CI)
npm run test:run

# View visual UI in browser
npm run test:ui

UI mode (--ui) opens a dashboard in the browser, displaying each test in a file tree with clear pass/fail color coding. Useful when debugging a large test suite with many nested describes.

Viewing the Coverage Report

Install the coverage package:

npm install -D @vitest/coverage-v8
npm run coverage

The output shows a stats table per file: what percentage of statements, branches, functions, and lines are covered. An HTML report is generated in the coverage/ directory — open it in a browser to see line-by-line details.

Integrating with CI/CD

In GitHub Actions or GitLab CI, replace jest with vitest run:

- name: Run tests
  run: npm run test:run

- name: Check coverage
  run: npm run coverage

Key Differences to Note When Migrating from Jest

  • Mock module: use vi.mock() instead of jest.mock()
  • Spy: vi.spyOn() instead of jest.spyOn()
  • Fake timers: vi.useFakeTimers() instead of jest.useFakeTimers()
  • Snapshot: syntax stays the same, snapshot files stored in __snapshots__ as before

Most of the time you just need to find-and-replace jest. with vi. and you’re done. I migrated 180 test files with a sed command in 2 minutes — only a few spots needed manual fixes due to more complex logic.

When to Use Vitest vs. When to Keep Jest

The decision isn’t complicated. Using Vite? Choose Vitest, no further thought needed. Building a standalone TypeScript library? Vitest is a solid default choice there too.

Old CRA, Next.js with Webpack, or a specialized setup you don’t want to touch — Jest remains stable, no need to switch.

Starting a new project or migrating to Vite? Pick Vitest from the start. 11 seconds instead of 47 seconds per full test suite run — that adds up to significant time saved over a few months of development.

Share: