Guida alla Migrazione

Migrazione da Vitest 0.34.6

Requisiti Minimi

Vitest 1.0 richiede Vite 5.0 e Node.js 18 o versioni successive.

Tutti i pacchetti secondari @vitest/* richiedono Vitest versione 1.0.

Aggiornamento degli Snapshot #3961

Le virgolette negli snapshot non vengono più sottoposte a escape e tutti gli snapshot utilizzano le virgolette inverse (`) anche se la stringa è su una sola riga.

1. Le virgolette non vengono più sottoposte a escape:

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

2. Gli snapshot su una riga ora usano le virgolette "`" invece di ':

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

Ci sono state anche modifiche nel pacchetto @vitest/snapshot. Se non lo si utilizza direttamente, non è necessario apportare modifiche.

• Non è più necessario estendere SnapshotClient solo per sovrascrivere il metodo equalityCheck: è sufficiente passarlo come isEqual quando si crea un'istanza.
• client.setTest è stato rinominato in client.startCurrentRun
• client.resetCurrent è stato rinominato in client.finishCurrentRun

I Pool sono Standardizzati #4172

Sono state rimosse diverse opzioni di configurazione per semplificare la configurazione del runner in base alle proprie esigenze. Consultare gli esempi di migrazione se si utilizzano --threads o altri flag correlati.

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

Modifiche alla Coverage #4265, #4442

L'opzione coverage.all è ora abilitata per impostazione predefinita. Ciò significa che tutti i file del progetto che corrispondono al pattern coverage.include verranno elaborati anche se non vengono eseguiti test su di essi.

L'API delle soglie di coverage ha cambiato formato e ora supporta la specifica delle soglie per file specifici utilizzando pattern 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,
+      }
    }
  }
})

Tipi di Mock #4400

Alcuni tipi sono stati rimossi a favore della denominazione "Mock" in stile Jest.

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

WARNING

SpyInstance è deprecato a favore di MockInstance e verrà rimosso nella prossima versione principale.

Timer mocks #3925

vi.useFakeTimers() non simula più automaticamente process.nextTick. È comunque possibile simulare process.nextTick specificandolo esplicitamente usando vi.useFakeTimers({ toFake: ['nextTick'] }).

Tuttavia, non è possibile simulare process.nextTick quando si utilizza --pool=forks. Utilizzare un'opzione --pool diversa se è necessario simulare process.nextTick.

Migrazione da Jest

Vitest è stato progettato con un'API compatibile con Jest, al fine di rendere la migrazione da Jest il più semplice possibile. Nonostante questi sforzi, potresti comunque riscontrare le seguenti differenze:

Variabili globali come impostazione predefinita

Jest ha la sua API globale abilitata per impostazione predefinita. Vitest no. Puoi abilitare le globali tramite l'impostazione di configurazione globals oppure aggiornare il tuo codice per utilizzare gli import dal modulo vitest.

Se decidi di mantenere le globali disabilitate, tieni presente che le librerie comuni come testing-library non eseguiranno la pulizia automatica del DOM cleanup.

Module Mocks

Quando si simula un modulo in Jest, il valore di ritorno dell'argomento factory è l'export predefinito. In Vitest, l'argomento factory deve restituire un oggetto con ogni export definito esplicitamente. Ad esempio, il seguente jest.mock dovrebbe essere aggiornato come segue:

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

Per maggiori dettagli, fare riferimento alla sezione dell'API vi.mock.

Comportamento di Auto-Mocking

A differenza di Jest, i moduli simulati in <root>/__mocks__ non vengono caricati a meno che non venga chiamato vi.mock(). Se hai bisogno che vengano simulati in ogni test, come in Jest, puoi farlo all'interno di setupFiles.

Importare l'Originale di un Pacchetto Simulato

Se stai simulando solo parzialmente un pacchetto, potresti aver usato in precedenza la funzione requireActual di Jest. In Vitest, dovresti sostituire queste chiamate con vi.importActual.

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

Estendere il mocking a librerie esterne

Mentre Jest lo fa per impostazione predefinita, quando si simula un modulo e si desidera che questo mocking sia esteso ad altre librerie esterne che utilizzano lo stesso modulo, bisogna specificare esplicitamente la libreria da simulare, in modo che la libreria esterna faccia parte del codice sorgente, utilizzando server.deps.inline.

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

Accesso ai Valori di Ritorno di una Promise Simulata

Sia Jest che Vitest memorizzano i risultati di tutte le chiamate mock nell'array mock.results, dove i valori di ritorno di ogni chiamata sono memorizzati nella proprietà value. Tuttavia, quando si simula o si spia una promise (ad esempio, utilizzando mockResolvedValue), in Jest la proprietà value sarà una promise, mentre in Vitest diventerà un valore risolto quando la promise viene risolta.

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

Envs (Variabili d'Ambiente)

Proprio come Jest, Vitest assegna a test il valore di NODE_ENV se non era già stato impostato. Vitest ha anche una controparte per JEST_WORKER_ID chiamata VITEST_POOL_ID (sempre minore o uguale a maxThreads), quindi se fai affidamento su di essa, non dimenticare di rinominarla. Vitest espone anche VITEST_WORKER_ID che è un ID univoco di un worker in esecuzione - questo numero non è influenzato da maxThreads e aumenterà con ogni worker creato.

Replace property (Sostituisci proprietà)

Se si desidera modificare l'oggetto, si utilizzerà replaceProperty API in Jest, è possibile utilizzare vi.stubEnv o vi.spyOn per fare lo stesso anche in Vitest.

Done Callback (Callback di Fine)

Dalla v0.10.0 di Vitest, lo stile callback per dichiarare i test è deprecato. Puoi riscriverli per utilizzare funzioni async/await oppure utilizzare Promise per imitare lo stile callback.

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

Hooks

Gli hook beforeAll/beforeEach possono restituire la funzione di teardown in Vitest. Per questo motivo, potrebbe essere necessario riscrivere le dichiarazioni degli hook, se restituiscono qualcosa di diverso da undefined o null:

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

In Jest gli hook vengono chiamati in sequenza (uno dopo l'altro). Di default, Vitest esegue gli hook in modo parallelo. Per utilizzare il comportamento di Jest, aggiorna l'opzione sequence.hooks:

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

Types (Tipi)

Vitest non ha un equivalente al namespace jest, quindi dovrai importare i tipi direttamente da vitest:

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

Inoltre, Vitest ha il tipo Args come primo argomento invece di Returns, come puoi vedere nella differenza.

Timers (Timer)

Vitest non supporta i timer legacy di Jest.

Timeout

Se hai usato jest.setTimeout, dovrai migrare a vi.setConfig:

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

Vue Snapshots

Questa non è una caratteristica specifica di Jest, ma se in precedenza utilizzavi Jest con il preset vue-cli, dovrai installare il pacchetto jest-serializer-vue e utilizzarlo all'interno di 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);

Altrimenti, gli snapshot conterranno molti caratteri " con escape.