Dépannage

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

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

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

Si vous utilisez WebdriverIO, WebDriverJS ou Java Selenium, vous devez configurer votre ensemble de tests pour utiliser explicitement Chrome pour les tests. 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 d'exécutants de tests parallèles avec différentes plateformes CI/CD, voir 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 ID dynamiques ou des noms de classe qui changent à chaque rafraîchissement de la page, vous verrez probablement des erreurs d'accessibilité en double, en particulier les problèmes marqués comme nouveau lorsque les exécutions de tests précédentes présentent le même problème sur le même élément. (Axe Developer Hub utilise les ID et les 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 ancestry propriété dans l'objet runOptions dans votre configuration à 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 de 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 adhère désormais aux paramètres définis dans la Configuration axe, et les exécutions de tests créées par les versions de @axe-core/watcher 3.18.0 ou plus anciennes génèrent des sessions qui ne tiennent pas compte des paramètres globaux de la Configuration axe. Vous devriez mettre à jour votre package @axe-core/watcher et relancer vos tests pour créer des sessions conformes à la Configuration axe de votre entreprise. Voir Utilisation des configurations globales.

Expiration de la méthode du contrôleur

(JavaScript ou TypeScript uniquement) Vous recevrez un message similaire à ce qui suit si les appels aux méthodes du contrôleur (définies dans la Controller classe de base abstraite comme analyze(), flush(), start(), et stop()) ou les 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 spécifiée Controller (ici, la méthode flush()) a nécessité plus de temps que le délai par défaut pour se terminer et a expiré. Vous pouvez modifier le délai par défaut en ajoutant un timeout objet à votre configuration :

axe: {
  timeout: {
    flush: 10000
  }
}

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

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

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 certain projet, la cause pourrait se trouver parmi les raisons des sections suivantes :

Non configuration de axe Watcher

Votre suite de tests modifiée doit appeler la fonction de configuration appropriée pour votre framework de test avant d'exécuter 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 les instructions de configuration 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 envoyer les résultats collectés aux serveurs de Deque afin qu'ils puissent être présentés sur le site web de Axe Developer Hub. En général, 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 ; sinon, vos tests échoueront silencieusement. Si vous utilisez le mode incognito pour éviter d’écrire des fichiers mis en cache sur le disque (les fichiers en cache sont conservés uniquement en mémoire en mode incognito), utilisez plutôt les méthodes de mise en cache de votre suite de test.

Ne pas définir les variables d'environnement requises

Si vous expérimentez avec les exemples dans le dépôt 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 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 parvenez pas à résoudre votre problème, veuillez nous envoyer un email afin que nous puissions vous aider.