Écrire des tests avec Axe DevTools Cypress

Produire des résultats de scans d'accessibilité avec Axe DevTools peut être aussi simple qu'une ligne de code. Ces résultats peuvent être consommés bruts, utilisés avec une bibliothèque d'assertions, ou utilisés pour créer des rapports d'accessibilité.

Prérequis

Pour tester les pages avec Axe DevTools, vous devez d'abord l'avoir installé dans votre projet. Si vous n'avez pas encore effectué cette étape, consultez le guide d'installation.

Structure du projet

.
├── package.json
├── cypress.config.js
├── cypress
│   ├── e2e
│   │   └── test.cy.js
│   └── support
│       └── e2e.js
└── results
    └── broken-workshop.json

Cypress 10.0 a remplacé le fichier de configuration cypress.json par cypress.config.js (ou cypress.config.ts), a renommé le répertoire de spécifications cypress/integration en cypress/e2e, a renommé cypress/support/index.js en cypress/support/e2e.js, et a supprimé le répertoire cypress/plugins au profit de la fonction setupNodeEvents dans le fichier de configuration. Les fichiers de spécifications utilisent le suffixe .cy.js au lieu de .spec.js.

Le répertoire results contient les résultats d'analyse JSON écrits par vos tests. Cypress le crée lors de la première écriture, vous n'avez donc pas besoin de l'ajouter vous-même.

Configuration

Les éléments suivants sont requis pour utiliser Axe DevTools Cypress.

Incluez la ligne suivante dans cypress/support/e2e.js :

import '@axe-devtools/cypress';

Dans le fichier cypress.config.js, vous devrez ajouter ce qui suit :

const { defineConfig } = require('cypress');
const axeDevtoolsCypressPlugin = require("@axe-devtools/cypress/dist/plugin");

module.exports = defineConfig({
   e2e: {
     setupNodeEvents(on, config) {
       axeDevtoolsCypressPlugin(on);
       return config;
     }
   }
 });

Fichier exemple complet

Appelez cy.axeAnalyze() et cy.getAxeResults() à l'intérieur de chaque bloc it(), et utilisez un nom de fichier unique pour chaque test afin d'éviter d'écraser les résultats d'autres tests.

Ajoutez ce code au fichier test.cy.js dans le répertoire e2e :

describe('Axe DevTools Cypress', () => {
  it('Scans the home page for accessibility issues', () => {
    // Visit the page to test
    cy.visit('https://broken-workshop.dequelabs.com')
    // Run an accessibility scan on the current page
    cy.axeAnalyze()
    // Write results to a uniquely named file; use a different name for each test to avoid overwriting
    cy.getAxeResults().then(results => {
      cy.writeFile('./results/broken-workshop.json', results)
    })
  })
})

Exécuter vos tests

Ajoutez des scripts à votre package.json pour pouvoir exécuter la suite sans interface en CI ou ouvrir l'application Cypress pendant que vous écrivez des tests :

{
  "scripts": {
    "test": "cypress run",
    "test:open": "cypress open"
  }
}

Exécutez toutes les spécifications dans cypress/e2e sans interface avec npm test, ou ouvrez l'application interactive Cypress avec npm run test:open. Pour exécuter une seule spécification, passez le paramètre --spec : npx cypress run --spec cypress/e2e/test.cy.js.

Ifra mes multi-origines et dans un bac à sable

cy.axeAnalyze() injecte axe-core dans la page sous test et dans chaque iframe qu'il peut atteindre. Les iframes dans lesquelles Cypress ne peut pas injecter, y compris les iframes multi-origines et celles portant un attribut sandbox, sont ignorées : l'analyse continue et rapporte les résultats pour le reste de la page plutôt que d'échouer le test. Le contenu à l'intérieur d'une iframe ignorée n'est pas analysé, donc testez ces pages directement dans leurs propres spécifications si vous avez besoin d'une couverture.