Analyser les iframes d'origine croisée

Axe Watcher analyse le contenu des éléments de même origine <iframe> ainsi que le reste de la page. Les frames provenant d'une origine différents sont ignorées par défaut, et les problèmes d'accessibilité à l'intérieur ne sont pas inclus dans vos résultats.

L'option allowedOrigins permet d'analyser ces frames. Vous nommez les origines que vous souhaitez couvrir, et Watcher analyse les frames provenant de celles-ci lors de chaque analyse de la page d'accueil.

Cette option nécessite Watcher 4.6.0 ou une version ultérieure, et est disponible avec les intégrations JavaScript/TypeScript et Java.

Quand vous en avez besoin

Réglez allowedOrigins lorsque des parties significatives de votre expérience utilisateur sont servies depuis une autre origine, comme un formulaire de paiement hébergé, un widget de réservation ou de planification intégré, un lecteur multimédia avec ses propres contrôles, ou un widget d'aide ou de chat.

Vous n'en avez pas besoin pour les frames provenant de votre propre origine, qui sont toujours analysées.

Configurer les origines autorisées

Ne listez que les origines intégrées que vous souhaitez couvrir. L'origine de votre propre application est toujours autorisée, donc ne l'incluez pas.

JavaScript et TypeScript

axe: {
  apiKey: process.env.AXE_DEVELOPER_HUB_API_KEY,
  projectId: process.env.AXE_PROJECT_ID,
  allowedOrigins: [ 'https://pay.example.com' ]
}

Java

AxeWatcherOptions options = new AxeWatcherOptions()
    .setApiKey(System.getenv("ACCESSIBILITY_API_KEY"))
    .setProjectId(System.getenv("PROJECT_ID"))
    .setAllowedOrigins(new String[] {"https://pay.example.com"});
AxeWatcher watcher = new AxeWatcher(options);

Décidez quelles origines de confiance

La liste blanche est appliquée dans chaque frame, pas seulement dans le principal, et fonctionne dans les deux sens : un frame accepte un message uniquement d'une origine présente sur sa propre liste, et ne répond qu'à ces origines. En pratique, chaque frame autorise sa propre origine, chaque origine que vous listez et, uniquement lorsque l'origine de ce frame est l'une que vous avez listée, l'origine du frame qui l'intègre directement, à condition que cet intégrateur soit soit la page de niveau supérieur soit une autre origine que vous avez listée.

Ainsi, lister une origine ne l'autorise pas à répondre à n'importe quelle page qui se trouve l'encadrer. Ce qu'il autorise, c'est l'échange de balisage entre ce frame et son intégrateur au sein de la page testée, ce qui explique pourquoi la liste doit rester limitée aux éléments intégrés de confiance.

C'est aussi pourquoi les jokers ne sont pas pris en charge et pourquoi il n'y a pas d'option signifiant "analyser chaque frame". Une liste blanche que vous ne pouvez pas énumérer n'est pas une liste blanche. Nommez chaque origine explicitement, et limitez la liste aux éléments intégrés que vous devez effectivement couvrir.

Réfléchissez à savoir si la page testée affiche quelque chose de sensible pendant que vos tests sont effectués. Si vos environnements de test utilisent des données personnelles ou de paiement réalistes, pesez cela par rapport aux origines tierces que vous êtes sur le point d'autoriser.

Écrivez correctement les origines

Chaque entrée doit être une origine et rien d'autre : un schéma (http ou https), un hôte, et un port optionnel. Watcher normalise ce que vous fournissez en supprimant une barre oblique finale et un port par défaut (:80 pour http, :443 pour https), en mettant l'hôte en minuscules et en éliminant les doublons.

Watcher rejette une entrée qu'il ne peut pas utiliser en signalant une erreur lorsque votre configuration est lue, plutôt que de laisser la suite de test se poursuivre et n'analyser rien. En Java, setAllowedOrigins() lance IllegalArgumentException.

Domaines contenant des caractères non anglais

Un domaine contenant des caractères en dehors de l'alphabet anglais, comme café.example.com ou пример.рф, a une deuxième orthographe équivalente composée uniquement des lettres a à z, des chiffres 0 à 9, et des tirets. Cette orthographe est appelée punycode, et elle commence toujours par xn--. Les navigateurs convertissent un domaine en sa forme punycode avant de l'utiliser, donc le punycode est la forme avec laquelle Watcher compare.

Pour trouver la forme punycode, visitez l'URL du frame et lisez la barre d'adresse de votre navigateur après le chargement de la page, ou utilisez n'importe quel convertisseur punycode en ligne.

Ne substituez pas une orthographe anglaise ressemblant, telle que cafe.example.com pour café.example.com. Watcher l'accepte, car c'est une origine valide, mais elle ne correspond jamais à la vraie origine du frame, donc le frame reste silencieusement non analysé.

Les mots-clés <same_origin> et <unsafe_all_origins>

Le moteur d'accessibilité utilisé par Watcher, axe-core, accepte deux mots-clés dans son propre paramètre équivalent, et vous pouvez les rencontrer dans la documentation de axe-core ou dans une configuration que vous migrez :

• <same_origin> signifie "l'origine propre à cette page". Watcher l'accepte, mais cela n'a aucun effet, car votre propre origine est toujours autorisée.
• <unsafe_all_origins> signifie "toute origine, y compris celles que vous n'avez pas listées". Watcher la rejette avec une erreur, pour les raisons décrites dans Décidez quelles origines de confiance.

Capturer les modifications effectuées à l'intérieur d'un frame

L'analyse automatique détecte les modifications de la page de niveau supérieur. Elle ne peut pas détecter une modification faite à l'intérieur un frame, que ce cadre soit de même origine ou d'origine croisée. Un cadre autorisé est donc analysé à partir de la dernière modification de la page de niveau supérieur.

Cela est important lorsque vous interagissez avec du contenu à l'intérieur d'un frame. L'interaction modifie le contenu du frame, la page de niveau supérieur reste inchangée, et donc aucune analyse automatique n'est exécutée :

// Interacting inside the frame doesn't trigger an automatic analysis
await page.frameLocator('#pay').getByRole('button', { name: 'Continue' }).click()

// Analyze explicitly to capture the resulting state
await controller.analyze()

Appelez analyze() après l'interaction pour capturer l'état résultant. Une analyse que vous demandez explicitement s'exécute toujours. Voir Gérez vos analyses pour savoir comment obtenir un objet contrôleur dans votre cadre de test.

Trouvez les frames qui vous manquent

Watcher signale les cadres cross-origin qu'il a ignorés, que vous ayez configuré allowedOrigins ou non. Cela signifie que vous pouvez découvrir quels éléments intégrés manquent dans vos résultats avant de configurer quoi que ce soit.

Le diagnostic cross_origin_frame_not_allowlisted nomme chaque origine ignorée et inclut la ligne allowedOrigins à coller dans votre configuration. Sur une page avec de nombreux éléments intégrés tiers, la liste est limitée et le reste est résumé par « et N de plus ».

Les diagnostics apparaissent uniquement dans les sorties de débogage, et chacun est signalé tout au plus une fois par exécution de test.

JavaScript et TypeScript : définissez la variable d'environnement DEBUG lorsque vous exécutez vos tests.

DEBUG=axe-watcher:* npx playwright test

Java : les contrôleurs enregistrent chaque diagnostic au niveau DEBUG, donc configurez votre cadre de journalisation pour afficher les messages DEBUG pour Axe Watcher. Avec l'intégration Selenium, vous pouvez également appeler enableDebugLogger() sur AxeWatcher.

Deux autres diagnostics signalent des cadres qui ont été autorisés mais toujours pas analysés. Les deux sont décrits sous Limitations :

• cross_origin_frame_unscannable, pour un cadre mis en bac à sable sans allow-same-origin.
• cross_origin_frame_timed_out, pour un cadre qui n'a pas renvoyé de résultats à temps.

Si vous préférez que la couverture des cadres apparaisse dans vos résultats plutôt que dans la sortie de débogage, activez meilleures pratiques. La règle frame-tested d'axe-core distingue « aucun problème dans ce cadre » de « ce cadre n'a jamais été analysé » : un cadre que Watcher n'a pas pu atteindre est signalé comme nécessitant une révision. Étant donné que c'est une règle de meilleure pratique, un ensemble de règles limité aux règles WCAG l'exclut.

Les problèmes trouvés à l'intérieur d'un cadre sont attribués à l'état de la page qui intègre le cadre, et non à un état de page séparé.

Limitations

La limitation à laquelle vous serez probablement confronté est que l'analyse automatique ne peut pas voir les modifications effectuées à l'intérieur d'un cadre, décrites sous Capturer les modifications effectuées à l'intérieur d'un cadre. Le reste est ci-dessous.

Un cadre en bac à sable a besoin de allow-same-origin

Un cadre dont l'attribut sandbox omet allow-same-origin a une origine opaque, qu'aucune entrée de liste blanche ne peut nommer, il ne peut donc pas être analysé peu importe ce que vous listez. Une fois que vous listez son origine, Watcher le signale avec le diagnostic cross_origin_frame_unscannable. Jusqu'à ce que vous le fassiez, il est signalé comme cross_origin_frame_not_allowlisted comme tout autre cadre ignoré. Ajoutez allow-same-origin à l'attribut sandbox pour analyser le cadre.

Seul allow-same-origin importe ici. Un cadre en bac à sable qui omet allow-scripts est toujours analysé normalement, car le script de contenu de Watcher s'exécute dans un monde isolé et s'exécute même là où les scripts de la page sont bloqués.

Éléments intégrés qui redirigent

Un élément intégré dont src redirige vers une autre origine, comme une redirection de domaine apex vers www ou http redirigeant vers https, finit par arriver sur une origine qui n'est pas celle que vous avez listée, donc elle n'est pas analysée. Listez l'origine sur laquelle le cadre termine réellement plutôt que celle dans son src.

Les cadres imbriqués à plus d'un niveau ne sont pas signalés

Les diagnostics de couverture des cadres sont signalés à partir de la page de niveau supérieur, concernant les cadres qu'elle intègre directement. Un cadre qui n'a pas pu être atteint mais qui est imbriqué à deux niveaux ou plus n'apparaîtra pas dans votre sortie de débogage, même si son contenu manque dans les résultats.

Un cadre qui ne répond jamais échoue à l'analyse

Un cadre qui répond au ping initial de Watcher mais ne renvoie jamais de résultats échoue à l'analyse plutôt que de la sous-estimer, et Watcher signale le diagnostic cross_origin_frame_timed_out. Si un élément intégré tiers lent fait cela, soit retirez son origine de allowedOrigins soit augmentez runOptions.frameWaitTime.

Budget pour une analyse plus lente

Chaque origine que vous autorisez ajoute le contenu total de ce cadre à chaque analyse de la page. Le contenu du cadre est collecté, transféré à la page de niveau supérieur et combiné avec le reste des résultats, et tout cela se passe pendant que votre test attend.

Le temps ajouté à ceci augmente avec la taille et la complexité du contenu encadré, ainsi qu'avec le nombre de cadres que vous autorisez. Avec l'analyse automatique activée, le coût se répète à chaque interaction analysée par Watcher, donc une longue suite de tests avec plusieurs cadres autorisés peut ajouter une quantité de temps considérable à une exécution. Deux façons de la garder gérable :

• Limitez allowedOrigins aux éléments intégrés que vous avez réellement besoin de couvrir, plutôt qu'à toutes les origines tierces de la page.
• Envisagez de l'activer par projet ou par suite de tests, afin que les suites qui n'utilisent pas de contenu encadré n'en supportent pas le coût.

Si vous souhaitez mesurer l'effet sur votre propre suite, chronométrez une exécution représentative avant et après l'activation de l'option.

Temps limites

Parce qu'analyser un cadre cross-origin inclut d'attendre que ce cadre réponde, les délais par défaut analyze et flush passent de 5000 ms à 10000 ms lorsque allowedOrigins est défini sur un tableau non vide. Les valeurs par défaut pour start et stop restent inchangées. Les valeurs de délai que vous définissez vous-même sont toujours utilisées telles quelles, donc cela n'affecte que les valeurs par défaut. Voir Définir les délais.

Cela s'applique aux intégrations JavaScript et TypeScript. Java Watcher ne prend actuellement pas en charge les délais personnalisés, et ses valeurs de délai ne sont pas modifiées par cette option.

Si vous définissez vos propres délais puis activez allowedOrigins, réexaminez-les. Une valeur ajustée pour une page sans contenu encadré peut maintenant être trop stricte.

Sujets connexes

• Définir les délais
• Contrôlez vos analyses
• Meilleures pratiques
• Dépannage
• Référence API pour la version JavaScript et TypeScript de Watcher
• OptionsAxeWatcher