Locators Playwright : getByRole plutôt que XPath

Un premier test Playwright qui casse après un simple changement de style vient presque toujours du sélecteur. Plutôt que de viser la structure de la page avec du CSS ou du XPath, Playwright recommande de viser ce que l'utilisateur voit : un rôle, un libellé, un texte. Voici pourquoi, les locators à connaître, et un test refactoré ligne par ligne. Les exemples ont été exécutés le 13 novembre 2026 avec Playwright 1.59.1 sur une page locale.

Pourquoi les sélecteurs CSS et XPath cassent

Un sélecteur comme div.form > div:nth-child(2) > input décrit où se trouve le champ dans le code de la page. Si un développeur ajoute un conteneur ou déplace le champ, le test échoue alors que le comportement visible n'a pas changé. Une classe de style comme btn-primary change au gré des refontes graphiques. Ces tests sont fragiles parce qu'ils dépendent de détails que l'utilisateur ne voit jamais.

Les locators recommandés par Playwright

getByRole, getByLabel, getByText, getByTestId

• getByRole cible un élément par son rôle accessible (button, link, heading, checkbox) et son nom : getByRole('button', { name: 'Créer mon compte' }).
• getByLabel cible un champ de formulaire par son libellé : getByLabel('E-mail').
• getByText cible un élément par le texte affiché, pratique pour un message ou un élément non interactif.
• getByTestId cible l'attribut data-testid que vous placez vous-même dans le code.

Locators stricts, chaînage et filtres

Un locator est strict : si getByRole('button', { name: 'Ajouter' }) trouve deux boutons, Playwright lève une erreur « strict mode violation » au lieu de cliquer sur l'un des deux. Cette erreur est utile, elle signale une ambiguïté. Pour la lever, restreignez la recherche en chaînant et en filtrant :

await page
  .getByRole('listitem')
  .filter({ hasText: 'Playwright' })
  .getByRole('button', { name: 'Ajouter' })
  .click();

Avant / après : refactorer un test fragile

Voici un même scénario écrit avec des sélecteurs de structure, puis avec des locators orientés utilisateur :

// Avant : dépend de la structure et des classes
await page.locator('div.form > div:nth-child(2) > input').fill('ada@example.com');
await page.locator('//button[contains(@class,"btn-primary")]').click();
await expect(page.locator('.toast > span')).toHaveText('Compte créé');

// Après : dépend de ce que l'utilisateur voit
await page.getByLabel('E-mail').fill('ada@example.com');
await page.getByRole('button', { name: 'Créer mon compte' }).click();
await expect(page.getByRole('status')).toHaveText('Compte créé');

Quand garder un data-testid

Certains éléments n'ont ni rôle clair ni texte stable : un total affiché dans un tableau de bord, une zone générée dynamiquement, un texte traduit dans plusieurs langues. Dans ce cas, un data-testid posé par l'équipe est préférable à un sélecteur de structure : getByTestId('total'). Convenez-en avec les développeurs, et gardez ces identifiants stables.

Vérifier un locator avec Codegen et l'inspecteur

La commande npx playwright codegen ouvre un navigateur, enregistre vos actions et propose des locators. L'outil de sélection d'élément permet de survoler la page et de lire le locator suggéré. Relisez toujours le code généré : vérifiez qu'il vise un rôle ou un libellé, pas une position. Notre guide Playwright en français, notre guide sur Playwright et l'IA (MCP) et le cours Playwright gratuit détaillent ces outils, et le tutoriel Playwright Python montre les mêmes locators en Python.