If you have an existing project with Jest and you're considering switching to Vitest, this guide will walk you through the entire migration process step-by-step. Think why to convert jest to vitest.
Why Switch from Jest to Vitest?
Before diving into the conversion steps, let’s quickly understand why developers are choosing Vitest:
- Faster Testing: Vitest uses Vite’s native ESM (ES Modules) handling and HMR (Hot Module Replacement) under the hood, resulting in incredibly fast test startup and execution times.
- Built-in TypeScript Support: No need for ts-jest or separate configurations — Vitest understands TypeScript out of the box.
- Jest-Compatible API: Most Jest functions like describe, it, expect, and mocks are supported, reducing migration effort.
- Better Integration with Vite: If your project already uses Vite for building or bundling, Vitest fits naturally.
Step-by-Step Guide to Convert Jest to Vitest
1. Install Vitest and Related Packages
First, you’ll need to install Vitest and any other utilities you might need, like @vitest/coverage-c8 for code coverage.
npm install --save-dev vitest @vitest/coverage-c8
You might also need vite if it's not already a part of your project, since Vitest relies on Vite’s configuration system.
npm install --save-dev vite
If you are using React and want to test React components, you should install @testing-library/react and @testing-library/jest-dom too.
- Configure Vitest
Create or modify your vite.config.ts (or vite.config.js) to include Vitest settings:
/// <reference types="vitest" />
import { defineConfig } from 'vite';
export default defineConfig({
test: {
globals: true, // Optional: emulate Jest's global APIs
environment: 'jsdom', // Useful if you test browser environments (like React)
coverage: {
reporter: ['text', 'html'], // Optional: for test coverage reports
},
},
});
The globals: true option means you can use describe, test, and expect without importing them explicitly — just like in Jest.
If you use Node.js APIs (like fs, path, etc.), you can switch environment to "node".
- Update Your Test Scripts
In your package.json, update the test script:
{
"scripts": {
"test": "vitest",
"test:watch": "vitest --watch",
"test:coverage": "vitest run --coverage"
}
}
You can remove Jest-specific scripts like jest if you're fully switching.
- Migrate Your Test Files
Good news: Since Vitest's API is heavily inspired by Jest, you often don't need to change much! However, there are a few things to watch out for:
- Mocking:
- jest.fn() ➔ vi.fn()
- jest.mock() ➔ vi.mock()
- jest.fn() ➔ vi.fn()
For example:
import { vi } from 'vitest';
const mockFn = vi.fn();
vi.mock('./path/to/module');
Setup Files: If you have setupFilesAfterEnv in Jest, configure it in Vitest’s vite.config.ts:
test: {
setupFiles: ['./src/setupTests.ts'],
}
- Snapshot Testing: As of now, Vitest has experimental support for snapshot testing. You might want to wait or migrate snapshots manually if heavily used.
Custom Matchers: If you’re using matchers like toBeInTheDocument from @testing-library/jest-dom, import them explicitly in your setup file:
import '@testing-library/jest-dom';
- Deal with Non-Supported Features (if any)
Vitest covers most of Jest’s functionality, but if you are using rare Jest features like:
- Timers manipulation (jest.useFakeTimers()): Vitest has similar APIs under vi.useFakeTimers().
- Module mocking with complex factories: You might need slight syntax adjustments.
- Advanced Snapshot Testing: Still maturing in Vitest.
For most projects, especially those involving unit and component tests, you’ll barely notice the difference.
Common Migration Example
Jest Version:
import { render, screen } from '@testing-library/react';
import App from './App';
import '@testing-library/jest-dom';
test('renders welcome message', () => {
render(<App />);
expect(screen.getByText(/welcome to react/i)).toBeInTheDocument();
});
Vitest Version:
import { render, screen } from '@testing-library/react';
import App from './App';
import { describe, it, expect } from 'vitest';
import '@testing-library/jest-dom';
describe('App Component', () => {
it('renders welcome message', () => {
render(<App />);
expect(screen.getByText(/welcome to react/i)).toBeInTheDocument();
});
});
Notice: Just minimal changes like importing describe, it, and expect from vitest if you disabled globals.
Final Thoughts
Converting from Jest to Vitest can be surprisingly easy for most modern codebases. Thanks to the API similarity and powerful Vite engine underneath, Vitest offers faster, simpler, and more enjoyable testing experiences.
If you're using Vite, or simply want a faster alternative to Jest with better TypeScript support, it's definitely worth making the switch.
Give Vitest a try — you might wonder why you didn't do it earlier!