data-testid : le guide complet pour des tests QA stables

Vous avez déjà vu un test casser parce qu'un développeur a renommé une classe CSS ? Ou parce qu'une traduction a fait passer "Login" à "Connexion" ? L'attribut data-testid est la réponse standard de l'industrie à ce problème. Voici tout ce qu'il faut savoir pour l'utiliser correctement.

1. Qu'est-ce qu'un data-testid ?

data-testid est un attribut HTML personnalisé que l'on ajoute à un élément pour permettre aux tests automatisés de le retrouver de manière fiable. Il ne sert ni au style, ni au comportement, ni à l'accessibilité : il existe exclusivement pour les tests.

<!-- Avant -->
<button class="btn btn-primary mt-4">Se connecter</button>

<!-- Après -->
<button class="btn btn-primary mt-4" data-testid="login-submit">Se connecter</button>

Le bouton continue à fonctionner exactement comme avant pour les utilisateurs. Mais côté tests, on peut maintenant l'identifier de façon stable, peu importe que la classe CSS change, que le texte soit traduit, ou que l'élément soit réordonné dans le DOM.

2. Les origines

La pratique remonte aux années 2017-2018, dans la communauté React. Avant cela, les tests utilisaient des sélecteurs CSS (.login-button, #email-input) ou des sélecteurs XPath alambiqués. Problème : ces sélecteurs cassaient dès qu'on touchait au styling.

C'est Kent C. Dodds, avec sa librairie React Testing Library (2018), qui a popularisé la philosophie : "Test what the user sees, not how the app is built". L'idée : privilégier les sélecteurs accessibles (rôle, label, texte visible) et n'utiliser data-testid qu'en dernier recours, quand aucun autre sélecteur stable n'est disponible.

L'adoption s'est ensuite généralisée :

• Cypress recommande data-cy ou data-testid dans sa doc officielle depuis 2018.
• Playwright a ajouté page.getByTestId() comme locator natif en 2022, avec data-testid comme attribut par défaut configurable.
• Vue Test Utils, Angular Testing Library et la majorité des frameworks de test E2E suivent la même convention.

Aujourd'hui, data-testid est devenu le standard de facto pour identifier des éléments dans les tests automatisés, tous frameworks confondus.

3. Pourquoi c'est crucial en QA

Chez Prod Watch, on observe les mêmes symptômes chez des dizaines de clients : des suites de tests qui cassent toutes les semaines, du temps perdu à "réparer" des tests qui n'ont pourtant rien testé de nouveau. Dans 80% des cas, le coupable est le sélecteur. Voici ce qu'apporte data-testid.

Stabilité face aux refactos

Un sélecteur CSS comme .btn.btn-primary:nth-child(3) est fragile : il casse dès qu'on réordonne les boutons, qu'on ajoute une classe, qu'on change le wrapper. Un data-testid="cart-checkout-btn" survit à tous ces changements puisqu'il porte une intention métier, pas une description visuelle.

Indépendance vis-à-vis de l'i18n

Tester via le texte (getByText("Se connecter")) marche - jusqu'au jour où vous lancez la version anglaise et que tout casse. Avec un testid, le sélecteur reste valide en français, anglais, espagnol, ou en mode A/B test.

Lisibilité du code de test

page.locator('.modal > div > form > button.primary').click()

page.getByTestId('signup-confirm').click()

Le second exemple lit comme du français. Un PM, un designer ou un nouveau développeur peut comprendre ce que fait le test sans connaître l'architecture DOM.

Découplage équipes UI / équipes QA

Quand les designers itèrent sur un composant (changement de classes Tailwind, refonte du layout, nouveaux variants), les tests ne tombent pas. C'est une condition indispensable pour que la QA passe à l'échelle dans une équipe produit qui bouge vite.

Réduction drastique des tests flaky

4. Comment les utiliser correctement

Convention de nommage

Adoptez une convention kebab-case, courte, scope-action :

• signup-email-input
• cart-checkout-btn
• nav-user-menu
• product-card-add

La structure contexte-objet-action (ou page-élément-rôle) facilite la recherche, l'autocomplétion et évite les collisions.

Où les placer ?

Sur l'élément interactif final (le <button>, le <input>, le <a>) - jamais sur les wrappers intermédiaires. Sinon, le clic peut atterrir sur un parent et échouer silencieusement.

Listes et éléments répétés

Pour des cards répétées (produits, lignes d'un tableau), combinez un testid générique et un identifiant unique :

<li data-testid="cart-item" data-item-id="sku-1042">
  <button data-testid="cart-item-remove">Retirer</button>
</li>

En Playwright, on peut alors faire : page.getByTestId('cart-item').filter({ has: page.locator('[data-item-id="sku-1042"]') }).

Côté frameworks

• React : passez data-testid en prop, il est transmis au DOM tel quel.
• Vue : utilisez :data-testid pour les valeurs dynamiques.
• Angular : binding direct [attr.data-testid]="'foo'".
• Web components : exposez les testids sur les éléments internes via ::part ou repropagez-les.

5. Anti-patterns à éviter

6. Faut-il retirer les data-testid en production ?

Question récurrente. La réponse courte : non, gardez-les.

Les arguments pour les retirer sont généralement :

• "Ça pollue le HTML" - le poids ajouté est négligeable (quelques octets par élément).
• "C'est mauvais pour le SEO" - faux, Google ignore les attributs data-*.
• "Ça expose la structure interne" - un attaquant peut déjà inspecter le DOM, vos testids n'apprennent rien de sensible.

Et les arguments pour les conserver sont solides :

• Les mêmes tests tournent en CI et en monitoring synthétique de production (c'est exactement ce que fait Prod Watch).
• Les outils de support client (replay de session, debug en live) peuvent s'en servir.
• Éviter une étape de build qui les supprime, c'est une catégorie de bugs en moins.

7. Exemples concrets : un formulaire de login

La version sans testid (à éviter)

<form>
  <input type="email" class="input input-lg" placeholder="Email" />
  <input type="password" class="input input-lg" placeholder="Mot de passe" />
  <button class="btn btn-primary">Connexion</button>
</form>

Le test Playwright correspondant :

await page.locator('input[type="email"]').fill('jane@example.com');
await page.locator('input[type="password"]').fill('****');
await page.locator('button.btn-primary').click();

Que se passe-t-il quand on ajoute un champ "Code entreprise" en haut du formulaire ? Le sélecteur input[type="email"] reste correct, mais si le projet utilise des libs de design system, on aura vite plusieurs button.btn-primary sur la page. Test cassé.

La version avec testid

<form data-testid="login-form">
  <input type="email" data-testid="login-email" class="input input-lg" />
  <input type="password" data-testid="login-password" class="input input-lg" />
  <button data-testid="login-submit" class="btn btn-primary">Connexion</button>
</form>

Le test devient :

await page.getByTestId('login-email').fill('jane@example.com');
await page.getByTestId('login-password').fill('****');
await page.getByTestId('login-submit').click();

Plus court, plus lisible, et incassable tant que les testids restent en place. C'est exactement le genre de tests que nos clients laissent tourner 24/7 sur Prod Watch sans avoir à y toucher pendant des mois.

8. Conclusion

data-testid est un petit attribut qui fait une énorme différence : il transforme une suite de tests fragile en infrastructure fiable, capable de tourner en continu pour détecter les régressions avant les utilisateurs.

Les principes à retenir :

1. Adopter une convention de nommage claire et la documenter dans le repo.
2. Les placer sur les éléments vraiment testés, pas partout.
3. Les garder en production pour faire tourner les mêmes tests en CI et en monitoring.
4. Les considérer comme un contrat entre l'équipe produit et l'équipe QA, au même titre qu'une API.

Si vous déployez ces pratiques et que vous voulez ensuite faire tourner vos tests Playwright en continu sur la prod, avec rapports, alertes et historique - c'est exactement le cœur de métier de Prod Watch.