Guide de migration

Migration de Jest

Vitest propose une API compatible avec Jest, afin de rendre la migration depuis Jest aussi simple que possible. Malgré ces efforts, vous pourriez rencontrer les différences ci-dessous :

Globals par Défaut

Jest a son API globals activée par défaut. Vitest ne l'a pas. Vous pouvez soit activer les globales via l'option de configuration globals, soit mettre à jour votre code pour utiliser les importations du module vitest à la place.

Si vous décidez de garder les globales désactivées, sachez que les bibliothèques courantes comme testing-library n'exécuteront pas le "nettoyage automatique du DOM" (https://testing-library.com/docs/svelte-testing-library/api/#cleanup).

Simulation de modules

Lorsqu'on simule un module dans Jest, la valeur renvoyée par l'argument factory est l'export par défaut. Dans Vitest, l'argument factory doit retourner un objet avec chaque export explicitement défini. Par exemple, le jest.mock suivant devrait être mis à jour comme suit :

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

Pour plus de détails, veuillez vous référer à la section de l'API vi.mock.

Comportement d'Auto-Simulation

Contrairement à Jest, les modules simulés dans <root>/__mocks__ ne sont pas chargés à moins que vi.mock() ne soit appelé. Si vous avez besoin qu'ils soient simulés dans chaque test, comme dans Jest, vous pouvez les simuler dans setupFiles.

Importer l'original d'un package simulé

Si vous ne simulez qu'une partie d'un package, vous avez peut-être utilisé la fonction requireActual de Jest auparavant. Dans Vitest, vous devriez remplacer ces appels par vi.importActual.

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

Variables d'environnement (Envs)

Comme Jest, Vitest définit NODE_ENV sur test si elle n'était pas déjà définie. Vitest possède également un équivalent à JEST_WORKER_ID, nommé VITEST_POOL_ID (toujours inférieur ou égal à maxThreads). Si vous en dépendez, n'oubliez pas de le renommer. Vitest expose également VITEST_WORKER_ID qui est un ID unique d'un worker en cours d'exécution - ce nombre n'est pas affecté par maxThreads, et augmentera avec chaque worker créé.

Si vous utilisiez l'API replaceProperty dans Jest pour modifier les variables d'environnement, vous pouvez utiliser vi.stubEnv pour le faire dans Vitest.

Callback 'Done'

À partir de Vitest v0.10.0, la déclaration de tests par callback est dépréciée. Vous pouvez les réécrire pour utiliser des fonctions async/await, ou utiliser Promise pour imiter le style de callback.

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

Hooks

Les hooks beforeAll/beforeEach peuvent retourner une fonction de démontage (teardown) dans Vitest. Par conséquent, vous devrez peut-être réécrire vos déclarations de hooks si elles renvoient une valeur autre que undefined ou null.

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

Types

Vitest n'expose que peu de types dans l'espace de noms Vi, celui-ci étant principalement destiné à assurer la compatibilité avec les matchers. Il peut donc être nécessaire d'importer les types directement depuis vitest au lieu de se reposer sur l'espace de noms Vi.

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

De plus, Vitest utilise le type Args comme premier argument au lieu de Returns, comme illustré dans le diff.

Minuteurs (Timers)

Vitest ne supporte pas les timers legacy de Jest.

Vue Snapshots

Bien que cette fonctionnalité ne soit pas spécifique à Jest, si vous utilisiez auparavant Jest avec le preset vue-cli, vous devrez installer le paquet jest-serializer-vue et l'utiliser dans 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);

Dans le cas contraire, vos snapshots contiendront de nombreux caractères " échappés.