Dépannage

Watcher ne prend en charge que Chrome pour les tests, Chromium ou Microsoft Edge

Bien que le site Axe Developer Hub prenne en charge plusieurs navigateurs, le package Watcher ne prend en charge que Google Chrome pour les tests, Chromium ou Microsoft Edge. Problèmes que vous pourriez rencontrer :

• Si vous utilisez Google Chrome version 139 ou ultérieure, vous recevrez une erreur de Watcher. Utilisez plutôt Chrome pour Testing, Chromium ou Microsoft Edge.
• Si vous utilisez le navigateur Electron de Cypress, vous recevrez une erreur. Spécifiez le navigateur comme Chrome pour les tests, Chromium ou Microsoft Edge lorsque vous invoquez Cypress ; sinon, il utilisera par défaut le navigateur Electron. Consultez Lancement des navigateurs dans la documentation de Cypress pour plus d'informations.

Si vous utilisez WebdriverIO, WebDriverJS ou Java Selenium, vous devez configurer votre environnement de test pour utiliser explicitement Chrome pour Testing ou Microsoft Edge. Voir Utiliser Chrome pour les tests pour les étapes d'installation et les exemples de configuration spécifiques à la plateforme.

Voir Plateformes de test automatisé pour plus d'informations sur les logiciels pris en charge avec Watcher.

Échec de Microsoft Edge avec Java Selenium

Si vos tests Java Selenium renvoient une IllegalStateException avec le message La prise en charge de Microsoft Edge nécessite Selenium 4 ou une version plus récente, votre projet utilise Selenium 3. La EdgeOptions de Selenium 3 cible le navigateur EdgeHTML hérité, que Axe Watcher ne prend pas en charge. Mettez à niveau selenium-java vers la version 4.x pour tester dans Microsoft Edge, ou continuez à tester sous Chrome for Testing ou Chromium avec ChromeOptions et ChromeDriver, que l'intégration Java Selenium prend en charge à partir de Selenium 3.141.59.

Aucun Résultat de Microsoft Edge avec WebdriverIO

Si vos tests WebdriverIO s'exécutent contre Microsoft Edge, se terminent sans erreur et ne produisent aucun résultat dans Axe Developer Hub, vérifiez la version de votre Watcher. Utiliser Microsoft Edge avec WebdriverIO nécessite Watcher 4.6.0 ou une version ultérieure.

Dans les versions antérieures, Watcher envoyait ses options de navigateur à la capacité goog:chromeOptions. Le WebDriver de Microsoft Edge les lit depuis ms:edgeOptions à la place, donc les options étaient ignorées et aucune analyse n'était effectuée. Rien n'a échoué, c'est pourquoi les tests ont passé avec un ensemble de résultats vide. Mettez à jour vers la version 4.6.0 ou plus pour résoudre le problème.

La Propriété args d'une Capacité de Navigateur Est Invalide

Si Watcher signale que la propriété args de vos capacités de navigateur goog:chromeOptions ou ms:edgeOptions doit être un tableau de chaînes, définissez args sur un tableau de drapeaux de ligne de commande du navigateur, ou supprimez-la :

capabilities: {
  browserName: 'MicrosoftEdge',
  'ms:edgeOptions': {
    args: ['--window-size=1280,720']
  }
}

Les valeurs telles qu'une seule chaîne, un objet, ou un tableau contenant autre chose qu'une chaîne sont rejetées. Watcher 4.5.0 et les versions antérieures acceptaient certaines de ces valeurs et échouaient plus tard avec une erreur non liée.

Problèmes d'Accessibilité à l'Intérieur d'un Iframe de Croisement de Domaine Manquants

Si votre analyse réussit mais que vos résultats ne contiennent rien d'un <iframe> servi depuis une origine différente de la page en test, ce cadre n'a pas été analysé. Watcher analyse toujours les cadres de même origine, mais il analyse un cadre de croisement de domaine uniquement lorsque vous listez l'origine de ce cadre :

• (JavaScript ou TypeScript) allowedOrigins
• (Java) setAllowedOrigins()

axe: {
  allowedOrigins: [ 'https://pay.example.com' ]
}

N'incluez pas l'origine de votre propre application, qui est toujours autorisée.

Pour confirmer quelles origines ont été ignorées, recherchez le diagnostic cross_origin_frame_not_allowlisted. Il est rapporté que vous ayez ou non défini l'option, il nomme les origines de croisement de domaine qui n'ont pas été analysées, et il imprime la ligne de configuration que vous pouvez coller. Les diagnostics apparaissent uniquement dans la sortie de débogage : définissez DEBUG=axe-watcher:* lors de l'exécution de vos tests (JavaScript ou TypeScript), ou configurez votre cadre de journalisation pour afficher les messages DEBUG pour Axe Watcher (Java). Avec l'intégration Java Selenium, vous pouvez également activer la journalisation du débogage avec enableDebugLogger().

Si les résultats manquent toujours après avoir listé l'origine :

• Le cadre possède un attribut sandbox qui omet allow-same-origin, signalé comme cross_origin_frame_unscannable. Le cadre a alors une origine opaque qu'aucune entrée de votre liste ne peut nommer. Ajoutez allow-same-origin à l'attribut sandbox.
• Le cadre redirige loin de l'origine dans sa src, comme un domaine apex redirigeant vers www, ou http redirigeant vers https. Listez l'origine sur laquelle le cadre finit réellement.
• Le cadre est imbriqué à plus d'un niveau de profondeur. Les diagnostics de couverture sont rapportés à partir de la page de niveau supérieur concernant les cadres qu'elle intègre directement, donc un cadre profondément imbriqué n'est pas signalé.

Si l'analyse échoue complètement plutôt que de sous-rapporter, recherchez le diagnostic cross_origin_frame_timed_out : un cadre a répondu au ping initial de Watcher mais n'a pas renvoyé les résultats à temps. Retirez cette origine de votre liste ou augmentez runOptions.frameWaitTime.

Si le cadre est analysé mais que ses résultats ne reflètent pas ce que votre test a fait à l'intérieur, l'analyse automatique en est la cause. Elle ne peut pas détecter les changements effectués à l'intérieur d'un cadre, donc un cadre autorisé est analysé au moment du dernier changement de la page de niveau supérieur. Appelez analyze() vous-même après avoir interagi avec le contenu à l'intérieur d'un cadre. C'est un problème séparé de Aucun état de page capturé après le passage à une frame enfant, qui s'applique lorsque le contexte du navigateur est passé dans le cadre.

Voir Analyser des iframes de Croisement de Domaine pour une vue d'ensemble complète.

Origines Rejetées par allowedOrigins

Si Watcher rapporte qu'une entrée allowedOrigins est invalide, l'entrée n'est pas une origine simple qu'il peut comparer à un cadre. Chaque entrée doit inclure un schéma (http ou https), un hôte et un port facultatif, sans rien d'autre. Causes courantes :

• Un caractère joker, tel que https://*.example.com. Nommez chaque origine explicitement.
• Un chemin, une chaîne de requête, un fragment ou des identifiants, tels que https://pay.example.com/checkout.
• Un schéma manquant, tel que pay.example.com.
• Un schéma autre que http ou https.
• Un domaine contenant des caractères en dehors de l'alphabet anglais, comme café.example.com. Utilisez la forme punycode à la place.

Watcher rejette ceux-ci plutôt que de les ignorer, car une entrée qui ne correspond pas à la véritable origine d'un cadre laisserait le cadre non analysé alors que votre exécution de test rapporterait toujours un succès. Voir Analyser des iframes de Croisement de Domaine.

Résultats incomplets

Si votre suite de tests utilise plusieurs exécutants de tests qui s'exécutent en parallèle et utilisent le même ID de build non nul, les résultats de chaque exécutant de tests remplaceront ceux des autres exécutants pour le même SHA de commit Git, donnant des résultats incomplets. Vous devez vous assurer que chaque exécutant de tests utilise le même ID de build non nul.

Vous définissez généralement l'ID de build dans votre AxeConfiguration.

Pour plus d'informations sur l'utilisation des runners de tests parallèles avec différentes plateformes CI/CD, consultez Exécuter des tests en parallèle.

Erreurs d'accessibilité en double ou nombre de nouveaux problèmes incorrect

Si votre site Web utilise des identifiants dynamiques qui changent à chaque fois que la page est actualisée, vous verrez probablement des erreurs d'accessibilité en double, en particulier les problèmes marqués comme nouveau lorsque les tests précédents présentent le même problème sur le même élément. (Axe Developer Hub identifie le même élément entre les séries de tests par son sélecteur CSS et son XPath, qui incorporent tous deux l'identifiant de l'élément.) Pour résoudre ce problème, vous devez définir la propriété ancestry dans l'objet runOptions de votre configuration sur true. L'exemple ci-dessous montre comment définir l'option dans votre configuration :

axe: {
  runOptions: {
    ancestry: true
  }
}

Voir Utilisation de sélecteurs dynamiques pour plus de conseils sur l'utilisation des sélecteurs dynamiques.

Si le nombre de vos problèmes est toujours incorrect après avoir activé ancestry, vérifiez si les URL que vos tests visitent changent entre les exécutions. L'URL est comparée dans son intégralité, y compris toute chaîne de requête, donc un identifiant de session ou un paramètre empêchant la mise en cache fait que tous les problèmes de la page semblent nouveaux. Voir URL dynamiques.

Voir (JavaScript/TypeScript) runOptions ou (Java) AxeWatcherOptions.setRunOptions() pour plus d'informations.

Ancienne version de @axe-core/watcher

Si vous utilisez la version 3.18.0 ou une version antérieure de @axe-core/watcher, vous recevrez ce message d'avertissement :

Axe Developer Hub respecte désormais les paramètres définis dans Configuration Axe, et les exécutions de tests créées par les versions de @axe-core/watcher version 3.18.0 ou antérieure génèrent des sessions qui n'étaient pas conscientes des paramètres globaux dans la configuration Axe. Vous devriez mettre à jour votre package @axe-core/watcher et relancer vos tests pour créer des sessions qui suivent la configuration Axe de votre entreprise. Voir Utilisation des configurations globales.

Aucun état de page capturé après le passage à une frame enfant

Si votre test change le contexte actuel du navigateur vers un cadre enfant en utilisant switchToFrame() (WebdriverIO ou WebDriverJS) ou switchTo().frame() (Java Selenium), Axe Watcher ne capturera pas les états de la page pour les actions effectuées pendant que le navigateur est centré sur le cadre enfant. Axe Watcher capture les états de la page uniquement lorsque le contexte du navigateur est sur le cadre de niveau supérieur.

Ceci est une question distincte de savoir si l'iframe contenu est analysée. Watcher analyse les cadres de même origine, et les cadres de croisement de domaine dont vous listez l'origine ; voir Analyser des iframes de Croisement de Domaine.

Par exemple, dans WebdriverIO, l'appel click() ci-dessous ne produira pas d'état de page :

await browser.url('https://example.com')
const iframe = await browser.$('iframe')
await browser.switchToFrame(iframe)
// Actions taken in the child frame will not be analyzed
await button.click()

Pour reprendre la capture des états de page, revenez à la frame de niveau supérieur avant de continuer :

// WebdriverIO
await browser.switchToParentFrame()

// WebDriverJS / Java Selenium
await driver.switchTo().defaultContent()

La méthode setContent() de Playwright n'est pas prise en charge

Axe Watcher ne prend pas en charge les tests qui appellent les méthodes page.setContent() ou frame.setContent() de Playwright. Cette limitation s'applique à la fois au package JavaScript/TypeScript et à la bibliothèque Java.

Ces méthodes remplacent l'ensemble du document en utilisant document.write() en interne, ce qui supprime le contexte sur lequel Axe Watcher se base pour analyser la page. Axe Watcher analyse la page avec succès jusqu'au moment de l'appel, mais après cela, Axe Watcher ne peut plus analyser la page ni envoyer ses résultats, et votre test échoue avec des messages de délai d'attente similaires aux suivants :

Error: Watcher timed out before it could finish analyzing the page state. To resolve this problem, increase the `timeout.analyze` property within your configuration or see https://docs.deque.com/developer-hub/2/en/dh-troubleshooting for more troubleshooting.

Error: Watcher timed out sending results to the server. To resolve this problem, increase the `timeout.flush` property within your configuration or see https://docs.deque.com/developer-hub/2/en/dh-troubleshooting for more troubleshooting.

Au lieu de paramétrer directement le balisage, servez-le depuis une URL et naviguez-y avec page.goto() afin que le navigateur charge le document normalement :

// Not supported by Axe Watcher:
await page.setContent('<my-button disabled></my-button>')

// Navigate to a URL that serves the same markup instead:
await page.goto('http://localhost:6006/my-button.html')

État de Page Supplémentaire Généré par cy.screenshot()

Si vous appelez cy.screenshot() dans vos tests Cypress, Axe Watcher peut générer un état de page supplémentaire. Lorsque Cypress prend une capture d'écran, il modifie brièvement le DOM pour désactiver les animations, et l'observateur DOM d'Axe Watcher peut détecter cette modification comme un changement d'état de la page. C'est un comportement attendu et cela n'affecte pas la précision de vos résultats d'accessibilité.

Expiration de la méthode du contrôleur

(JavaScript ou TypeScript uniquement) Vous recevrez un message similaire au suivant si les appels à méthodes du contrôleur (définis dans la classe de base abstraite Controller comme analyze(), flush(), start(), et stop()) ou commandes personnalisées de Cypress expirent :

Error: Watcher could not send results to the server. To resolve this problem, adjust your `timeout.flush` property within your configuration or see https://docs.deque.com/developer-hub/wa-troubleshooting for more troubleshooting.

La méthode Controller spécifiée (ici, la méthode flush()) a nécessité plus de temps que prévu pour s'achever et a expiré. Vous pouvez modifier le temps par défaut en ajoutant un objet timeout à votre configuration :

axe: {
  timeout: {
    flush: 10000
  }
}

Voir Définir les délais d'attente pour des informations sur l'utilisation des délais d'attente.

Voir Interface Timeouts et timeouts pour plus d'informations. Les valeurs de temps d'attente par défaut sont affichées dans le tableau sous Interface Timeouts.

Résultats non affichés

Si vous avez exécuté votre suite de tests et qu'aucun résultat n'apparaît dans Axe Developer Hub pour un projet donné, la cause pourrait se trouver parmi les raisons des sections suivantes :

Non configuration de Axe Watcher

Votre suite de tests modifiée doit appeler le fonction de configuration approprié pour votre framework de test avant de lancer vos tests. Si vous ne configurez pas correctement Axe Watcher, vous recevrez un message indiquant que vous devez configurer Axe Watcher. Par exemple, si vous oubliez de configurer Axe Watcher avec Cypress, vous verrez ce message lorsque vous exécuterez votre suite de tests :

Cypress is not configured for axe Watcher. Please ensure that axe Watcher's cypressConfig() is invoked within Cypress's defineConfig() in your cypress.config.js. All tests will fail with this error.

Consultez la configuration instructions pour des exemples de configuration pour votre langage et framework de tests de navigateur.

Résultats non vidés

Vous devez appeler la fonction flush() (ou la commande personnalisée axeWatcherFlush() dans Cypress) pour renvoyer les résultats collectés aux serveurs de Deque afin que les résultats puissent être présentés sur le site Web Axe Developer Hub. Habituellement, vous appelez la fonction flush() dans le hook de nettoyage de votre plateforme d'automatisation.

Par exemple, dans le fichier support/e2e.js de Cypress, vous ajoutez l'appel à afterEach() :

// Flush axe-watcher results after each test.
afterEach(() => {
  cy.axeWatcherFlush()
})

Utilisation de l'option --incognito

Vous ne pouvez pas utiliser l'option --incognito en ligne de commande avec Chrome ; autrement, vos tests échoueront silencieusement. Si vous utilisez le mode incognito pour éviter d'écrire des fichiers mis en cache sur le disque (les fichiers mis en cache sont conservés en mémoire uniquement en mode incognito), utilisez plutôt les méthodes de mise en cache de votre suite de tests.

Ne pas définir les variables d'environnement requises

Si vous expérimentez avec les exemples dans le watcher-examples sur GitHub, notez que les exemples utilisent des variables d'environnement pour définir la clé API et l'ID du projet, API_KEY et PROJECT_ID.

Test exécuté trop rapidement

Vos tests peuvent s'exécuter trop rapidement, déchargeant la page et libérant ses ressources avant que Watcher puisse l'analyser. Pour résoudre ce problème, vous pouvez ajouter un délai à la fin du test pour permettre l'analyse de la page.

Par exemple, dans Cypress, vous pouvez ajouter un délai de 10 secondes (10 000 millisecondes) avec la méthode cy.wait() :

describe('Visitor', () => {
  it('should visit example.com', () => {
    cy.visit('https://www.example.com')
    cy.wait(10000);  })
})

Clé API manquante ou invalide

Une clé API invalide ou manquante apparaît comme un fichier de configuration invalide dans Cypress. La trace de la pile révélera si elle est invalide ou manquante. Une clé **manquante** entraîne le résultat suivant :

AssertionError [ERR_ASSERTION]: API key is required
    at validateApiKey ...

(De nombreuses lignes de la trace de pile ont été supprimées pour plus de concision.)

Une clé **invalide** entraîne la trace de pile suivante (abrégée) :

Error: Server responded to https://axe.deque.com/api/api-keys/test/validate/axe-devtools-watcher with status code 404:
{"error":"Invalid API key"}
    at Response.getBody
...

Aide

Si vous ne pouvez pas résoudre votre problème, veuillez nous envoyer un email pour que nous puissions vous aider.