Comment migrer vos tests d'Enzyme vers React Testing Library

Dec 1, 2025 · 4 min read

Comment migrer vos tests d'Enzyme vers React Testing Library

Si votre suite de tests React dépend encore d’Enzyme, vous maintenez du code basé sur une bibliothèque qui n’a pas reçu de mises à jour officielles depuis des années. Enzyme ne dispose d’aucun adaptateur pour React 18 ou 19, et les solutions de contournement non officielles ne sont pas fiables. La voie à suivre est claire : migrer vers React Testing Library (RTL).

Cet article couvre les changements conceptuels nécessaires pour réussir une migration d’Enzyme vers React Testing Library, les modèles de refactorisation courants, et des conseils pratiques pour les équipes qui entreprennent ce travail en 2025.

Points clés à retenir

Enzyme ne dispose pas d’adaptateurs officiels pour React 18 et 19, ce qui rend la migration vers React Testing Library essentielle pour les projets React modernes.
RTL se concentre sur le test du comportement visible par l’utilisateur plutôt que sur les détails d’implémentation, produisant des tests plus stables et plus significatifs.
Remplacez shallow() et mount() d’Enzyme par render() de RTL, et utilisez des requêtes accessibles comme getByRole() au lieu de find().
Migrez progressivement en exécutant les deux bibliothèques côte à côte et en convertissant les tests par lots, en commençant par les composants les plus simples.

Pourquoi Enzyme n’est plus viable

Enzyme a été l’outil de test React dominant pendant des années. Mais son couplage étroit avec les mécanismes internes de React est devenu un handicap. Lors de la sortie de React 17, des adaptateurs communautaires ont comblé le vide. React 18 a complètement rompu ce schéma — aucun adaptateur officiel n’existe, et aucun n’a été annoncé car le projet Enzyme n’est effectivement plus maintenu.

Au-delà de la compatibilité, Enzyme encourageait le test des détails d’implémentation : vérifier l’état interne, appeler des méthodes d’instance, et utiliser le rendu superficiel (shallow rendering) pour isoler les composants de leurs enfants. Ces pratiques produisent des tests fragiles qui se cassent lors de refactorisations même lorsque le comportement reste identique.

React Testing Library adopte l’approche opposée. Elle effectue un rendu complet des composants et interroge le DOM de la même manière que les utilisateurs interagissent avec lui — par rôle, label et contenu textuel. Cela s’aligne avec les meilleures pratiques modernes de test React et produit des tests qui restent stables malgré les changements d’implémentation.

Le changement de philosophie fondamental

Le plus grand défi de cette migration n’est pas syntaxique. C’est un changement de mentalité.

Les tests Enzyme ressemblent souvent à ceci :

Accéder à l’instance du composant via wrapper.instance()
Appeler setState() ou setProps() directement
Faire des assertions sur les valeurs d’état interne
Utiliser shallow() pour éviter le rendu des composants enfants

Aucun de ces éléments n’a d’équivalent direct dans RTL. RTL les omet intentionnellement car ils testent des choses que les utilisateurs ne voient jamais.

Au lieu de cela, les tests RTL se concentrent sur :

Ce qui est rendu dans le DOM
Comment les éléments répondent aux interactions utilisateur
Si les rôles et labels accessibles sont présents

Pour remplacer le rendu superficiel d’Enzyme, vous effectuez le rendu de l’arbre complet des composants et simulez les dépendances au niveau du module si nécessaire. Cela nécessite plus de configuration mais produit une couverture plus significative.

Modèles de refactorisation courants

Remplacer `shallow()` et `mount()` par `render()`

La fonction render() de RTL monte votre composant dans un environnement DOM. Il n’existe pas d’équivalent superficiel. Si les composants enfants posent problème, simulez-les avec Jest :

jest.mock('./ChildComponent', () => () => <div data-testid="child-mock" />);

Remplacer `wrapper.find()` par des requêtes accessibles

Le find('button') d’Enzyme devient screen.getByRole('button') dans RTL. Privilégiez les requêtes qui reflètent la façon dont les utilisateurs localisent les éléments :

getByRole() pour les éléments interactifs
getByLabelText() pour les champs de formulaire
getByText() pour le contenu visible

Supprimer les assertions `instance()` et `state()`

Si vous testez qu’un clic sur un bouton met à jour l’état interne, reformulez le test : que voit l’utilisateur après le clic ? Faites des assertions sur la sortie rendue à la place.

Gérer le comportement asynchrone avec `findBy` et `waitFor`

Enzyme nécessitait des appels manuels à wrapper.update(). RTL gère les mises à jour automatiquement. Utilisez findByRole() ou waitFor() pour les assertions asynchrones.

La migration en conditions réelles est réalisable

De grandes équipes ont réussi cette migration avec succès. L’équipe d’ingénierie de Slack a converti plus de 15 000 tests en utilisant une combinaison de codemods basés sur l’AST et de transformations assistées par LLM. L’équipe d’ingénierie du New York Times a décrit leur migration d’Enzyme comme la partie la plus importante de leur mise à niveau vers React 18.

L’approche commune : migrer progressivement. Exécutez les deux bibliothèques côte à côte. Convertissez les tests par lots, en commençant par les composants les plus simples. Utilisez l’automatisation lorsque les changements syntaxiques sont mécaniques, mais attendez-vous à un travail manuel pour les tests qui reposaient fortement sur les détails d’implémentation.

React 19 et l’avenir des tests de composants

React 19 déprécie react-test-renderer pour les tests de composants, consolidant davantage RTL comme standard. Si vous planifiez une mise à niveau de React, terminer votre migration d’Enzyme vers React Testing Library en premier élimine un obstacle majeur.

Les tests React modernes en 2025 signifient écrire des tests qui survivent aux refactorisations, valident l’accessibilité et reflètent le comportement réel des utilisateurs. RTL répond à ces trois objectifs.

Conclusion

Migrer depuis Enzyme nécessite plus qu’un simple rechercher-remplacer. Vous adoptez une philosophie de test différente — une philosophie qui privilégie le comportement visible par l’utilisateur plutôt que l’implémentation interne. L’effort est récompensé par des tests plus stables, plus significatifs et compatibles avec les versions actuelles et futures de React.

Commencez par un petit lot. Reformulez vos assertions autour de ce que les utilisateurs voient. Abandonnez le rendu superficiel. Votre suite de tests n’en sera que meilleure.

FAQ

Oui. Les deux bibliothèques peuvent coexister dans le même projet. Cela vous permet de migrer les tests progressivement sans perturber votre suite de tests existante. Installez RTL aux côtés d'Enzyme, convertissez les tests par lots, et supprimez Enzyme une fois la migration terminée.

RTL décourage le test direct de l'état interne. Au lieu de cela, testez le résultat observable. Si un clic sur un bouton modifie l'état, vérifiez ce que l'utilisateur voit après le clic — comme un texte mis à jour, un nouvel élément qui apparaît, ou un attribut modifié. Cette approche produit des tests plus résilients.

Simulez le composant enfant problématique au niveau du module en utilisant Jest. Cela isole votre test de l'implémentation de l'enfant tout en effectuant toujours le rendu complet du composant parent. Utilisez jest.mock pour remplacer l'enfant par un élément placeholder simple.

Oui. RTL reste la bibliothèque de test recommandée pour React 19. React 19 déprécie react-test-renderer pour les tests de composants, faisant de RTL le choix standard. Terminer votre migration avant de passer à React 19 élimine un obstacle de compatibilité significatif.

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.