Guide de migration

Migration depuis Vitest 0.34.6

Exigences minimales

Vitest 1.0 requiert Vite 5.0 et Node.js 18 ou supérieur.

Tous les sous-packages @vitest/* requièrent la version 1.0 de Vitest.

Mise à jour des clichés (Snapshots) #3961

Les guillemets dans les clichés ne sont plus échappés, et tous les clichés utilisent des guillemets inversés (`) même si la chaîne ne contient qu'une seule ligne.

1. Les guillemets ne sont plus échappés :

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

2. Les clichés d'une seule ligne utilisent désormais les guillemets "`" au lieu de ' :

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

Des modifications ont également été apportées au package @vitest/snapshot. Si vous ne l'utilisez pas directement, aucune modification n'est nécessaire.

• Il n'est plus nécessaire d'étendre SnapshotClient uniquement pour remplacer la méthode equalityCheck : passez-la simplement en tant que isEqual lors de l'initialisation d'une instance.
• client.setTest a été renommé en client.startCurrentRun.
• client.resetCurrent a été renommé en client.finishCurrentRun.

Standardisation des Pools #4172

Nous avons supprimé de nombreuses options de configuration afin de simplifier la configuration du runner selon vos besoins. Veuillez consulter les exemples de migration si vous utilisiez --threads ou d'autres options associées.

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

Modifications de la couverture de code (Coverage) #4265, #4442

L'option coverage.all est maintenant activée par défaut. Cela signifie que tous les fichiers du projet correspondant au motif coverage.include seront pris en compte, même s'ils ne sont pas exécutés.

La structure des API de seuils de couverture a été modifiée, et elle prend désormais en charge la spécification de seuils pour des fichiers spécifiques à l'aide de motifs globaux :

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,
+      }
    }
  }
})

Types de Mock #4400

Certains types ont été supprimés en faveur de la nomenclature "Mock" de style Jest.

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

WARNING

SpyInstance est déprécié en faveur de MockInstance et sera supprimé dans la prochaine version majeure.

Simulations de Timer #3925

vi.useFakeTimers() ne simule plus automatiquement process.nextTick. Il est toujours possible de simuler process.nextTick en le spécifiant explicitement en utilisant vi.useFakeTimers({ toFake: ['nextTick'] }).

Cependant, il n'est pas possible de simuler process.nextTick lors de l'utilisation de --pool=forks. Utilisez une autre option --pool si vous avez besoin de la simulation de process.nextTick.

Migration depuis Jest

Vitest a été conçu avec une API compatible avec Jest, afin de rendre la migration depuis Jest aussi simple que possible. Malgré ces efforts, vous pouvez toujours rencontrer les différences suivantes :

Globals par défaut

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

Si vous décidez de désactiver les variables globales, sachez que les bibliothèques courantes comme testing-library ne pourront pas exécuter le nettoyage automatique du DOM.

Mocks de module

Lors de la simulation d'un module dans Jest, la valeur de retour de l'argument factory est l'export par défaut. Dans Vitest, l'argument factory doit renvoyer 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-Mocking

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 à l'intérieur de setupFiles.

Importer l'original d'un package simulé

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

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

Étendre la simulation aux bibliothèques externes

Par défaut, Jest étend la simulation d'un module aux autres bibliothèques externes qui l'utilisent. Avec Vitest, vous devez explicitement indiquer les bibliothèques tierces à simuler. Pour ce faire, ajoutez ces bibliothèques à la propriété server.deps.inline dans votre configuration.

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

Accéder à la valeur de retour d'une promesse simulée

Jest et Vitest stockent tous les deux les résultats de tous les appels simulés dans le tableau mock.results, où les valeurs de retour de chaque appel sont stockées dans la propriété value. Cependant, lors de la simulation ou de l'espionnage d'une promesse (par exemple, en utilisant mockResolvedValue), dans Jest, la propriété value sera une promesse, tandis que dans Vitest, elle deviendra la valeur résolue une fois que la promesse est résolue.

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

Envs (Environnements)

Tout comme Jest, Vitest définit NODE_ENV sur test, s'il n'était pas défini auparavant. Vitest fournit également une variable équivalente à JEST_WORKER_ID, nommée VITEST_POOL_ID (toujours inférieure ou égale à maxThreads). Si votre code utilise JEST_WORKER_ID, pensez à la remplacer par VITEST_POOL_ID. 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éé.

Remplacer la propriété

Si vous souhaitez modifier un objet, vous utilisiez l'API replaceProperty dans Jest. Vous pouvez utiliser vi.stubEnv ou vi.spyOn pour faire de même dans Vitest.

Callback de fin (Done)

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

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

Hooks

Les hooks beforeAll/beforeEach peuvent renvoyer une fonction de teardown dans Vitest. Pour cette raison, il peut être nécessaire de modifier vos déclarations de hooks si elles retournent une valeur autre que undefined ou null :

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

Dans Jest, les hooks sont appelés séquentiellement (l'un après l'autre). Par défaut, Vitest exécute les hooks en parallèle. Pour utiliser le comportement de Jest, mettez à jour l'option sequence.hooks :

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

Types

Vitest n'a pas d'équivalent à l'espace de noms jest, vous devrez donc importer les types directement depuis vitest :

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

De plus, Vitest a le type Args comme premier argument au lieu de Returns, comme vous pouvez le voir dans le diff.

Timers

Vitest ne prend pas en charge les timers hérités de Jest.

Timeout

Si vous avez utilisé jest.setTimeout, vous devrez le remplacer par vi.setConfig :

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

Clichés Vue

Ce n'est pas une fonctionnalité spécifique à Jest, mais si vous utilisiez auparavant Jest avec le preset vue-cli, vous devrez installer le package jest-serializer-vue, et l'utiliser à l'intérieur 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);

Sinon, vos clichés auront beaucoup de caractères " échappés.