Utiliser des sélecteurs dynamiques

Lors du test de pages qui génèrent des IDs d'éléments ou des noms de classes dynamiques à chaque chargement, Axe Watcher peut avoir du mal à déterminer si les problèmes d'accessibilité sont des doublons entre les exécutions de test. Cet article explique comment configurer Watcher pour gérer ces scénarios correctement. Une URL dynamique cause le même symptôme pour une raison différente et nécessite une solution différente, abordée ci-dessous en URLs dynamiques.

Le problème avec les sélecteurs dynamiques

Par défaut, Axe Watcher utilise des sélecteurs CSS incluant des identifiants d'éléments et des classes pour identifier où se produisent les problèmes d'accessibilité. Par exemple, un problème peut être signalé à :

iframe#main-iframe

Cette approche fonctionne bien lorsque les identifiants et les classes de votre page restent cohérents entre les chargements de page. Cependant, de nombreuses applications web modernes génèrent des identifiants dynamiques qui changent à chaque rendu de la page, tels que :

• #component-a1b2c3d4
• .form-field-xyz789

Axe Watcher envoie également un XPath pour chaque élément, et Axe Developer Hub considère un match sur l'un ou l'autre sélecteur comme le même élément. Comme un XPath n'inclut jamais les noms de classes, une page dont les noms de classes seuls sont dynamiques est souvent suivie correctement sans configuration supplémentaire. Un XPath inclut cependant l'ID d'un élément lorsque cet ID est unique sur la page, produisant un chemin tel que //div[@id='component-a1b2c3d4']. Un ID dynamique modifie donc à la fois le sélecteur CSS et le XPath, ne laissant rien de stable sur lequel se baser.

Lorsque les identifiants changent entre les exécutions de test de cette manière, Axe Watcher ne peut pas déterminer si un problème est un doublon d'un problème précédemment détecté ou une nouvelle occurrence. Cela peut entraîner :

• Le même problème signalé à la fois comme "nouveau" et "résolu" à chaque exécution de test
• Un suivi inexact de votre progression en matière d'accessibilité au fil du temps
• Des difficultés à identifier quels problèmes ont réellement été corrigés

La solution : Activer le suivi de l'ascendance

Pour gérer les sélecteurs dynamiques, définissez l'option ancestry sur true dans votre configuration runOptions. Une fois activée, Axe Watcher utilise la position de l'élément dans l'arborescence DOM plutôt que de se fier aux identifiants et aux classes pour localiser les éléments entre les exécutions de tests.

Avec ancestry activé, un sélecteur qui ressemblait auparavant à ceci :

iframe#main-iframe

Inclura à la place le chemin complet depuis l'élément racine :

html > body > div:nth-child(20) > div:nth-child(1) > div > div > ul > li:nth-child(1) > div > span > iframe

Ce sélecteur positionnel reste cohérent entre les chargements de page, même lorsque les identifiants et les classes changent, permettant à Axe Watcher de suivre avec précision les problèmes en double.

Exemples de configuration

JavaScript et TypeScript

Ajoutez l'option ancestry à vos runOptions de configuration d'axe :

const config = {
  axe: {
    apiKey: process.env.ACCESSIBILITY_API_KEY,
    projectId: process.env.PROJECT_ID,
    runOptions: {
      ancestry: true
    }
  }
}

Java

Utilisez la méthode setAncestry() sur votre objet AxeRunOptions :

AxeRunOptions runOptions = new AxeRunOptions()
    .setAncestry(true);

AxeWatcherOptions options = new AxeWatcherOptions()
    .setApiKey(System.getenv("ACCESSIBILITY_API_KEY"))
    .setProjectId(System.getenv("PROJECT_ID"))
    .setRunOptions(runOptions);

AxeWatcher watcher = new AxeWatcher(options);

Quand utiliser le suivi de l'ascendance

Activez ancestry: true lorsque votre application :

• Utilise des frameworks qui génèrent des identifiants de composants dynamiques (React, Vue, Angular)
• Emploie des bibliothèques CSS-in-JS qui génèrent des noms de classe uniques
• A des champs de formulaire ou des éléments interactifs avec des identifiants générés automatiquement
• Montre des comptes "nouveau problème" et "problème résolu" incohérents entre les exécutions de tests pour ce qui semble être les mêmes problèmes

Compromis à considérer

Bien que le suivi de l'ascendance résolve le problème des sélecteurs dynamiques, certains points doivent être pris en compte :

• Lisibilité des sélecteurs : Les sélecteurs positionnels sont plus longs et peuvent être plus difficiles à lire lors de l'examen des problèmes dans Axe Developer Hub.
• Sensibilité à la structure DOM : Si la structure DOM de votre page change de manière significative entre les rendus (pas seulement les identifiants/classes), les sélecteurs positionnels peuvent également changer.
• Débogage : Lors de l'investigation d'un problème, vous pouvez trouver plus facile de localiser un élément par un identifiant significatif plutôt que par sa position dans l'arborescence DOM.

Pour la plupart des applications avec des identifiants dynamiques, les avantages d'un suivi précis des problèmes l'emportent sur ces compromis.

URLs dynamiques

Les sélecteurs d'éléments ne sont qu'une partie de la façon dont Axe Developer Hub identifie un problème. L'URL de la page est également comparée dans son intégralité, y compris toute chaîne de requête. Activer ancestry n'a aucun effet sur cette comparaison.

Une URL qui varie entre les exécutions de test produit donc les mêmes symptômes qu'un sélecteur dynamique, et le fait de manière plus agressive : lorsqu'une URL n'a pas été vue auparavant, chaque problème trouvé dessus est signalé comme nouveau, sans que les sélecteurs d'éléments ne soient consultés. Les causes courantes incluent :

• IDs de session ou jetons d'authentification inclus dans la chaîne de requête
• Horodateurs ou paramètres anti-cache, tels que ?v=1738012800
• IDs aléatoires dans le chemin, tels que /orders/8f3c1b2a/summary
• Fixtures de test qui génèrent un nouvel enregistrement, et donc une nouvelle URL, à chaque exécution

Il n'y a pas d'option de configuration qui normalise les URLs avant qu'elles ne soient comparées, donc cela doit être résolu dans votre suite de tests : naviguez vers des URLs déterministes, de sorte que la même page produise la même URL à chaque exécution. En pratique, cela signifie généralement d'initialiser des données de test fixes au lieu de générer de nouveaux enregistrements par exécution, et de retirer ou de fixer les paramètres de requête volatils avant que la page ne soit scannée.

Si une URL ne peut vraiment pas être stabilisée, vous pouvez la garder hors de vos résultats totalement avec excludeUrlPatterns, bien que cela signifie que la page n'est pas scannée du tout plutôt que suivie correctement. Voir Exclure les URLs de l'analyse pour les détails.

Voir aussi

• Référence API pour JavaScript et TypeScript Documentation complète pour runOptions et d'autres options de configuration
• Référence API Java pour les options d'exécution Classe AxeRunOptions
• Glossaire : Doublon Comprendre comment Axe Developer Hub identifie les problèmes en double