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

Installation

Les éléments suivants sont nécessaires pour utiliser Axe DevTools Cypress. L'installation est montrée en JavaScript et en TypeScript. Cypress lit l'une ou l'autre extension, donc un projet TypeScript utilise des fichiers spec cypress.config.ts, cypress/support/e2e.ts, et .cy.ts à la place de leurs homologues .js.

JavaScript

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;
     }
   }
 });

TypeScript

Ajoutez un tsconfig.json à côté de vos specs pour que TypeScript reconnaisse les types de Cypress et Node :

{
  "compilerOptions": {
    "target": "es5",
    "lib": ["es5", "dom"],
    "types": ["cypress", "node"]
  },
  "include": ["**/*.ts"]
}

Incluez la ligne suivante dans cypress/support/e2e.ts. L'import du package enregistre également les types pour cy.axeAnalyze(), cy.getAxeResults(), et les autres commandes Axe DevTools, donc @axe-devtools/cypress n'a pas besoin d'un package @types/ séparé :

import '@axe-devtools/cypress';

Dans le fichier cypress.config.ts, vous devrez ajouter ce qui suit. Le plugin est publié comme un point d'entrée CommonJS, donc chargez-le avec require même en TypeScript :

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

export default defineConfig({
   e2e: {
     setupNodeEvents(on, config) {
       axeDevtoolsCypressPlugin(on);
       return config;
     }
   }
 });

Fichier d'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.

JavaScript

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

TypeScript

Ajoutez ce code au fichier test.cy.ts dans le répertoire e2e. Les types de commande que le package enregistre donnent à results le type AxeDevToolsResults | null, donc restreignez-le avant de le passer à cy.writeFile(), qui n'accepte pas null :

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 => {
      if (!results) {
        throw new Error('cy.getAxeResults() returned no results')
      }
      cy.writeFile('./results/broken-workshop.json', results)
    })
  })
})

Un projet TypeScript prêt à l'emploi est disponible dans le dépôt d'exemples de l'API Axe DevTools.

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.