Guia de Migração

Migrando do Jest

O Vitest foi projetado com uma API compatível com o Jest, a fim de tornar a migração o mais simples possível. Apesar desses esforços, você ainda pode encontrar as seguintes diferenças:

Globais por Padrão

O Jest tem sua API global habilitada por padrão. O Vitest não. Você pode habilitar os globais através da configuração globals ou atualizar seu código para usar importações do módulo vitest.

Se você decidir manter os globais desabilitados, esteja ciente de que bibliotecas comuns como testing-library não executarão a limpeza automática do DOM.

Simulações de Módulo

Ao simular um módulo no Jest, o valor de retorno do argumento da fábrica é a exportação padrão do módulo. No Vitest, o argumento da fábrica deve retornar um objeto com cada exportação explicitamente definida. Por exemplo, o seguinte jest.mock precisaria ser atualizado da seguinte forma:

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

Para mais detalhes, consulte a seção da API vi.mock.

Comportamento de Simulação Automática

Ao contrário do Jest, os módulos simulados em <root>/__mocks__ não são carregados a menos que vi.mock() seja chamado. Se você precisar que eles sejam simulados em todos os testes, assim como no Jest, você pode simulá-los dentro de setupFiles.

Importando o original de um pacote simulado

Se você estiver simulando apenas parcialmente um pacote, você pode ter usado a função requireActual do Jest anteriormente. No Vitest, você deve substituir essas chamadas por vi.importActual.

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

Variáveis de Ambiente

Assim como o Jest, o Vitest define NODE_ENV para test, caso não tenha sido definido antes. O Vitest também tem uma contrapartida para JEST_WORKER_ID chamada VITEST_POOL_ID (sempre menor ou igual a maxThreads). Se você depende dela, não se esqueça de renomeá-la. O Vitest também expõe VITEST_WORKER_ID, que é um ID único de um worker em execução - este número não é afetado por maxThreads e aumentará com cada worker criado.

Se você quiser modificar as variáveis de ambiente, e usava a API replaceProperty no Jest, você pode usar vi.stubEnv para fazer o mesmo no Vitest.

Callback de Conclusão

A partir do Vitest v0.10.0, o estilo de callback para declarar testes está obsoleto. Você pode reescrevê-los para usar funções async/await, ou usar Promises para imitar o estilo de callback.

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

Hooks

Os hooks beforeAll/beforeEach podem retornar uma função de teardown no Vitest. Por causa disso, você pode precisar reescrever suas declarações de hooks, se retornarem algo diferente de undefined ou null:

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

Tipos

O Vitest não expõe muitos tipos no namespace Vi. Ele existe principalmente para garantir compatibilidade com matchers, então você pode precisar importar tipos diretamente de vitest em vez de depender do namespace Vi:

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

Além disso, o Vitest tem o tipo Args como primeiro argumento em vez de Returns, como você pode ver na diferença.

Temporizadores

O Vitest não oferece suporte aos temporizadores legados do Jest.

Snapshots do Vue

Este não é um recurso exclusivo do Jest, mas se você estava usando o Jest com o preset vue-cli, você precisará instalar o pacote jest-serializer-vue e usá-lo 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);

Caso contrário, seus snapshots terão muitos caracteres " escapados.