Your React Native test suite is green, yet a user still reports that tapping “Continue” does nothing on a real device. The component test found the button, called its handler, and saw the expected screen in a mocked JavaScript environment. It never verified the native permission prompt, keyboard behavior, animation, platform API, or the actual navigation stack.
C'est là où les équipes se font une fausse confiance. Bibliothèque de test React Native is excellent for testing what a component renders and how it responds to user interaction, but it isn’t a substitute for device testing or performance measurement. The reliable strategy is to use each layer for the failures it can expose.
La bibliothèque de test React Native
- Pourquoi le Testage centré sur l'utilisateur change tout
- Installation et Configuration Qui Fonctionnent Vraiment
- APIs de base, requêtes et assertions Expliquées
- Modèles Pratiques pour les composants, les hooks et la navigation
- Débogage des Tests Fragiles CI et Contrôles de Performance
- Mettre tout en place et avancer
Pourquoi le test utilisateur centré change tout
Une erreur de test courante commence avant même que le test ne soit écrit. Un développeur inspecte les propriétés d'un composant, y accède à son état ou compare un grand snapshot car ces détails sont faciles à affirmer. Le test passe, puis une refacteur change la structure du composant sans modifier l'expérience, et le lot se brise. De plus, le test peut continuer à passer alors que le comportement visible pour l'utilisateur est incorrect car l'affirmation n'a jamais décrit ce dont l'utilisateur a besoin de voir.
La bibliothèque de test React Native prend l'approche inverse. Vous affichez le composant, interagissez avec lui à l'aide d'un contrôle visible, puis affirmez le résultat que l'utilisateur peut observer. Cette approche correspond Bibliothèque de test React Native centrée sur l'utilisateuret à la recommandation de test de React Native pour garder les tests courts, se concentrer sur une chose à la fois, séparer les préoccupations de vue des logiques métier et de l'état, et préférer les sorties visibles ou les aides d'accessibilité aux détails d'implémentation internes.
Test the behavior users depend on
Supposons qu'un formulaire de connexion désactive son bouton de soumission pendant qu'une requête s'exécute. Un test fragile pourrait inspecter disabled sur une instance spécifique d'un composant ou que la variable d'état a changé. Un test plus fort appuie sur le contrôle d'inscription accessible, attend l'indicateur de chargement et vérifie que le message d'erreur ou l'écran de destination apparaît.
Le deuxième test n'a pas d'importance sur le fait que le formulaire utilise un état local, un réducteur, un hook personnalisé ou une mise en œuvre de bouton différent. Il s'assure que l'application transmet le résultat correct.
Règle pratique : Si un utilisateur ne peut pas le voir, il faut se demander s'il s'agit d'un comportement à tester dans une composante.
Les requêtes basées sur les étiquettes d'accèsibilité et les rôles forcent également un produit code à être plus significatif. Une écran qui expose des étiquettes significatives est plus facile à utiliser avec des technologies d'assistance et plus facile à exercer en tests. Cette connexion compte lorsqu'on évalue l'expérience utilisateur plus large. l'expérience utilisateur de l'application, car la testabilité et l'utilisabilité s'améliorent souvent ensemble.
Connaître ce que les tests réussis ne prouvent pas
Un test de composant centré sur l'utilisateur peut prouver que JavaScript rend la brancher attendue et répond à un press simulé. Il ne peut pas prouver que le prompt biométrique s'ouvre correctement, que la caméra native retourne un résultat utilisable ou que le flux de paiement résiste au comportement de cycle de vie spécifique à la plateforme.
Cette limite n'est pas une faiblesse de la bibliothèque. C'est une raison de garder les couches de test honnêtes. Utilisez RNTL pour le comportement des composants, puis réservez les tests basés sur les appareils pour les flux où l'intégration native, la navigation réelle, les permissions, l'authentification, les paiements ou la fonctionnalité de l'application peuvent changer le résultat.
Installation et Configuration Qui Fonctionnent Réellement
La mise en place moderne commence par le package scoping :
@testing-library/react-nativeLe plus ancien react-native-testing-library Le nom de package npm existe encore comme artefact historique, mais les projets actuels doivent utiliser le package scoping maintenu au sein de la famille de Testing Library. Le dépôt du projet npm répertoire GitHub Installez la bibliothèque avec votre environnement Jest existant. Les projets Expo utilisent couramment le preset Jest d'Expo, tandis que les projets React Native sans enveloppe utilisent le preset React Native :
Install the library with your existing Jest environment. Expo projects commonly use the Expo Jest preset, while bare React Native projects may use the React Native preset:
npm install --save-dev @testing-library/react-native jestAjoutez le preset que votre projet utilise déjà pour Expo :
{
"scripts": {
"test": "jest"
},
"jest": {
"preset": "jest-expo"
}
}For a bare React Native application, use the corresponding React Native Jest configuration instead. Keep the preset aligned with the framework version. Many failures that look like RNTL problems come from a mismatched React renderer, Babel transform, or Jest preset.
Gardez les fichiers de configuration explicites
Placez la configuration de l'environnement partagé dans un fichier de configuration plutôt que de répéter les mocks dans chaque test.
// jest.setup.js
import '@testing-library/react-native/extend-expect';Ensuite, référez-vous à Jest :
{
"jest": {
"preset": "jest-expo",
"setupFilesAfterEnv": ["<rootDir>/jest.setup.js"]
}
}If votre application utilise React Navigation, Reanimated, la gestion de gestes, le contexte de zone de sécurité ou les modules de stockage, configurez uniquement les mocks dont votre environnement de test a besoin. Un mock global qui modifie le comportement de l'application peut rendre chaque test plus facile à passer, mais rend la suite moins fiable.
TypeScript nécessite la même attention. Assurez-vous que Jest transforme .ts et .tsx les fichiers à travers le preset ou votre configuration Babel, et maintenez les types de test disponibles au compilateur. Un test qui s'exécute localement mais n'est pas vérifié par type peut cacher des noms de requêtes incorrects, des paramètres de navigation invalides ou des formes de mock non sûres.
La chronologie des versions est utile pour diagnostiquer des conseils de mise en place plus anciens. Le projet liste 127 versions, avec v14.0.1 étiqueté le 23 juin 2026, tandis que v12.9.0, publié le 27 novembre 2024, ajoute le support officiel pour React Native 0.77 et Expo 52.. La ligne alpha v14 en mars 2025 a migré vers le Test Renderer Universel à partir du Test Renderer React obsolète et s'est préparé pour un support React 19 uniquement. Ces détails apparaissent dans l' historique des versions RNTLn'importez pas un dépendance de rendu d'un tutoriel obsolète sans vérifier les versions de votre application.
Pour une fondation Jest pratique, comparez votre configuration à celle de ce guide de test unitaire de Jestexécutez ensuite un test de composant mineur avant d'ajouter la navigation et les mocks natifs.
APIs, requêtes et affirmations de base expliquées
Les tests RNTL deviennent fiables lorsque leurs requêtes correspondent à ce que les utilisateurs peuvent voir, trouver et utiliser. L’API est petit, mais choisir un sélecteur qui expose des détails d'implémentation peut rendre un test réussi trompeur.
Démarrez par render:
const screen = render(<LoginForm />);Préférez les requêtes orientées accessibilité lorsque le composant les expose, utilisez le texte visible lorsque le texte est le comportement, et réservez testID pour les cas sans sélecteur pertinent pour l'utilisateur ou nécessitant une prise en charge d'intégration stable.
Pick the query by timing and intent
Chaque famille de requête a un but distinct :
- Présence synchronique : Utilisez
getByRole,getByText, ou une autregetByrequête lorsque l'élément doit déjà exister. Le test échoue immédiatement si ce n'est pas le cas. - Apparition asynchrone : Utilisez
findByRoleoufindByTextwhen rendering or interaction causes an async update. - Contrôles d'absence : Utilisez
queryByTextouqueryByTestIdlorsqu'un élément peut manquer et qu'un résultat null est attendu au lieu d'une exception. - Les sélecteurs de fallback : Utilisez
getByTestIdintentionnellement. Il donne des contrôles complexes un crochet durable, mais ne doit pas remplacer les étiquettes accessibles à travers l'application.
Pour les tests d'événements ciblés fireEvent.press est direct :
fireEvent.press(screen.getByRole('button', { name: 'Save' }));Utilisez userEvent Lorsque la version installée prend en charge la séquence d'interaction plus réaliste. Dans les deux cas, assurez-vous que l'interface utilisateur résultante :
expect(await screen.findByText('Saved')).toBeTruthy();Une assertion de gestionnaire convient à un composant dont le contrat public est un appel de callback d'événement. C'est faible car c'est la seule preuve que le parcours utilisateur fonctionne.
Préférez les assertions spécifiques aux captures d'écran
Les bonnes assertions décrivent l'écran :
expect(screen.getByText('Account created')).toBeTruthy();
expect(screen.getByRole('button', { name: 'Continue' })).toBeEnabled();Ils peuvent également vérifier l'état d'accès, la sélection et les retours d'informations de validation visibles. Évitez de vérifier les connexions internes.
expect(screen.getByTestId('submit-button').props.onPress).toBeDefined();Ce faisant prouve l'existence d'une propriété, pas que la fonctionnalité fonctionne. Les captures d'écran intentionnelles et petites peuvent détecter les changements structurels, tandis que les captures d'écran de navigation ou d'écran plus grandes créent souvent des commentaires bruyants et rendent les mises à jour non expliquées faciles à approuver.
Le package Testing Library appartient à la plus large testing-library L'organisation npm gère plusieurs packages actifs. @testing-library/react-nativeorganisation. Ses packages actifs incluent , avec la version13.3.3 publiée en 2026 , selon les informations du dépôtConventions de requêtes partagées sont utiles sur plusieurs plateformes, mais elles ne déterminent pas quelle assertion représente votre comportement produit.
Pour une comparaison plus large des pratiques de test de composants Jest, consultez ce guide sur le test unitaire de React. RNTL s'arrête toujours à la limite du composant JavaScript rendu. Les permissions natives, les piles de navigation réelles, les claviers de dispositif, les temps de cadence et le comportement de la mémoire nécessitent des outils E2E ou de performance plutôt que plus de mocks de composants.
Le vidéo ci-dessous démontre le flux de requête et d'assertion dans le contexte.
Modèles pratiques pour les composants, les hooks et la navigation
Un ensemble de tests utiles suit la forme de l'application. Les composants présentatifs nécessitent des tests de comportement directs, les hooks nécessitent des entrées et des sorties contrôlées, la navigation nécessite un fournisseur réaliste suffisamment réaliste et les modules natifs nécessitent des mocks qui restent visiblement différents de la vérification de la réalité du dispositif.
Composants présentatifs
Conservez un test de composant proche de son contrat public :
const onSelect = jest.fn();
render(
<PlanCard
title="Team"
description="Shared workspace"
onSelect={onSelect}
/>
);
fireEvent.press(screen.getByRole('button', { name: 'Choose Team' }));
expect(onSelect).toHaveBeenCalled();Le label exact doit correspondre à votre interface. L'important est que le test trouve le contrôle de la même manière qu'un utilisateur ou un service d'accessibilité et confirme le résultat visible ou de rappel qui compte. N'implémentez pas par défaut tous les composants enfants. Mettez en cache les limites coûteuses ou non liées uniquement lorsque celles-ci obscurcissent le comportement à tester.
Pour un hook personnalisé, utilisez renderHook Lorsque la version RNTL installée le fournit :
const { result } = renderHook(() => useSearch());
await act(async () => {
await result.current.submit('query');
});
expect(result.current.status).toBe('success');Le test du hook doit contrôler la limite de réseau ou de répertoire, et non reproduire l'ensemble de l'application. Testez l'écran séparément afin de savoir si l'état du hook devient utile pour l'interface.
Navigation et données asynchrones
Pour le comportement de navigation, afficher une écran à l'intérieur d'un vrai NavigationContainer et d'un petit navigateur de test est souvent plus précieux que de mocker tous les méthodes de navigation. Appuyez sur un contrôle visible, attendez le contenu de destination et affirmez le nouveau contenu de l'écran. Un test direct useNavigation Le mock est encore approprié pour un petit bouton dont la seule responsabilité est de dispatcher une route typée, mais il ne validera pas l'enregistrement de la route, les paramètres ou le comportement du navigateur imbriqué.
Les données asynchrones méritent la même discipline. Mockez l’API ou la réponse du repository, affichez l'écran, affirmez l'état de chargement, résolvez la demande, puis affirmez le succès ou l'erreur de sortie. findBy Les requêtes pour les éléments attendus à terme sont explicitement refusées, sinon une test peut passer car le composant n'a jamais atteint la branchée ciblée.
Mocks de modules natifs
Les mocks pour AsyncStorage, les permissions, les appareils photo, les biométriques et les API de plateforme sont utiles pour les tests JavaScript déterministes. Ils ne sont pas la preuve que la fonctionnalité native fonctionne. Gardez le comportement du mock proche du contrat du module, réinitialisez les appels entre les tests et incluez les réponses de failure au lieu de modéliser uniquement la voie heureuse.
| Scénario | Meilleur avec RNTL | Besoin de validation E2E |
|---|---|---|
| Validation de formulaire et erreurs visibles | Oui | Non généralement |
| UI de chargement, de succès et d'erreur à partir d'un repository mocké | Oui | Pour les flux de production critiques |
| Navigation entre les écrans enregistrés | Oui, avec un navigateur de test | Yes when gestures, deep links, or platform behavior matter |
| Décisions sur l'état de l'AsyncStorage | Oui, avec un mock contrôlé | Oui lorsque le lancement et la persistance interagissent avec le cycle de vie natif |
| Caméra, biométrie, autorisations ou API du système d'exploitation | Logique de fallback et de branchement en JS | Oui, sur des appareils réels ou représentatifs |
| Disposition, performance de rendu et native code | No | Oui, avec un appareil ou un outil spécialisé |
La limite est pratique : simulez la dépendance pour tester vos décisions JavaScript, puis exécutez un test d'appareil pour confirmer le comportement réel de la dépendance.
Diagnostic des Tests Fragiles Vérifications de Performance CI
Un test fragile indique souvent un temps non contrôlé, un état partagé ou une assertion qui court sur l'interface utilisateur. Identifiez la condition présente avant d'augmenter les temps d'attente. Un temps d'attente plus long peut cacher le problème de planification et ralentir l'ensemble des tests.
Utilisez findBy pour les éléments attendus après une mise à jour. Utilisez waitFor pour les conditions d'état ou les appels de mock. Si les faux horloges sont activés, avancez-les au point où l'interaction nécessite et rétablissez les horloges réelles par la suite. Un act Avertissement signifie que React a observé une mise à jour en dehors de sa limite d'interaction attendue. Corrigez le manque. await, interaction utilisateur, ou purge du timer au lieu d'ignorer l'avertissement.
Rendre les échecs de CI répudiables
A dependable CI job installs from the lockfile, runs the same Jest command used locally, and isolates mock state. Clear mock calls between tests, reset modules when module-level state affects behavior, and remove dependencies on execution order. Jest caching speeds feedback, but dependency or configuration changes require appropriate cache invalidation.
Les échecs CI nécessitent une comparaison de l'environnement avant une reécriture du composant. Vérifiez Node, le gestionnaire de packages, les paramètres de travail de Jest, la configuration du chronomètre et les variables d'environnement. Reproduisez la même commande localement où possible, puis réduisez le test en échec à l'interaction la plus petite qui expose la différence.
La visibilité couvre un autre fossé. Surveillance de l'état d'application fournit le contexte d'erreur de production qui ne peut être reproduit par les tests de composants mockés, notamment les échecs liés à des appareils réels et aux intégrations natives.
Les parcours sensibles à la sécurité nécessitent une deuxième limite. Utilisez les tests de composants pour la validation et les transitions d'état, puis ajoutez une couverture au niveau de l'appareil pour le transfert et le comportement natif. Pour les flux code uniques, consultez les conseils sur la façon de tester les flux de vérification SMS lorsque cette intégration fait partie du parcours.
Traitez la performance comme une mesure, pas une affirmation.
Un test fonctionnel peut confirmer que la liste s'affiche. Il ne peut pas déterminer de manière fiable si une refacteur a changé la durée de rendu ou le nombre de rendus, car le temps de test ajoute du bruit. Rassurez les mesures de ces valeurs pour un scénario, répétez le scénario pour réduire la variance et appliquez une analyse statistique avant de signaler une modification significative. Ses documentation de test de performance couvre également la présentation adaptée aux CI et aux examens de demande de tirage.
Évitez les assertions fixes telles que « ce rendu doit se terminer en dessous d'un seuil choisi. » Un travailleur CI occupé peut déclencher une fausse erreur, tandis qu'un seuil lâche peut manquer une régression réelle. Utilisez des mesures répétées pour les signaux de régression, puis inspectez le composant et le profil de l'appareil lorsque la comparaison montre une différence significative.
Règle de mesure : Les tests fonctionnels répondent à la question de savoir si le comportement est correct. Les outils de performance répondent à la question de savoir si un scénario mesuré a changé. Gardez ces questions séparées.
Mettre tout en place et avancer
La bibliothèque de tests React Native appartient à la couche rapide et large de votre stratégie de test. Elle doit couvrir le comportement des composants, les changements d'état visibles, les résultats d'accèsibilité, la validation, les états de données mockés et l'intégration entre les composants JavaScript. Gardez ces tests focalisés sur ce que l'utilisateur peut observer, et faites en sorte que les erreurs pointent vers un comportement spécifique plutôt qu'à un grand arbre rendu.
La couche plus petite basée sur les appareils doit protéger les flux où les mocks peuvent se trouver. La Résumé des tests indique que RNTL ne fournit pas un runtime React Native complet et ne peut donc pas tester les fonctionnalités natives. La même recommandation suggère de pairer les tests de composants avec des outils E2E tels que Detox pour les flux critiques, notamment l'authentification, les paiements et la fonctionnalité de l'application principale.
Un chemin de migration pratique
Vous n'avez pas besoin de réécrire un ensemble existant en une seule passe.
- Conservez les tests commerciaux précieux. Déplacez l'état pur et la logique de domaine dans des tests unitaires ciblés qui fournissent un feedback clair.
- Remplacez les assertions d'implémentation en premier lieu. Convertissez les vérifications de propriété et d'état interne en sortie visible, en état d'accessibilité et en résultats d'interaction.
- Réduisez les captures d'écran. Conservez uniquement les captures d'écran que les réviseurs peuvent comprendre et maintenir.
- Ajoutez une couverture des limites natives. Pour chaque module mocké important, identifiez le comportement du périphérique qui nécessite encore une validation.
- Protégez les parcours critiques. Ajoutez une couverture E2E pour l'authentification, les paiements, la navigation de base, les permissions et d'autres flux où le comportement natif peut modifier le résultat.
- Mesurez les écrans sensibles séparément. Utilisez des comparaisons de performances répétées pour les listes, les flux et les chemins de rendu coûteux au lieu de deviner en fonction de la durée de Jest.
Pour une confiance de version, connectez le suite à l'intégration de CI/CD et nécessite la couche de test appropriée avant la livraison. Si une correction JavaScript ou d'actif doit atteindre les utilisateurs après la validation, Capgo peut livrer des bundles web signés vers les canaux ciblés pour les applications CapacitorJS et Electron, avec des contrôles de lancement et une protection de rollback. Ce flux de livraison ne remplace pas les tests de dispositifs React Native, mais il illustre le même principe : valider le comportement à la couche où il s'exécute.
La bonne question n'est pas de savoir si la bibliothèque de test React Native peut tester votre application entière. Elle ne le peut pas, et la frontière officielle est utile. La bonne question est de savoir si chaque risque important a un test exécuté dans l'environnement capable de l'exposer.
Capgo relie les modifications JavaScript et d'actifs validées à une livraison contrôlée pour les équipes CapacitorJS et Electron, avec des canaux ciblés, une visibilité sur le lancement et une protection de rollback. Visitez Capgo pour voir comment il peut s'adapter à votre composant, E2E, et CI testing workflow.
