Escribe pruebas con Axe DevTools Cypress

Producir resultados de escaneo de accesibilidad con Axe DevTools puede ser tan sencillo como una línea de código. Estos resultados pueden ser consumidos en bruto, utilizados junto con una biblioteca de aserciones, o empleados para crear informes de accesibilidad.

Requisitos previos

Para probar páginas con Axe DevTools, primero necesitas tenerlo instalado en tu proyecto. Si aún no has completado este paso, consulta la guía de instalación.

Estructura del proyecto

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

Cypress 10.0 reemplazó el archivo de configuración cypress.json con cypress.config.js (o cypress.config.ts), renombró el directorio de especificaciones cypress/integration a cypress/e2e, renombró cypress/support/index.js a cypress/support/e2e.js, y eliminó el directorio cypress/plugins a favor de la función setupNodeEvents en el archivo de configuración. Los archivos de especificaciones usan el sufijo .cy.js en lugar de .spec.js.

El directorio results contiene los resultados de escaneo JSON escritos por tus pruebas. Cypress lo crea en la primera escritura, así que no necesitas añadirlo tú mismo.

Configuración

Se requiere lo siguiente para usar Axe DevTools Cypress. La configuración se muestra en JavaScript y en TypeScript. Cypress lee cualquiera de las extensiones, por lo que un proyecto TypeScript utiliza archivos espec cypress.config.ts, cypress/support/e2e.ts y .cy.ts en lugar de sus contrapartes .js.

JavaScript

Incluye la siguiente línea en cypress/support/e2e.js:

import '@axe-devtools/cypress';

Dentro del archivo cypress.config.js, necesitarás añadir lo siguiente:

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

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

TypeScript

Agregue un tsconfig.json junto a sus especificaciones para que TypeScript reconozca los tipos de Cypress y Node:

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

Incluya la siguiente línea en cypress/support/e2e.ts. Importar el paquete también registra los tipos para cy.axeAnalyze(), cy.getAxeResults() y los demás comandos de Axe DevTools, por lo que @axe-devtools/cypress no necesita un paquete @types/ separado:

import '@axe-devtools/cypress';

Dentro del archivo cypress.config.ts, deberá agregar lo siguiente. El plugin se publica como un punto de entrada CommonJS, así que cárguelo con require incluso 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;
     }
   }
 });

Archivo de Muestra Completo

Llama a cy.axeAnalyze() y cy.getAxeResults() dentro de cada bloque it() y usa un nombre de archivo único para cada prueba para evitar sobrescribir los resultados de otras pruebas.

JavaScript

Agrega este código al archivo test.cy.js en el directorio 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

Agregue este código al archivo test.cy.ts en el directorio e2e. Los tipos de comandos que registra el paquete le dan a results el tipo AxeDevToolsResults | null, por lo que debe acotarlo antes de pasarlo a cy.writeFile(), que no acepta 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 proyecto TypeScript listo para ejecutarse está disponible en el Repositorio de ejemplos de API de Axe DevTools.

Ejecutar Tus Pruebas

Agrega scripts a tu package.json para que puedas ejecutar el conjunto en modo sin cabeza en CI o abrir la aplicación Cypress mientras escribes pruebas:

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

Ejecuta todas las especificaciones en cypress/e2e en modo sin cabeza con npm test, o abre la aplicación interactiva de Cypress con npm run test:open. Para ejecutar una única especificación, pasa la bandera --spec: npx cypress run --spec cypress/e2e/test.cy.js.

Iframes de Origen Cruzado y en Caja de Arena

cy.axeAnalyze() inyecta axe-core en la página bajo prueba y en cada iframe al que pueda acceder. Los iframes a los que Cypress no puede inyectar, incluidos los iframes de origen cruzado y los iframes con el atributo sandbox, se omiten: el escaneo continúa e informa resultados para el resto de la página en lugar de fallar la prueba. El contenido dentro de un iframe omitido no se analiza, así que prueba esas páginas directamente en sus propias especificaciones si necesitas cobertura de ellas.