Aller au contenu principal
Version : 28.0

De la v27 à la v28

Mise à jour de la v27 à la v28 de Jest ? Ce guide a pour but de vous aider à refactoriser votre configuration et vos tests.

info

Consultez le changelog pour la liste complète des modifications.

Compatibilité

Les versions de Node supportées sont 12.13, 14.15, 16.10 et supérieures.

Si vous prévoyez d'utiliser les définitions de type de Jest (ou de l'un de ses packages), assurez-vous d'installer TypeScript version 4.3 ou supérieure.

Options de Configuration

extraGlobals

L'option extraGlobals a été renommée en sandboxInjectedGlobals :

- extraGlobals: ['Math']
+ sandboxInjectedGlobals: ['Math']

timers

L'option timers a été renommée en fakeTimers. Consultez la section Faux temporisateurs pour plus de détails.

testURL

L'option testURL est supprimée. Maintenant vous devez utiliser testEnvironmentOptions pour passer l'option url à l'environnement JSDOM :

- testURL: 'https://jestjs.io'
+ testEnvironmentOptions: {
+ url: 'https://jestjs.io'
+ }

Configuration de Babel

babel-jest passe maintenant root: config.rootDir à Babel lors de la résolution de la configuration. Cela améliore la compatibilité lors de l'utilisation de projects avec une configuration différente, mais cela peut signifier que votre configuration babel n'est plus récupérée de la même manière. Vous pouvez remplacer cette option en passant des options à babel-jest dans votre configuration.

expect

Dans les versions antérieures à Jest 28, toHaveProperty vérifiait l'égalité au lieu de l'existence, ce qui signifie que, par exemple, expect({}).toHaveProperty('a', undefined) est un test concluant. Cela a été changé dans Jest 28 pour échouer.

En outre, si vous importez expect directement, il a été changé d'export par défaut en une exportation nommée.

- import expect from 'expect';
+ import {expect} from 'expect';
- const expect = require('expect');
+ const {expect} = require('expect');

Faux temporisateurs

Les faux temporisateurs ont été refactorisés pour permettre de passer des options à @sinonjs/fake-timers.

fakeTimers

L'option de configuration timers a été renommée en fakeTimers et prend maintenant un objet avec des options :

- timers: 'real'
+ fakeTimers: {
+ enableGlobally: false
+ }
- timers: 'fake'
+ fakeTimers: {
+ enableGlobally: true
+ }
- timers: 'modern'
+ fakeTimers: {
+ enableGlobally: true
+ }
- timers: 'legacy'
+ fakeTimers: {
+ enableGlobally: true,
+ legacyFakeTimers: true
+ }

jest.useFakeTimers()

Un objet avec des options doit maintenant être passé à jest.useFakeTimers() ainsi :

- jest.useFakeTimers('modern')
+ jest.useFakeTimers()
- jest.useFakeTimers('legacy')
+ jest.useFakeTimers({
+ legacyFakeTimers: true
+ })

Si les anciens faux temporisateurs sont activés dans le fichier de configuration de Jest, mais que vous souhaitez les désactiver dans un fichier de test particulier :

- jest.useFakeTimers('modern')
+ jest.useFakeTimers({
+ legacyFakeTimers: false
+ })

Environnement de test

Environnement personnalisé

Le constructeur de la classe de l'environnement de test reçoit maintenant un objet avec la classe globalConfig de Jest et projectConfig comme premier argument. Le deuxième argument est désormais obligatoire.

  class CustomEnvironment extends NodeEnvironment {
- constructor(config) {
- super(config);
+ constructor({globalConfig, projectConfig}, context) {
+ super({globalConfig, projectConfig}, context);
+ const config = projectConfig;

De plus, les environnements de test sont maintenant exportés avec le nom TestEnvironment, au lieu d'exporter simplement la classe directement :

- const TestEnvironment = require('jest-environment-node');
+ const {TestEnvironment} = require('jest-environment-node');

- const TestEnvironment = require('jest-environment-jsdom');
+ const {TestEnvironment} = require('jest-environment-jsdom');

jsdom

Si vous utilisez l'>environnement de test de JSDOM, le paquet jest-environment-jsdom doit maintenant être installé séparément :

npm install --save-dev jest-environment-jsdom

Exécuteur de test

Si vous utilisez l'exécuteur de test de Jasmine , le paquet jest-jasmine2 doit maintenant être installé séparément :

npm install --save-dev jest-jasmine2

Transformateur

Les méthodes process() et processAsync() d'un module de transformateur personnalisé ne peuvent plus retourner une chaîne de caractères. Ils doivent toujours renvoyer un objet :

  process(sourceText, sourcePath, options) {
- return `module.exports = ${JSON.stringify(path.basename(sourcePath))};`;
+ return {
+ code: `module.exports = ${JSON.stringify(path.basename(sourcePath))};`,
+ };
}

package.json exports

Jest inclut maintenant une prise en charge complète du paquet exports, ce qui peut avoir pour conséquence que les fichiers que vous importez ne sont pas résolus correctement.

De plus, Jest fournit désormais davantage de conditions. jest-environment-node a node et node-addons, tandis que jest-environment-jsdom a browser. En conséquence, vous pourriez par exemple obtenir un code de navigateur qui suppose l'ESM, alors que Jest fournit ['require', 'browser']. Vous pouvez soit signaler un bug à la bibliothèque (ou à Jest, l'implémentation est nouvelle et peut avoir des bugs !), surcharger les conditions que Jest passe (via un environnement de test personnalisé et en surchargeant exportConditions()), en utilisant un résolveur personnalisé ou moduleMapper. Il existe de nombreuses options, et vous devrez choisir celle qui convient à votre projet.

Les exemples connus de paquets qui échouent dans Jest 28 sont uuid et nanoid lors de l'utilisation de l'environnement jest-environment-jsdom. Pour une analyse et une solution potentielle, voir ce commentaire.

TypeScript

info

Les exemples TypeScript de cette page ne fonctionneront comme documentés que si vous importez jest de '@jest/globals' :

import {jest} from '@jest/globals';

jest.fn()

jest.fn() ne prend maintenant qu'un seul argument de type générique. Consultez la page de l'API des fonctions simulées pour plus d'exemples d'utilisation.

  import add from './add';
- const mockAdd = jest.fn<ReturnType<typeof add>, Parameters<typeof add>>();
+ const mockAdd = jest.fn<typeof add>();
- const mock = jest.fn<number, []>()
+ const mock = jest.fn<() => number>()
.mockReturnValue(42)
.mockReturnValueOnce(12);

- const asyncMock = jest.fn<Promise<string>, []>()
+ const asyncMock = jest.fn<() => Promise<string>>()
.mockResolvedValue('default')
.mockResolvedValueOnce('first call');