Un locator est un contrat, pas une coordonnée

page.locator('.panel > div:nth-child(3) > button.primary') fonctionne aujourd'hui. Ça marche demain. Il continue de fonctionner jusqu'à ce qu'un concepteur déplace le bouton d'un emplacement vers la gauche, puis votre suite échoue sur une fonctionnalité que personne n'a cassée. Vous n'avez pas passé de test. Vous avez écrit une photographie du DOM.

Ce que recommande réellement le dramaturge

La documentation de Playwright est inhabituellement directe à ce sujet. Son guide des locators recommande de donner la priorité aux attributs destinés aux utilisateurs et aux contrats explicites : getByRole, getByLabel, getByText, getByPlaceholder, getByTestId. Les locators de rôles reflètent la façon dont les utilisateurs et les technologies d'assistance perçoivent la page. Les identifiants de test créent un contrat explicite distinct, au prix d'être invisibles pour les utilisateurs. Ils ne restent stables que si les développeurs préservent ce contrat. Les sélecteurs CSS et XPath sont documentés comme fragiles car ils sont liés à la structure DOM, et c'est la structure DOM qui change.

Deux propriétés du cadre récompensent la bonne habitude. Les locators sont re-résolus avant chaque action, donc un nouveau rendu entre deux étapes ne vous laisse pas avec un élément obsolète. Et les locators sont stricts : si votre sélecteur correspond à deux éléments, l'action se lance au lieu de cliquer silencieusement sur le premier. Un échec strict en CI est embêtant pour un après-midi. Un mauvais clic dans la mauvaise boîte de dialogue est un rapport de bug avec votre nom dessus.

Pourquoi les générateurs prennent d'abord la mauvaise habitude

Une suite générée peut accéder à un sélecteur qui se résout sur la page actuelle sans considérer ce qu'une refonte va changer. Il s'agit d'un risque d'examen, et non d'une preuve des données d'entraînement d'un modèle particulier. Les tests liés à la mise en page peuvent réussir dès le premier jour et échouer après un changement frontal pour des raisons sans rapport avec le comportement du produit.

L'échec coûte cher d'une manière spécifique : la suite crie au loup à chaque refonte, l'équipe apprend à ignorer les versions rouges et la seule véritable régression navigue à travers un mur de bruit familier.

Un audit de quinze minutes pour n'importe quelle suite

Grep vos tests pour page.locator avec des chaînes CSS ou XPath, et pour getByText utilisé sur des éléments interactifs. Pour chaque appel, posez une question : ce sélecteur indique-t-il ce qu'est l'élément ou où il se trouve ? Remplacez les coordonnées par des contrats :

• Boutons et liens : getByRole avec le nom accessible.
• Champs de formulaire : getByLabel ou getByPlaceholder en solution de secours.
• Contenu répété ou dynamique : un data-testid convenu avec les développeurs.
• getByText : utile pour le contenu texte ; préférez un rôle et un nom accessible lorsque vous cliquez sur un contrôle.

Vous vous retrouverez avec une poignée de contrôles véritablement ambigus. Ce n'est pas un problème de test. Il s'agit d'un problème d'accessibilité que les tests viennent de découvrir gratuitement.

Le piège de la rigueur, et quand first() est un aveu

Les locators de dramaturges sont stricts : une action sur un sélecteur qui correspond à deux éléments génère une violation au lieu de deviner. Traitez chaque erreur en mode strict comme une question de conception. Si vous avez besoin de .first() pour faire passer la suite, l'une des deux choses suivantes est vraie : la page affiche des contrôles en double qui devraient avoir des noms accessibles distincts, ou votre sélecteur est trop large. Ce sont deux découvertes et non des inconvénients. Le correctif consiste à affiner avec un contrat nommé, à filtrer par un parent stable ou à demander un identifiant de test. Atteindre .nth(1) parce que la deuxième correspondance s'avère être la bonne cette semaine est la façon dont les suites apprennent à cliquer sur la mauvaise boîte de dialogue après la prochaine version.

Il existe une issue de secours légitime. locator.or() existe pour les cas où la page affiche honnêtement l'un des deux états, comme un formulaire de connexion ou une bannière déjà connectée. Utilisez-le délibérément, avec les deux alternatives nommées, et il se lit comme une branche. Utilisez-le pour dissiper toute ambiguïté et cela se lit comme un haussement d'épaules.

La place des agents

Laissez l'agent explorer et rédiger ; les locators sont l'endroit où se trouve votre avis. Un test généré avec getByRole('button', { name: 'Save' }) vous indique ce qu'il pense que la page fait. Un test généré avec div:nth-child(3) ne vous dit rien sauf que le DOM ressemblait à ça autrefois. Gardez le premier type. Réécrivez la seconde avant qu'elle n'atteigne CI, car chaque locator fragile que vous acceptez est une future fausse alarme pour laquelle vous avez déjà payé.