Retour au Centre de connaissances
Démarrage

Snapshot ARIA Playwright : examiner avant de modifier

Examinez un diff ARIA Playwright en distinguant noms capturés, modèles partiels et changements visuels avant de modifier la référence attendue.

BotBrowser Team

Documentation

Vous voulez la documentation structurée pour Démarrage ?

Cet article fait partie de la bibliothèque éditoriale. Pour les étapes de configuration, la référence et les mises à jour continues, passez directement à la section docs.

Un diff de snapshot ARIA Playwright peut révéler un changement du nom d'un bouton alors que sa capture d'écran semble identique. Vérifiez l'arbre réellement capturé, le modèle attendu et le contrat prévu de l'interface avant de modifier l'attente. BotBrowser peut fournir un exécutable Chromium et un profil de navigateur pilotés par Playwright ; il ne peut pas décider si un nouveau nom accessible est correct ni transformer un snapshot réussi en audit d'accessibilité.

TL;DR

  • locator.ariaSnapshot() capture une représentation accessible. toMatchAriaSnapshot() la vérifie selon un modèle dont les omissions comptent.
  • Un modèle contenant uniquement - button peut accepter différents noms de bouton. Sa réussite ne démontre pas qu'un changement de nom est sans conséquence.
  • Un modèle au nom exact détecte la différence de nom ; une modification CSS seule peut préserver cette correspondance tout en changeant l'image affichée.
  • Corrigez un nom involontaire dans l'application. Modifiez un nom voulu dans l'attente uniquement après vérification du besoin et du comportement associé.

Sommaire

Arbres capturés et modèles répondent à des questions différentes

Le mot snapshot désigne deux objets qui demandent un traitement distinct. Le premier est la chaîne YAML renvoyée par locator.ariaSnapshot() : une représentation capturée des rôles, noms, états et contenus accessibles dans le périmètre du localisateur. Le second est le modèle transmis à expect(locator).toMatchAriaSnapshot() : les conditions que l'assertion fera respecter. Un modèle plus court ne décrit pas nécessairement tout ce que contient la capture.

La documentation des snapshots ARIA Playwright énonce directement la distinction : un modèle est une contrainte, pas nécessairement une sérialisation complète de l'arbre d'accessibilité. Cela compte lorsqu'un test réussit après une modification de l'interface. Le navigateur peut exposer correctement le nouveau nom alors que le modèle attendu n'a jamais exigé l'ancien. Le comparateur n'a rien réparé silencieusement ; l'assertion posait une condition moins exigeante.

Pour un bouton, trois faits peuvent diverger : son texte visible, son nom accessible et sa présentation CSS. Les recommandations WAI-ARIA sur les noms décrivent aria-label comme un nom fourni par une chaîne qui n'est pas affichée visuellement. Modifier cet attribut peut changer le YAML capturé sans changer le libellé visible. À l'inverse, modifier un fond ou une bordure peut laisser le rôle et le nom intacts. Aucune représentation ne contient toutes les propriétés de l'autre.

Considérez un panneau de paramètres que vous contrôlez, avec une seule commande d'enregistrement. Si son nom accessible passe d'une action précise à un terme vague, la question est de savoir si ce nouveau nom communique toujours l'opération prévue. Compter les lignes YAML modifiées ne permet pas d'y répondre. Un changement de nom sur une ligne peut affecter l'identification de la commande, tandis que de nombreuses lignes modifiées peuvent provenir d'une réorganisation volontaire d'un panneau correct.

L'API des localisateurs présente ariaSnapshot() comme une capture et renvoie séparément à l'assertion de correspondance. Conservez les deux résultats pour diagnostiquer un écart : la capture réelle indique ce qui était exposé et le modèle ce qui était exigé. Un rapport indiquant seulement « snapshot réussi » laisse la condition essentielle du test indéterminée.

Un snapshot ARIA est également une représentation accessible particulière produite par la combinaison installée de Playwright et du navigateur. Il sert aux assertions de non-régression, mais son YAML ne transcrit pas une session de lecteur d'écran. La démarche générale de tests d'accessibilité par automatisation du navigateur distingue les vérifications structurelles des observations au clavier, avec des technologies d'assistance et d'autres éléments probants. Un arbre de rôles et de noms correspondant ne fournit qu'une partie de ces éléments.

Limiter la capture à l'état testé

Une assertion utile part d'un état stable de l'application et d'un localisateur qui identifie le composant concerné. Capturer toute la page peut inclure un compteur de navigation changeant, une notification ou un contenu latéral sans rapport. Remplacer toutes ces valeurs par des motifs permissifs rend l'assertion plus difficile à interpréter. Sélectionnez d'abord le panneau de paramètres, puis exprimez le contrat des commandes dont la sémantique importe.

L'exemple Playwright Test suivant est une démonstration indépendante et réutilisable. page.setContent() crée un balisage original sous votre contrôle ; aucune page distante, aucun compte authentifié ni service applicatif n'intervient. La première assertion établit la présence du panneau précis avant la capture de sa représentation accessible. L'exemple utilise volontairement un seul bouton pour faciliter l'examen du périmètre et du comportement du modèle.

import { test, expect } from '@playwright/test';

test('settings action keeps its accessible name', async ({ page }) => {
  await page.setContent(`
    <section aria-label="Settings">
      <h2>Delivery preferences</h2>
      <button aria-label="Save settings">Save</button>
    </section>
  `);

  const settings = page.getByRole('region', {
    name: 'Settings',
    exact: true,
  });
  await expect(settings).toBeVisible();
  console.log(await settings.ariaSnapshot());

  await expect(settings.getByRole('button')).toMatchAriaSnapshot(`
    - button "Save settings"
  `);
});

Ici, getByRole('button') continue à fonctionner lorsque le nom change, ce qui permet à l'assertion de signaler l'écart sémantique. Si le localisateur exige plutôt name: 'Save settings', changer ce nom peut empêcher sa résolution avant la comparaison du snapshot. Cet échec reste utile, mais suit une autre voie de diagnostic. Distinguez « l'ancien localisateur ne trouve plus la commande » de « la commande sélectionnée expose un autre nom ».

Pour une application qui charge les paramètres de manière asynchrone, la visibilité ne prouve pas à elle seule l'arrivée des données finales. Attendez un état de chargement terminé propre au composant ou une valeur de champ attendue avant la capture. Ne définissez pas la disponibilité par une durée arbitraire de waitForTimeout(). Sinon, le squelette de chargement et le panneau terminé deviennent deux candidats concurrents au snapshot, alors que la régression ne porte sur aucun de ces états transitoires.

Conservez le même périmètre entre la référence et les variantes modifiées. Capturer le panneau dans une variante et tout le corps dans une autre introduit une différence structurelle étrangère à l'expérience prévue. Consignez la version de Playwright, celle du navigateur, la zone d'affichage et le balisage contrôlé avec la comparaison reproductible. Ces données permettent de distinguer un échec ultérieur d'un changement d'environnement de test, sans le déduire du seul YAML.

La capture ne vérifie pas elle-même que la commande d'enregistrement est active, que le clic fonctionne ou qu'une requête aboutit. Ces besoins demandent leurs propres vérifications. Ajouter un snapshot à un test de formulaire doit identifier un contrat sémantique précis, comme le nom de l'action, plutôt que remplacer le test de son résultat. Un panneau peut exposer un excellent nom alors que son gestionnaire de clic est défaillant.

Une correspondance par rôle seul peut masquer une régression du nom

La documentation officielle sur la correspondance partielle montre un modèle de bouton dont le nom est omis. Elle précise que le test peut alors réussir quel que soit le libellé du bouton. Omettre un nom est un choix d'assertion, pas une demande à Playwright de déduire quels libellés sont équivalents. Si la régression porte sur les noms, cette omission retire la condition nécessaire au test.

Prolongez l'exemple contrôlé en modifiant uniquement aria-label. Une assertion par rôle seul et une assertion avec nom posent alors deux questions différentes sur la même commande. La première doit continuer à réussir puisque le rôle de bouton subsiste. La seconde doit échouer puisque le littéral exigé manque. L'assertion négative ci-dessous appartient à cette démonstration contrôlée ; un test de non-régression ordinaire doit conserver son exigence positive et échouer en présence du mauvais nom.

await page.setContent(`
  <button aria-label="Save settings">Save</button>
`);
const button = page.getByRole('button');

await expect(button).toMatchAriaSnapshot('- button');
await expect(button).toMatchAriaSnapshot('- button "Save settings"');

await button.evaluate(element => {
  element.setAttribute('aria-label', 'Apply');
});

await expect(button).toMatchAriaSnapshot('- button');
await expect(button).not.toMatchAriaSnapshot('- button "Save settings"');

Une capture réelle effectuée après la modification contient toujours le nouveau nom accessible. Le modèle par rôle seul n'a pas amené le navigateur à le supprimer : il ne le contraignait simplement pas. Cette distinction évite une erreur fréquente d'examen : constater une correspondance souple réussie et conclure que l'arbre réel est inchangé. Comparez les chaînes capturées pour savoir si la représentation a changé ; examinez le modèle pour comprendre pourquoi l'assertion a réussi.

La correspondance d'un nom n'est pas non plus une comparaison octet par octet de toute une capture. Les règles officielles normalisent les espaces dans les noms et valeurs textuelles, et la structure est sensible à l'ordre. Utilisez la sémantique documentée de l'API pour la version installée. Une assertion d'égalité directe entre deux chaînes capturées indique si ces chaînes sérialisées sont identiques, avec les conséquences plus strictes de cette comparaison.

Les expressions régulières peuvent assouplir volontairement une valeur variable tout en préservant le contenu significatif. Un nombre, comme le total de tickets, peut légitimement changer, alors que le nom d'une action peut être un besoin stable. Évitez un motif assez large pour accepter à la fois le libellé prévu et la régression étudiée. Définissez la variation sans importance avant d'assouplir le modèle ; un comparateur ne peut pas prendre cette décision produit.

De même, omettre des attributs d'état les laisse hors des contraintes de ce modèle. L'exemple officiel décrit une case à cocher dont checked est omis et dont l'état coché n'est donc pas imposé. Une assertion de case à cocher par rôle seul ne remplace pas une vérification de sélection. Faites correspondre la propriété nommée par le besoin au lieu de supposer qu'un snapshot réussi couvre tous les attributs accessibles.

La correspondance des enfants mérite la même attention. Un petit modèle ne doit pas être automatiquement décrit comme un inventaire complet de tous les descendants. La documentation actuelle présente un comportement configurable pour les enfants, mais la syntaxe peut différer de versions installées plus anciennes. Les exemples de bouton évitent ces options dépendantes de la version : un bouton sélectionné, une condition de rôle et, si nécessaire, un nom accessible littéral rendent le contrat appliqué explicite.

Comparer séparément les variantes de nom et de style

Le 2026-11-18, le cas de test local contrôlé a été exécuté avec Playwright 1.58.0, Chrome standard 157.0.8103.79 et macOS darwin arm64. Chacune des trois variantes utilisait un navigateur indépendant, avec des périodes d'exécution qui se chevauchaient. La zone d'affichage était de 640 × 320, avec un facteur d'échelle de périphérique 1. Le relevé docs/evidence/playwright-aria-snapshot-diff-review-run-20261118.json conserve les entrées, captures réelles, résultats du comparateur public et empreintes des images.

Dans la référence, le texte visible et aria-label étaient tous deux Save changes, avec un fond #2563eb. La variante de nom changeait uniquement aria-label en Publish changes. La variante de style conservait le balisage de référence et changeait le fond en #c2410c. Le bouton sélectionné et les deux modèles restaient identiques entre les conditions ; aucune modification de masquage ni d'état d'affichage n'intervenait.

Panneau de paramètres de référence : bouton bleu Save changes dont le nom accessible est également Save changes.

La capture de référence établit l'apparence affichée initiale. La capture du bouton était exactement - button "Save changes". Les modèles - button et - button "Save changes" réussissaient tous deux avec la véritable assertion toMatchAriaSnapshot() dans un contexte Playwright Test. Il s'agit des résultats du comparateur, pas d'une recherche manuelle de sous-chaîne dans le YAML.

Variante de nom : le bouton affiche toujours Save changes, mais son nom accessible est devenu Publish changes.

La variante de nom produisait - button "Publish changes": Save changes. Le Save changes final est un contenu conservé dans cette représentation capturée ; le nom accessible entre guillemets reste Publish changes. Sa présence après les deux-points ne fait pas contenir le libellé visible dans le nom accessible. Le comparateur par rôle seul réussissait, tandis que celui du nom littéral Save changes échouait après le délai configuré de 400 ms.

-- button "Save changes"
+- button "Publish changes": Save changes

La comparaison RGBA décodée trouvait 0 / 204800 pixels modifiés entre la référence et la variante de nom, et leurs empreintes PNG étaient identiques. C'est une égalité effectivement mesurée pour ces captures, pas une déduction tirée de leur ressemblance. Elle montre pourquoi une vérification par capture d'écran seule pourrait manquer cette modification précise du nom. La capture réelle du bouton et celle, plus large, de main avaient toutes deux changé.

Variante de style : le bouton Save changes est orange au lieu de bleu, tandis que son nom accessible et sa représentation ARIA capturée restent identiques.

La variante de style conservait - button "Save changes", avec réussite des deux modèles. Son image différait sur 9043 / 204800 pixels, soit 4.415527% de la zone d'affichage. Le rectangle englobant les pixels modifiés mesurait 196 × 48 aux coordonnées 81, 163, correspondant au bouton. Le comptage utilisait l'égalité exacte des RGBA décodés : un pixel était compté une fois dès qu'un canal différait, sans tolérance.

La sortie enregistrée juxtapose les deux erreurs de déduction :

name: ariaSnapshotEqual=false changedPixels=0/204800 roleOnlyMatch=true exactNameMatch=false
style: ariaSnapshotEqual=true changedPixels=9043/204800 roleOnlyMatch=true exactNameMatch=true

Comparaison des trois captures du bouton : résultats des modèles de rôle et de nom et nombre de pixels modifiés.

Dans le schéma, 1 signifie vrai et 0 signifie faux. Le nombre de pixels modifiés et l’égalité des arbres se lisent par rapport au bouton d’origine.

Ces nombres de pixels appartiennent au navigateur, aux polices et à la zone d'affichage de cette exécution. La documentation des comparaisons visuelles Playwright avertit que le rendu dépend du système hôte, de la version, des réglages et d'autres facteurs environnementaux. Cette mesure RGBA exacte diffère aussi d'une assertion toHaveScreenshot() avec des seuils configurés ; ces chiffres ne permettent aucune conclusion sur la tolérance de cette assertion. Si le rendu change d’un environnement à l’autre, recherchez la cause de l’écart visuel avant de remplacer la capture de référence.

Le cas de test n'exécutait aucun gestionnaire d'enregistrement, ne comparait pas de lecteurs d'écran et n'auditait pas la conformité d'accessibilité. Il mesurait des représentations et le comportement du comparateur sur un balisage local original. Ses assertions réussies ne mesurent pas BotBrowser et n'établissent pas qu'un vrai formulaire conserve une modification. Les résultats sur le nom et le style sont utiles précisément parce que l'entrée modifiée et la sortie observée sont explicites.

Choisir une correction avant de modifier la référence

L'échec d'un snapshot avec nom demande d'expliquer une différence. Commencez par le besoin : la commande doit-elle toujours exposer son nom initial ? Si oui, corrigez le balisage ou les données qui ont fourni le nom modifié. Changer le modèle ferait accepter à l'assertion le défaut qu'elle devait détecter. Une mise à jour de référence convient seulement si le besoin a changé ou si l'attente précédente était incorrecte.

La combinaison du cas de test, texte visible Save changes et nom accessible Publish changes, doit être rejetée. Le nom ne contient pas le libellé visible et ne préserve pas l'action d'enregistrement annoncée. L'explication W3C de Label in Name indique que le nom accessible d'une commande contient le texte présenté visuellement, permettant les commandes vocales fondées sur le libellé visible. Une réussite par rôle seul ne prouve pas que ce besoin est préservé.

Pour une modification terminologique volontaire, faites d'abord correspondre le libellé visible et le nom accessible à l'action réelle. Si le nouveau libellé visible est Save delivery preferences, un nom approprié peut reprendre cette phrase ou l'inclure avec le contexte nécessaire. Une demande de renommage et un modèle au nom exact mis à jour n'établissent pas cette relation. Examinez la commande réelle et exercez son action avant de modifier l'attente ciblée et les localisateurs fondés sur le nom.

Résultat observéDécision nécessaireVérification ciblée suivante
Le modèle avec nom échoue après une modification involontaire de aria-labelCorriger le nom dans l'applicationRétablir le libellé attendu et relancer l'assertion avec nom
Le modèle avec nom échoue après un changement terminologique vouluVérifier ensemble libellé visible, nom accessible et action réelleModifier l'attente uniquement lorsque ces conditions sont réunies
Le modèle par rôle seul accepte les deux nomsDécider si les noms appartiennent à cette assertionAjouter le nom exigé si le test protège la dénomination
Le YAML est stable, mais la présentation CSS a changéÉvaluer séparément le besoin visuelComparer la commande affichée dans l'environnement de référence
La capture diffère uniquement avant la fin du chargement des donnéesCorriger la précondition d'étatAttendre l'état précis de chargement terminé, puis capturer à nouveau

Playwright documente la mise à jour des attentes ARIA par ses outils de test, notamment --update-snapshots. Ce mécanisme écrit de nouvelles données attendues ; il ne classe pas une modification comme correcte. Examinez la proposition avant de l'accepter. Une mise à jour importante incluant des régions étrangères complique la vérification du maintien du contrat sémantique prévu.

Évitez de retirer le nom uniquement pour faire réussir un test. Une assertion par rôle seul peut parfaitement convenir à une vérification structurelle élémentaire dont le besoin est la présence d'un bouton. Elle est insuffisante pour approuver le nouveau nom de son action. Les deux constats sont compatibles puisque les tests ont des contrats différents. Explicitez ce contrat pour éviter qu'une maintenance ultérieure n'attribue une portée excessive à la réussite.

Si une assertion dédiée toHaveAccessibleName() protège déjà le nom, un snapshot plus large peut se concentrer sur une autre relation, comme la hiérarchie du composant. C'est une répartition volontaire des assertions, avec une exigence de nom visible ailleurs. Ce n'est pas la suppression silencieuse de la seule assertion qui rejetait auparavant un libellé involontaire. Gardez l'échec important facile à localiser.

Compléter les vérifications sémantiques par l'observation manquante

Utilisez toHaveScreenshot() lorsque le besoin porte sur l'apparence. Utilisez des assertions d'action et de résultat lorsqu'il porte sur le comportement. Employez des interactions au clavier et les vérifications d'accessibilité appropriées lorsqu'il porte sur l'utilisation effective de l'interface. Un snapshot ARIA peut détecter un nom ou une structure modifiés, mais ces observations complémentaires couvrent les propriétés absentes de son YAML.

Si le diff n'apparaît que par intermittence, conservez les éléments de l'état défaillant. La démarche de traces Playwright aide à corréler les actions et les états affichés d'une même exécution. Une trace peut expliquer pourquoi le panneau a été capturé pendant une transition ; une nouvelle capture réussie ne récupère pas l'état exact du décalage précédent. Enregistrez la sortie de l'arbre réel avec l'échec plutôt que dépendre uniquement d'une nouvelle exécution.

L'intégration Playwright de BotBrowser documente la sélection de son exécutable et la transmission d'un profil de navigateur. Ces entrées permettent de déclarer l'environnement d'une vérification de non-régression conçue séparément. Elles ne choisissent pas la force du modèle, n'approuvent pas un nom accessible modifié et ne remplacent pas une évaluation visuelle ou avec technologie d'assistance. Le cas local dans Chrome standard concerne l'observation et les assertions Playwright.

Lors d'une comparaison d'environnements, séparez l'identité du navigateur de celle de l'assertion. Si une exécution utilise un autre exécutable et un autre modèle, un résultat différent a deux explications possibles. Conservez la variante de page, le périmètre du localisateur et le modèle avant d'attribuer l'écart au navigateur. Une autre zone d'affichage peut également modifier le contenu adaptatif : consignez cette entrée plutôt que traiter chaque différence d'arbre comme une régression d'API.

Pour un vrai formulaire de paramètres, le plus petit ensemble utile pourrait protéger le nom de la commande d'enregistrement, exécuter l'action et vérifier son résultat visible. Ajoutez une assertion visuelle uniquement lorsqu'une attente d'apparence est explicite, et conservez les vérifications générales d'accessibilité pour leurs propres besoins. Les échecs obtenus identifieront un changement de nom, de comportement ou de rendu, au lieu de demander à un seul snapshot de diagnostiquer les trois.

FAQ

Un snapshot ARIA réussi signifie-t-il que la page est accessible ?

Il établit que la représentation sélectionnée satisfait le modèle fourni. Il n'établit ni l'utilisation au clavier, ni un contraste suffisant, ni des transitions de focus correctes, ni une utilisation réussie avec une technologie d'assistance précise. Ces propriétés demandent des observations adaptées, même si le modèle contient des rôles et des noms.

Un nom littéral est-il toujours préférable à une correspondance partielle ?

Utilisez un littéral lorsque ce nom fait partie du besoin stable. Une correspondance partielle peut convenir à une vérification structurelle dont les libellés varient intentionnellement, à condition qu'une autre assertion protège tout comportement de dénomination requis. Le choix dépend de la condition testée ; une rigueur supplémentaire sans besoin peut créer des échecs sans intérêt.

Un arbre inchangé peut-il approuver une refonte CSS ?

Il peut montrer que la représentation accessible comparée est restée stable pour l'état sélectionné. Il ne peut pas approuver l'espacement, les coupures, la couleur ou d'autres propriétés affichées absentes de cette représentation. Évaluez le résultat selon ses attentes visuelles et vérifiez si les variantes adaptatives introduisent du contenu ou une sémantique supplémentaires.

Sources

Conclusion pratique

Avant de modifier un snapshot ARIA Playwright, identifiez si la différence est un changement voulu de nom accessible, une contrainte absente du modèle ou un changement de rendu distinct. Conservez un nom littéral lorsque la dénomination constitue le besoin et comparez la capture réelle avec l'assertion. Commencez par une commande contrôlée et son nom d'action attendu ; approuvez une mise à jour de référence uniquement lorsque ce contrat est clair.

#Playwright#ARIA#Accessibilité#Tests Par Instantanés

Cet article fait partie du guide : Débuter avec l'automatisation du navigateur : carte initiale

Exécutez la même vérification dans BotBrowser

Chargez un profil, gardez dans le navigateur les signaux que vous venez de lire, puis confirmez le résultat sur votre propre machine avant le déploiement.