Aller au contenu principal
Version : Suivant

De la v29 à la v30

Traduction Bêta Non Officielle

Cette page a été traduite par PageTurner AI (bêta). Non approuvée officiellement par le projet. Vous avez trouvé une erreur ? Signaler un problème →

Vous effectuez une mise à niveau de Jest de la v29 à la v30 ? Ce guide a pour but de vous aider à refactorer votre configuration et vos tests.

info

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

note

Vous effectuez une mise à niveau depuis une version antérieure ? Consultez le guide de mise à niveau de la v28 à la v29 ici.

Compatibilité​

  • Jest 30 abandonne la prise en charge de Node 14, 16, 19 et 21. Les versions minimales supportées de Node sont désormais 18.x. Vérifiez que votre environnement utilise une version compatible de Node avant la mise à niveau.

  • La version minimale de TypeScript est désormais 5.4. Mettez à jour TypeScript si vous utilisez les définitions de types de Jest (ou de l'un de ses paquets).

  • Le paquet jest-environment-jsdom utilise désormais JSDOM v26. Cette mise à jour peut introduire des changements de comportement dans l'environnement DOM. Si vous rencontrez des différences de comportement DOM ou de nouveaux avertissements, reportez-vous aux notes de version de JSDOM pour les v21–26.

Les assertions et matchers de Jest​

Suppression des alias des fonctions matchers​

Tous les noms d'alias des matchers ont été supprimés au profit de leurs noms principaux. Si vous utilisiez des noms de matchers anciens et dépréciés, vous devrez mettre à jour vos tests :

  • Alias supprimés et leurs remplacements :
    • expect(fn).toBeCalled() → expect(fn).toHaveBeenCalled()
    • expect(fn).toBeCalledTimes(n) → expect(fn).toHaveBeenCalledTimes(n)
    • expect(fn).toBeCalledWith(arg) → expect(fn).toHaveBeenCalledWith(arg)
    • expect(fn).lastCalledWith(arg) → expect(fn).toHaveBeenLastCalledWith(arg)
    • expect(fn).nthCalledWith(n, arg) → expect(fn).toHaveBeenNthCalledWith(n, arg)
    • expect(fn).toReturn() → expect(fn).toHaveReturned()
    • expect(fn).toReturnTimes(n) → expect(fn).toHaveReturnedTimes(n)
    • expect(fn).toReturnWith(val) → expect(fn).toHaveReturnedWith(val)
    • expect(fn).lastReturnedWith(val) → expect(fn).toHaveLastReturnedWith(val)
    • expect(fn).nthReturnedWith(n, val) → expect(fn).toHaveNthReturnedWith(n, val)
    • expect(func).toThrowError(message) → expect(func).toThrow(message)
info

Ces méthodes d'alias étaient dépréciées depuis Jest 26, et dans Jest 30 elles sont complètement supprimées. Effectuez une recherche-remplacement globale dans votre base de code pour passer aux noms canoniques des matchers. La fonctionnalité est identique - seuls les noms des méthodes ont changé. (Si vous utilisez ESLint avec eslint-plugin-jest, la règle no-alias-methods peut vous aider à automatiser ce remplacement.)

Propriétés non énumérables​

Les propriétés non énumérables des objets sont désormais exclues par défaut des matchers d'objets. Cela pourrait affecter expect.objectContaining ou les vérifications d'égalité.

Amélioration de l'inférence de type pour CalledWith​

Utilisateurs TypeScript : Les types pour la famille de matchers CalledWith (par exemple toHaveBeenCalledWith) ont été améliorés pour inférer les types des paramètres de fonction. Dans la plupart des cas, cela détectera les incompatibilités de types plus précisément. Il s'agit d'un changement rupture à la compilation.

Si vous effectuiez des assertions avec des arguments qui ne correspondent pas aux types de paramètres réels de la fonction, TypeScript pourrait désormais générer des erreurs sur ces tests. Par exemple, si une fonction est typée pour accepter un nombre et que vous écriviez expect(fn).toHaveBeenCalledWith("string"), les types de Jest 30 avec TypeScript 5+ signaleront cette erreur. Le comportement d'exécution du matcher reste inchangé.

Pour corriger les nouvelles erreurs TypeScript, assurez-vous que les arguments de vos tests correspondent aux types attendus par la fonction (ou utilisez des conversions de type si vous appelez intentionnellement avec des types différents).

Ce changement n'affecte pas l'exécution, mais il peut révéler de nouvelles erreurs de type dans vos tests qui étaient auparavant passées inaperçues, rendant vos tests plus sûrs au niveau des types.

Mises à jour de la configuration​

Prise en charge des extensions .mts et .cts​

Jest 30 étend la prise en charge des extensions de fichiers pour les modules ESM et TypeScript :

  • L'option moduleFileExtensions inclut désormais par défaut .mts et .cts (modules TypeScript ESM et CommonJS) en plus des extensions habituelles.

  • Les modèles par défaut de testMatch et testRegex ont été mis à jour pour reconnaître les fichiers .mjs, .cjs, .mts et .cts comme fichiers de test.

info

Si votre projet contient des fichiers avec ces extensions qui ne sont pas destinés à être traités comme des modules ou des tests, vous devrez peut-être ajuster votre configuration. Inversement, si vous avez des fichiers de test avec ces extensions, Jest les détectera désormais par défaut (vous pouvez supprimer la configuration personnalisée qui était auparavant nécessaire pour les inclure).

--testPathPattern a été renommé en --testPathPatterns​

Si vous filtrez les tests par chemin, notez que l'option CLI a changé : --testPathPattern est désormais --testPathPatterns. Vous pouvez passer plusieurs motifs en les séparant par des espaces ou en répétant l'option. Par exemple :

# Old (Jest 29)
jest --testPathPattern="unit/.*"

# New (Jest 30)
jest --testPathPatterns "unit/.*" "integration/.*"

En interne, Jest consolide ces motifs dans un objet TestPathPatterns. Si vous appeliez programmatiquement le mode watch de Jest avec un testPathPattern, vous devez désormais construire une instance TestPathPatterns.

Suppression de la commande --init​

La commande interactive d'initialisation de configuration jest --init a été supprimée. Cette commande obsolète servait à générer un fichier de configuration Jest. Pour créer une configuration, exécutez :

npm init jest@latest
# Or for Yarn
yarn create jest
# Or for pnpm
pnpm create jest

Autres changements CLI​

  • Jest valide désormais les options CLI nécessitant des arguments. Par exemple, avec --maxWorkers ou --selectProjects, vous devez inclure une valeur (p. ex. --maxWorkers=50%). Auparavant, Jest autorisait certaines options sans valeur (utilisant les valeurs par défaut) ; désormais, il génère une erreur si la valeur est manquante. Vérifiez que vos scripts ou commandes npm incluent les arguments nécessaires.

  • Pour l'option avancée --filter (filtrage de fichiers via une implémentation personnalisée), l'interface attendue a changé. La fonction de filtre doit désormais retourner un objet de forme {filtered: Array<string>}. Dans les versions antérieures, d'autres formats étaient acceptés (p. ex. un tableau direct). Mettez à jour vos fonctions de filtrage pour retourner un objet avec une propriété filtered.

Changements de comportement du moteur de test​

Rejets de promesses non gérés dans les tests​

Jest corrige désormais le traitement des promesses rejetées puis interceptées pour éviter des échecs de test erronés. Dans Jest 29, un rejet géré de manière asynchrone (après le tick du test) pouvait causer un échec incorrect. Jest 30 attend désormais un tour supplémentaire de la boucle d'événements pour confirmer qu'un rejet reste non géré avant d'échouer un test.

info

Vous devriez observer moins de faux positifs pour les rejets de promesses non gérés. Les tests échouant précédemment à cause de rejets interceptés de manière asynchrone devraient désormais réussir. Ce changement peut légèrement ralentir la fin des tests, notamment pour les tests rejetant intentionnellement des promesses. L'option waitForUnhandledRejections permet de restaurer l'ancien comportement si nécessaire. La plupart des utilisateurs peuvent conserver la valeur par défaut qui privilégie l'exactitude en évitant les échecs erronés.

Ordonnanceurs de test personnalisés​

Si vous utilisez un ordonnanceur de tests personnalisé (une classe héritant de TestSequencer de Jest), vous devrez le mettre à jour pour Jest 30. Jest transmet désormais un contexte supplémentaire à l'ordonnanceur de tests. Plus précisément, l'API TestSequencer a été étendue pour exposer globalConfig et contexts à votre ordonnanceur.

globalConfig requis dans Runtime​

Pour ceux qui utilisent les API programmatiques de Jest : la construction d'un Runtime nécessite désormais un paramètre globalConfig. Si vous utilisez jest.runCLI ou des assistants similaires, assurez-vous de passer toutes les options requises conformément à l'API mise à jour. (L'utilisation typique via la CLI jest ou npm test n'est pas affectée par ce changement.)

Snapshots et modifications de sortie​

Mise à jour des liens de documentation cassés​

L'URL raccourcie goo.gl est supprimée des tests snapshot. Ce changement met à jour les snapshots existants pour remplacer les liens goo.gl par des URL complètes non raccourcies.

Causes d'erreurs dans les snapshots​

La sérialisation des erreurs dans les snapshots a changé. Le sérialiseur de snapshots de Jest 30 inclura désormais la propriété cause d'une Error (si présente) lors de l'impression des erreurs.

Rendu des chaînes vides dans React​

Le sérialiseur spécifique à React ne rend plus les enfants de chaîne vide ("") dans la sortie. Dans Jest 29, un enfant de chaîne vide dans un élément React pouvait apparaître comme "" dans la sortie snapshot ; dans Jest 30 il sera omis (traité comme aucun contenu).

Amélioration de l'affichage des objets dans pretty-format​

ArrayBuffer et DataView sont désormais affichés de manière lisible par l'homme au lieu d'être représentés comme des objets avec des champs internes.

Modifications des API de mock de Jest​

jest.genMockFromModule supprimé​

L'ancienne fonction jest.genMockFromModule(moduleName) a été supprimée. Elle était précédemment dépréciée au profit de jest.createMockFromModule(moduleName). Si vous utilisez encore genMockFromModule, passez à createMockFromModule – le comportement est identique. Par exemple :

Ancien code (Jest 29) :

const mockFs = jest.genMockFromModule('fs');

Nouveau code (Jest 30) :

const mockFs = jest.createMockFromModule('fs');

Types de fonctions mock supprimés​

info

Les changements de types ne s'appliquent que si vous importez explicitement les API Jest :

import {expect, jest, test} from '@jest/globals';

Certains types TypeScript liés aux fonctions mock ont été supprimés de l'API publique.

  • MockFunctionMetadata

  • MockFunctionMetadataType

  • SpyInstance

Si vous utilisiez jest.SpyInstance (par exemple pour annoter le retour de jest.spyOn), vous devriez passer à jest.Spied.

jest.mock ne fonctionne qu'avec des chemins de modules sensibles à la casse​

jest.mock() ne fonctionnera désormais qu'avec des chemins de modules sensibles à la casse. Dans le meilleur des cas, il s'agit d'un cas marginal puisque la plupart des utilisateurs suivent le comportement des noms de fichiers du système d'exploitation. Nous recommandons d'utiliser des chemins de modules correctement nommés pour éviter de futures ruptures similaires.

Ancien code (Jest 29) :

jest.mock('./path/to/FILENAME.js'); // This works EVEN when you only have `filename.js`

Nouveau code (Jest 30) :

jest.mock('./path/to/filename.js'); // This strictly works when you ONLY have `filename.js`

Modifications des modules et du runtime​

Support ESM et restructuration interne​

Jest a introduit des changements significatifs dans la façon dont ses paquets sont empaquetés et exportés :

  • Tous les modules internes de Jest sont désormais regroupés en fichiers uniques pour un démarrage plus rapide. Cela signifie qu'à l'installation de Jest, le nombre de fichiers chargés est considérablement réduit (améliorant les performances). Cependant, un effet secondaire est que tout import profond non officiel dans les paquets de Jest risque de casser. Par exemple, si vous faisiez précédemment quelque chose comme require('jest-runner/build/testWorker') (qui n'est pas une API publique), ce chemin n'existera plus. Solution : Utilisez uniquement les API publiques ou les interfaces documentées de Jest. Si vous dépendez d'un module interne que vous pensez devoir faire partie de l'API publique, veuillez ouvrir une Pull Request pour l'exposer.

  • Les paquets Jest fournissent désormais des wrappers ESM. Cela fait partie du travail en cours pour permettre l'exécution de Jest dans un contexte ESM. Tous les paquets officiels Jest s'exportent correctement via le champ "exports" du package.json. Pour la plupart des utilisateurs, cela n'a pas d'impact direct – vous continuez à utiliser Jest de la même manière. Mais si vous maintenez un outil ou un plugin qui importe des modules Jest, assurez-vous d'utiliser les noms de paquets dans vos imports (qui seront résolus via la résolution de modules de Node).

Ces changements sont considérés comme cassants pour quiconque manipule les internals de Jest, mais pas pour une utilisation typique du CLI Jest et de sa configuration. Après la mise à jour, exécutez vos tests normalement – si vous rencontrez des erreurs de résolution de modules liées aux propres modules de Jest, cela vient probablement d'un import non supporté qu'il faut supprimer ou mettre à jour.

Changements dans la correspondance des motifs globaux​

La dépendance de Jest pour la correspondance de motifs de fichiers (glob) a été mise à jour vers la v10. Glob v10 peut présenter de légères différences dans la syntaxe et le comportement des motifs.

Un changement notable est que glob@10 traite les expansions d'accolades et les extglobs un peu différemment et est plus strict sur certains motifs. Si vous avez des configurations personnalisées testMatch, des motifs moduleNameMapper ou d'autres configurations basées sur glob, elles devraient continuer à fonctionner dans la plupart des cas. Sachez simplement que si un motif ne correspond plus aux fichiers comme avant, vous devrez peut-être l'ajuster pour le nouveau moteur glob.

Conclusion​

Pour mettre à jour vers Jest 30, assurez d'abord que votre environnement répond aux nouvelles exigences Node.js et TypeScript. Mettez à jour votre fichier de configuration Jest et l'utilisation du CLI pour les options renommées et supprimées (notamment testPathPatterns et la suppression de --init). Exécutez votre suite de tests et corrigez les échecs :

  • Corrigez les tests utilisant des alias de matchers supprimés en les remplaçant par les noms officiels.

  • Mettez à jour les snapshots qui échouent en raison des changements de formatage (causes d'erreurs, chaînes vides, etc.).

  • Portez attention aux erreurs du compilateur TypeScript – elles vous guideront pour mettre à jour l'utilisation d'API dépréciées (comme genMockFromModule ou les types supprimés) et ajuster les tests où les types sont désormais plus stricts.

Bonnes pratiques de test !