Guía de Migración

Migración desde Jest

Vitest ha sido diseñado con una API compatible con Jest, con el objetivo de simplificar al máximo la migración desde Jest. A pesar de estos esfuerzos, es posible que encuentres las siguientes diferencias:

Globales por defecto

Jest tiene su API de globales habilitada por defecto. Vitest no. Puedes habilitar los globales a través de la configuración globals o actualizar tu código para usar importaciones desde el módulo vitest.

Si decides mantener los globales deshabilitados, ten en cuenta que bibliotecas comunes como testing-library no realizarán la limpieza automática del DOM.

Simulaciones de Módulos

Cuando se simula un módulo en Jest, el valor que devuelve el argumento de la función de fábrica es la exportación por defecto. En Vitest, el argumento de la función de fábrica debe devolver un objeto con cada exportación definida explícitamente. Por ejemplo, el siguiente jest.mock debería actualizarse de la siguiente manera:

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

Para más detalles, consulta la sección de la API vi.mock.

Comportamiento del Auto-Mocking

A diferencia de Jest, los módulos simulados en <root>/__mocks__ no se cargan a menos que se llame a vi.mock(). Si necesitas que se simulen en cada test, como en Jest, puedes simularlos dentro de setupFiles.

Importando el original de un paquete simulado

Si solo estás simulando parcialmente un paquete, es posible que hayas usado previamente la función requireActual de Jest. En Vitest, debes reemplazar estas llamadas con vi.importActual.

- const { cloneDeep } = jest.requireActual('lodash/cloneDeep')
+ const { cloneDeep } = await vi.importActual('lodash/cloneDeep')

Variables de Entorno

Al igual que Jest, Vitest establece NODE_ENV a test si no se había establecido previamente. Vitest también tiene una contraparte para JEST_WORKER_ID llamada VITEST_POOL_ID (siempre menor o igual a maxThreads). Si dependes de ella, no olvides renombrarla. Vitest también expone VITEST_WORKER_ID, que es un ID único de un worker en ejecución. Este número no se ve afectado por maxThreads y aumentará con cada worker creado.

Si quieres modificar las variables de entorno, y usabas la replaceProperty API en Jest, puedes usar vi.stubEnv para hacerlo también en Vitest.

Callback 'done'

Desde Vitest v0.10.0, el estilo de callback para declarar pruebas está obsoleto. Puedes reescribirlas para usar funciones async/await, o usar Promise para simular el estilo de callback.

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

Hooks

Los hooks beforeAll/beforeEach pueden devolver una función de limpieza en Vitest. Debido a esto, es posible que necesites reescribir tus declaraciones de hooks si devuelven algo que no sea undefined o null:

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

Tipos

Vitest no expone muchos tipos en el espacio de nombres Vi. Este espacio de nombres existe principalmente para la compatibilidad con los matchers, por lo que es posible que necesites importar los tipos directamente desde vitest en lugar de depender del espacio de nombres Vi:

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

Además, Vitest tiene el tipo Args como primer argumento en lugar de Returns, como puedes ver en el diff.

Temporizadores

Vitest no soporta los temporizadores heredados de Jest.

Instantáneas de Vue

Esta no es una característica específica de Jest, pero si previamente estabas usando Jest con el preset vue-cli, necesitarás instalar el paquete jest-serializer-vue y usarlo dentro de setupFiles:

vite.config.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);

De lo contrario, tus instantáneas tendrán muchos caracteres de comillas escapadas.