Contactez-nous

Requêtes de sélection (Queries : getBy, findBy, queryBy...)

Apprenez à utiliser efficacement les différentes requêtes (getBy, queryBy, findBy...) de React Testing Library pour sélectionner des éléments DOM dans vos tests React.

Le coeur de l'interaction : Trouver les éléments

Une fois votre composant rendu avec la fonction `render`, l'étape suivante consiste presque toujours à trouver des éléments spécifiques dans le DOM résultant. Vous en avez besoin soit pour simuler des interactions utilisateur (comme cliquer sur un bouton trouvé), soit pour faire des assertions sur leur état ou leur présence (comme vérifier qu'un message d'erreur s'affiche). React Testing Library (RTL) fournit un ensemble puissant et sémantique de fonctions pour accomplir cette tâche : les Requêtes (Queries).

Conformément à la philosophie de RTL, ces requêtes sont conçues pour vous aider à trouver des éléments de la manière dont un utilisateur le ferait, en privilégiant les attributs d'accessibilité et le contenu visible plutôt que les détails de l'implémentation (comme les noms de classes CSS ou la structure interne du DOM). Maîtriser ces requêtes est essentiel pour écrire des tests efficaces et robustes.

Les trois familles de requêtes : getBy, queryBy, findBy

Les requêtes de RTL se déclinent en trois variantes principales, différenciées par leur préfixe, qui déterminent leur comportement lorsqu'un ou plusieurs éléments sont trouvés ou non :

  • getBy* : Cette famille de requêtes est utilisée lorsque vous vous attendez absolument à ce que l'élément soit présent dans le DOM au moment de l'appel.
    • Si aucun élément correspondant n'est trouvé, `getBy*` lève une erreur immédiate, faisant échouer le test.
    • Si plus d'un élément correspondant est trouvé, `getBy*` lève également une erreur immédiate.
    • Si exactement un élément est trouvé, il le retourne.
    • Cas d'usage typique : Vérifier la présence initiale d'un élément qui doit exister (un titre, un bouton principal).
  • queryBy* : Cette famille est utilisée pour rechercher un élément qui pourrait ne pas être présent, et dont l'absence n'est pas une erreur en soi.
    • Si aucun élément correspondant n'est trouvé, `queryBy*` retourne `null` (et ne lève pas d'erreur).
    • Si plus d'un élément correspondant est trouvé, `queryBy*` lève une erreur immédiate (comme `getBy*`).
    • Si exactement un élément est trouvé, il le retourne.
    • Cas d'usage typique : Vérifier qu'un élément n'est pas présent à l'écran (ex: `expect(screen.queryByText('Erreur')).toBeNull();`).
  • findBy* : Cette famille est utilisée pour rechercher des éléments qui apparaissent de manière asynchrone (après un chargement de données, une minuterie, une animation, etc.).
    • `findBy*` retourne une Promesse.
    • La promesse se résout lorsqu'un élément correspondant est trouvé. Elle réessaie de trouver l'élément à intervalles réguliers pendant un temps défini (par défaut 1000ms).
    • La promesse est rejetée si aucun élément n'est trouvé après le délai d'attente, ou si plus d'un élément est trouvé.
    • Cas d'usage typique : Attendre qu'un élément apparaisse après un appel API (ex: `const articleTitle = await screen.findByText('Titre chargé');`).

Ces trois préfixes (`get`, `query`, `find`) se combinent ensuite avec différents suffixes qui spécifient comment rechercher l'élément (par rôle, par texte, etc.).

Les sélecteurs (Suffixes) : Comment chercher ?

RTL propose plusieurs types de sélecteurs (suffixes des requêtes), avec un ordre de priorité recommandé pour favoriser l'accessibilité et la robustesse :

  1. ByRole : (Ex: `getByRole('button', { name: /submit/i })`) - Le plus recommandé. Trouve les éléments par leur rôle ARIA implicite (pour les éléments HTML sémantiques comme `
  2. ByLabelText : (Ex: `getByLabelText('Username')`) - Très utile pour les éléments de formulaire (``, `