Migration Guide #

Migrating from Jest #

Vitest has been designed with a Jest compatible API, in order to make the migration from Jest as simple as possible. Despite those efforts, you may still run into the following differences:

Globals as a Default

Jest has their globals API enabled by default. Vitest does not. You can either enable globals via the globals configuration setting or update your code to use imports from the vitest module instead.

If you decide to keep globals disabled, be aware that common libraries like testing-library will not run auto DOM cleanup.

Module mocks

When mocking a module in Jest, the factory argument's return value is the default export. In Vitest, the factory argument has to return an object with each export explicitly defined. For example, the following jest.mock would have to be updated as follows:

- jest.mock('./some-path', () => 'hello')
+ vi.mock('./some-path', () => ({
+   default: 'hello',
+ })

- jest.mock('./some-path', () => 'hello')
+ vi.mock('./some-path', () => ({
+   default: 'hello',
+ })

For more details please refer to the vi.mock api

Auto-Mocking Behaviour

Unlike Jest, mocked modules in <root>/__mocks__ are not loaded unless vi.mock() is called. If you need them to be mocked in every test, like in Jest, you can mock them inside setupFiles.

Jasmine API

Jest exports various jasmine globals (such as jasmine.any()). Any such instances will need to be migrated to their Vitest counterparts.

Envs

Just like Jest, Vitest sets NODE_ENV to test, if it wasn't set before. Vitest also has a counterpart for JEST_WORKER_ID called VITEST_POOL_ID (always less than or equal to maxThreads), so if you rely on it, don't forget to rename it. Vitest also exposes VITEST_WORKER_ID which is a unique ID of a running worker - this number is not affected by maxThreads, and will increase with each created worker.

Done Callback

From Vitest v0.10.0, the callback style of declaring tests is deprecated. You can rewrite them to use async/await functions, or use Promise to mimic the callback style.

- it('should work', (done) => {
+ it('should work', () => new Promise(done => {
    // ...
    done()
- })
+ }))

- it('should work', (done) => {
+ it('should work', () => new Promise(done => {
    // ...
    done()
- })
+ }))

Hooks

beforeAll/beforeEach hooks may return teardown function in Vitest. Because of that you may need to rewrite your hooks declarations, if they return something other than undefined or null:

- beforeEach(() => setActivePinia(createTestingPinia()))
+ beforeEach(() => { setActivePinia(createTestingPinia()) })

- beforeEach(() => setActivePinia(createTestingPinia()))
+ beforeEach(() => { setActivePinia(createTestingPinia()) })

Types

Vitest doesn't expose a lot of types on Vi namespace, it exists mainly for compatibility with matchers, so you might need to import types directly from vitest instead of relying on Vi namespace:

- let fn: jest.Mock<string, [string]>
+ import type { Mock } from 'vitest'
+ let fn: Mock<[string], string>

- let fn: jest.Mock<string, [string]>
+ import type { Mock } from 'vitest'
+ let fn: Mock<[string], string>

Also, Vitest has Args type as a first argument instead of Returns, as you can see in diff.

Timers

Vitest doesn't support Jest's legacy timers.

it.each

Vitest intentionally doesn't support template literals for it.each. You will need to rewrite it to either an array of arguments, or array of objects:

Before:

it.each`
a    | b    | expected
${1} | ${3} | ${4}
${2} | ${2} | ${4}
`('adds $a to $b', ({ a, b, expected }) => {
  expect(add(a, b)).toEqual(expected)
})

it.each`
a    | b    | expected
${1} | ${3} | ${4}
${2} | ${2} | ${4}
`('adds $a to $b', ({ a, b, expected }) => {
  expect(add(a, b)).toEqual(expected)
})

After:

it.each([
  [1, 3, 4],
  [2, 2, 4],
])('adds %d to %d', (a, b, expected) => {
  expect(add(a, b)).toEqual(expected)
})

it.each([
  [1, 3, 4],
  [2, 2, 4],
])('adds %d to %d', (a, b, expected) => {
  expect(add(a, b)).toEqual(expected)
})

Vue Snapshots

This is not a Jest-specific feature, but if you previously were using Jest with vue-cli preset, you will need to install jest-serializer-vue package, and use it inside setupFiles:

vite.config.js

import { defineConfig } from 'vite'

export default defineConfig({
  test: {
    setupFiles: ['./tests/unit/setup.js']
  }
})

import { defineConfig } from 'vite'

export default defineConfig({
  test: {
    setupFiles: ['./tests/unit/setup.js']
  }
})

tests/unit/setup.js

import vueSnapshotSerializer from 'jest-serializer-vue'

expect.addSnapshotSerializer(vueSnapshotSerializer)

import vueSnapshotSerializer from 'jest-serializer-vue'

expect.addSnapshotSerializer(vueSnapshotSerializer)

Otherwise your snapshots will have a lot of escaped " characters.