Guia de Migração

Migrando do Vitest 0.34.6

Requisitos Mínimos

Vitest 1.0 requer Vite 5.0 e Node.js 18 ou superior.

Todos os subpacotes @vitest/* requerem a versão 1.0 do Vitest.

Atualização de Snapshots #3961

As aspas nos snapshots não são mais escapadas, e todos os snapshots usam crase (`) mesmo que a string seja de uma única linha.

1. Aspas não são mais escapadas:

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

2. Snapshots de uma linha agora usam crases "`" em vez de apóstrofos ':

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

Também houve mudanças no pacote @vitest/snapshot. Se você não estiver usando-o diretamente, não precisa mudar nada.

• Você não precisa mais estender SnapshotClient apenas para sobrescrever o método equalityCheck: basta passá-lo como isEqual ao iniciar uma instância
• client.setTest foi renomeado para client.startCurrentRun
• client.resetCurrent foi renomeado para client.finishCurrentRun

Pools são Padronizados #4172

Removemos muitas opções de configuração para facilitar a configuração do executor às suas necessidades. Recomendamos que você consulte os exemplos de migração se estiver utilizando --threads ou outras flags relacionadas.

• --threads agora é --pool=threads
• --no-threads agora é --pool=forks
• --single-thread agora é --poolOptions.threads.singleThread
• --experimental-vm-threads agora é --pool=vmThreads
• --experimental-vm-worker-memory-limit agora é --poolOptions.vmThreads.memoryLimit
• --isolate agora é --poolOptions.<pool-name>.isolate e browser.isolate
• test.maxThreads agora é test.poolOptions.<pool-name>.maxThreads
• test.minThreads agora é test.poolOptions.<pool-name>.minThreads
• test.useAtomics agora é test.poolOptions.<pool-name>.useAtomics
• test.poolMatchGlobs.child_process agora é test.poolMatchGlobs.forks
• test.poolMatchGlobs.experimentalVmThreads agora é 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"
  }
}

Mudanças na Cobertura #4265, #4442

A opção coverage.all agora está habilitada por padrão. Isso significa que todos os arquivos do projeto que correspondem ao padrão coverage.include serão processados, mesmo que não sejam executados.

A estrutura da API de limites de cobertura foi modificada e agora permite a especificação de limites para arquivos específicos através do uso de padrões globais:

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 Mock #4400

Alguns tipos foram removidos em favor da nomenclatura "Mock" no estilo Jest.

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

WARNING

SpyInstance está obsoleto em favor de MockInstance e será removido na próxima versão principal.

Mocks de Timer #3925

vi.useFakeTimers() agora não simula mais automaticamente process.nextTick. Ainda é possível simular process.nextTick especificando-o explicitamente usando vi.useFakeTimers({ toFake: ['nextTick'] }).

No entanto, simular process.nextTick não é possível ao usar --pool=forks. Use uma opção --pool diferente se precisar simular process.nextTick.

Migrando do Jest

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

Globais por Padrão

O Jest possui sua API de globais habilitada por padrão, diferentemente do Vitest. Para habilitar os globais, você pode utilizar a configuração globals ou modificar seu código para importar os elementos necessários diretamente 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.

Mocks de Módulo

No Jest, ao simular um módulo, o valor retornado pelo argumento de fábrica corresponde à exportação padrão. Já no Vitest, o argumento de fábrica deve retornar um objeto contendo cada exportação explicitamente definida. Por exemplo, o seguinte jest.mock teria que 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 Auto-Mocking

Diferentemente do Jest, os módulos simulados localizados em <root>/__mocks__ não são carregados automaticamente, a menos que a função vi.mock() seja explicitamente invocada. Se você precisar que eles sejam simulados em todos os testes, 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 anteriormente a função requireActual do Jest. No Vitest, você deve substituir essas chamadas por vi.importActual.

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

Estendendo o Mocking para Bibliotecas Externas

Diferentemente do Jest, que realiza essa ação por padrão, ao simular um módulo e desejar que essa simulação seja aplicada a outras bibliotecas externas que utilizam o mesmo módulo, é necessário especificar explicitamente qual biblioteca de terceiros deve ser simulada. Isso garante que a biblioteca externa seja considerada parte do seu código-fonte, o que pode ser feito através da configuração server.deps.inline.

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

Acessando os Valores de Retorno de uma Promise Simulada

Tanto o Jest quanto o Vitest armazenam os resultados de todas as chamadas de mock no array mock.results, onde os valores de retorno de cada chamada são armazenados na propriedade value. No entanto, ao simular ou espionar uma promise (por exemplo, usando mockResolvedValue), no Jest a propriedade value será uma promise, enquanto no Vitest, ela se tornará um valor resolvido quando a promise for resolvida.

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

Variáveis de Ambiente

Assim como o Jest, o Vitest define NODE_ENV como test, se não foi definido antes. O Vitest também oferece uma variável equivalente a JEST_WORKER_ID, denominada VITEST_POOL_ID (cujo valor é sempre menor ou igual a maxThreads). Caso seu código dependa da JEST_WORKER_ID, lembre-se de realizar a substituição pela nova variável. 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.

Substituir Propriedade

Se você quiser modificar o objeto, você usará replaceProperty API no Jest, você pode usar vi.stubEnv ou vi.spyOn para fazer o mesmo também no Vitest.

Callback Done

A partir da versão v0.10.0 do Vitest, a utilização de callbacks para declarar testes foi descontinuada. Você pode reescrevê-los para usar funções async/await, ou usar Promise para imitar o estilo de callback.

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

Hooks

Os hooks beforeAll/beforeEach podem retornar função teardown no Vitest. Portanto, pode ser necessário reescrever as declarações dos seus hooks caso eles retornem um valor diferente de undefined ou null:

beforeEach(() => setActivePinia(createTestingPinia())); 
beforeEach(() => {
  setActivePinia(createTestingPinia());
}); 

No Jest, os hooks são chamados sequencialmente (um após o outro). Por padrão, o Vitest executa os hooks em paralelo, ao contrário do Jest. Para usar o comportamento do Jest, atualize a opção sequence.hooks:

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

Tipos

O Vitest não tem um equivalente ao namespace jest, então você deve importar os tipos diretamente de vitest:

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.

Timers

O Vitest não suporta os timers antigos do Jest.

Timeout

Se você usou jest.setTimeout, você precisaria migrar para vi.setConfig:

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

Snapshots do Vue

Este não é um recurso específico 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 apresentarão um grande número de caracteres " escapados.