Guía de Migración

Migrando desde Vitest 0.34.6

Requisitos Mínimos

Vitest 1.0 requiere Vite 5.0 y Node.js 18 o superior.

Todos los subpaquetes @vitest/* requieren la versión 1.0 de Vitest.

Actualización de Instantáneas #3961

Las comillas en las instantáneas ya no se escapan, y todas las instantáneas usan comillas inversas (`) incluso si la cadena es de una sola línea.

1. Las comillas ya no se escapan:

expect({ foo: 'bar' }).toMatchInlineSnapshot(`
  Object {
-    \\"foo\\": \\"bar\\",
+    "foo": "bar",
  }
`)

2. Las instantáneas de una línea ahora usan comillas "`" en lugar de ':

- expect('some string').toMatchInlineSnapshot('"some string"')
+ expect('some string').toMatchInlineSnapshot(`"some string"`)

También hubo cambios en el paquete @vitest/snapshot. Si no lo estás usando directamente, no necesitas cambiar nada.

• Ya no necesitas extender SnapshotClient solo para sobrescribir el método equalityCheck. Simplemente pásalo como isEqual al instanciarlo.
• client.setTest fue renombrado a client.startCurrentRun
• client.resetCurrent fue renombrado a client.finishCurrentRun

Los Pools se Estandarizan #4172

Eliminamos muchas opciones de configuración para facilitar la adaptación del ejecutor a tus necesidades. Por favor, revisa los ejemplos de migración si dependes de --threads u otras opciones relacionadas.

• --threads ahora es --pool=threads
• --no-threads ahora es --pool=forks
• --single-thread ahora es --poolOptions.threads.singleThread
• --experimental-vm-threads ahora es --pool=vmThreads
• --experimental-vm-worker-memory-limit ahora es --poolOptions.vmThreads.memoryLimit
• --isolate ahora es --poolOptions.<pool-name>.isolate y browser.isolate
• test.maxThreads ahora es test.poolOptions.<pool-name>.maxThreads
• test.minThreads ahora es test.poolOptions.<pool-name>.minThreads
• test.useAtomics ahora es test.poolOptions.<pool-name>.useAtomics
• test.poolMatchGlobs.child_process ahora es test.poolMatchGlobs.forks
• test.poolMatchGlobs.experimentalVmThreads ahora es test.poolMatchGlobs.vmThreads

{
  scripts: {
-    "test": "vitest --no-threads"
     // For identical behaviour:
+    "test": "vitest --pool forks --poolOptions.forks.singleFork"
     // Or multi parallel forks:
+    "test": "vitest --pool forks"

  }
}

{
  scripts: {
-    "test": "vitest --experimental-vm-threads"
+    "test": "vitest --pool vmThreads"
  }
}

{
  scripts: {
-    "test": "vitest --isolate false"
+    "test": "vitest --poolOptions.threads.isolate false"
  }
}

{
  scripts: {
-    "test": "vitest --no-threads --isolate false"
+    "test": "vitest --pool forks --poolOptions.forks.isolate false"
  }
}

Cambios en la Cobertura #4265, #4442

La opción coverage.all ahora está habilitada por defecto. Esto significa que todos los archivos del proyecto que coincidan con el patrón coverage.include serán procesados, incluso si no se ejecutan directamente en las pruebas.

La estructura de la API de umbrales de cobertura fue modificada, y ahora soporta la especificación de umbrales para archivos específicos usando patrones glob:

export default defineConfig({
  test: {
    coverage: {
-      perFile: true,
-      thresholdAutoUpdate: true,
-      100: true,
-      lines: 100,
-      functions: 100,
-      branches: 100,
-      statements: 100,
+      thresholds: {
+        perFile: true,
+        autoUpdate: true,
+        100: true,
+        lines: 100,
+        functions: 100,
+        branches: 100,
+        statements: 100,
+      }
    }
  }
})

Tipos de Simulación #4400

Algunos tipos fueron eliminados en favor de la nomenclatura "Mock" similar a la de Jest.

- import { EnhancedSpy, SpyInstance } from 'vitest'
+ import { MockInstance } from 'vitest'

WARNING

SpyInstance está obsoleto y se recomienda usar MockInstance en su lugar.

Simulaciones de Temporizadores #3925

vi.useFakeTimers() ya no simula automáticamente process.nextTick. Todavía es posible simular process.nextTick especificándolo explícitamente usando vi.useFakeTimers({ toFake: ['nextTick'] }).

Sin embargo, no es posible simular process.nextTick cuando se usa --pool=forks. Usa una opción --pool diferente si necesitas simular process.nextTick.

Migrando desde Jest

Vitest fue diseñado con una API compatible con Jest para simplificar la migración. A pesar de estos esfuerzos, aún puedes encontrarte con 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 en su lugar.

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

Mocks de Módulos

En Jest, al simular un módulo, el valor de retorno del argumento de la fábrica es la exportación predeterminada. En Vitest, el argumento de la fábrica debe devolver un objeto con cada exportación definida explícitamente. Por ejemplo, el siguiente jest.mock tendría que ser actualizado de la siguiente manera:

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

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

Comportamiento de Auto-Simulación

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'); 

Extendiendo la Simulación a Bibliotecas Externas

Jest lo hace por defecto. Cuando se simula un módulo y se quiere que esta simulación se extienda a otras bibliotecas externas que usan el mismo módulo, debes indicar explícitamente qué biblioteca de terceros quieres simular, para que la biblioteca externa forme parte de tu código fuente, usando server.deps.inline.

server.deps.inline: ["lib-name"]

Accediendo a los Valores de Retorno de una Promesa Simulada

Tanto Jest como Vitest almacenan los resultados de todas las llamadas simuladas en el array mock.results, donde los valores de retorno de cada llamada se almacenan en la propiedad value. Sin embargo, cuando se simula o se espía una promesa (por ejemplo, usando mockResolvedValue), en Jest la propiedad value será una promesa, mientras que en Vitest, se convertirá en un valor resuelto una vez que la promesa se resuelva.

await expect(spy.mock.results[0].value).resolves.toBe(123); 
expect(spy.mock.results[0].value).toBe(123); 

Envs (Variables de Entorno)

Al igual que Jest, Vitest establece NODE_ENV a test, si no se había establecido antes. Vitest también tiene una contraparte para JEST_WORKER_ID llamada VITEST_POOL_ID (siempre menor o igual que maxThreads), así que 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.

Sustituir Propiedad

Si quieres modificar el objeto, usarás replaceProperty API en Jest, puedes usar vi.stubEnv o vi.spyOn para hacer lo mismo también en Vitest.

Función de Retorno 'Done'

A partir de Vitest v0.10.0, el estilo de función de retorno para declarar pruebas está obsoleto. Puedes reescribirlos para usar funciones async/await, o usar Promesas para imitar el estilo de función de retorno.

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

Hooks

Los hooks beforeAll/beforeEach pueden devolver funciones de teardown 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());
}); 

En Jest, los hooks se llaman secuencialmente (uno tras otro). Por defecto, Vitest ejecuta los hooks en paralelo. Para usar el comportamiento de Jest, actualiza la opción sequence.hooks:

export default defineConfig({
  test: {
    sequence: {
      hooks: 'list', 
    }, 
  },
});

Tipos

Vitest no tiene un equivalente al espacio de nombres jest, por lo que necesitarás importar los tipos directamente desde vitest:

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.

Tiempo de Espera (Timeout)

Si usaste jest.setTimeout, necesitarías migrar a vi.setConfig:

jest.setTimeout(5_000); 
vi.setConfig({ testTimeout: 5_000 }); 

Capturas de Pantalla de Vue

Esta no es una característica específica de Jest, pero si previamente estabas usando Jest con el preset de 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 capturas de pantalla tendrán muchos caracteres " escapados.