Dépannage

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

Bien que le site Web 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 (JavaScript/TypeScript ou Java avec Playwright). Problèmes que vous pourriez rencontrer :

• Si vous utilisez la version 139 de Chrome ou ultérieure, vous recevrez une erreur de Watcher. Utilisez Chrome for Testing ou Chromium à la place (avec JavaScript/TypeScript ou Java avec Playwright, vous pouvez également utiliser 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 ou WebDriverJS, vous devez configurer votre setup de test pour utiliser explicitement Chrome for Testing ou Microsoft Edge. Si vous utilisez Java Selenium, vous devez configurer votre setup de test pour utiliser explicitement Chrome for Testing. Voir Utiliser Chrome pour les tests pour les étapes d'installation et des exemples de configuration spécifiques à la plateforme.

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

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 ou des noms de classe qui changent à chaque actualisation de la page, vous verrez probablement des erreurs d'accessibilité en double, notamment des problèmes marqués comme nouveau lorsque les exécutions de tests précédentes montrent le même problème sur le même élément. (Axe Developer Hub utilise des identifiants et des classes pour identifier le même élément entre les exécutions de tests.) 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.

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 une sous-trame en utilisant switchToFrame() (WebdriverIO ou WebDriverJS) ou switchTo().frame() (Java Selenium), Axe Watcher ne capturera pas les états de page pour les actions effectuées pendant que le navigateur est focalisé sur la sous-trame. Axe Watcher ne peut analyser que la trame de niveau supérieur.

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()

É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.