Escrever Testes com o Axe DevTools Cypress

Produzir resultados de verificações de acessibilidade com o Axe DevTools pode ser tão fácil quanto uma linha de código. Esses resultados podem ser consumidos em bruto, usados em conjunto com uma biblioteca de asserção ou utilizados para criar relatórios de acessibilidade.

Pré-requisitos

Para testar páginas com o Axe DevTools, você primeiro precisa tê-lo instalado em seu projeto. Se ainda não completou essa etapa, veja guia de instalação.

Estrutura do Projeto

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

O Cypress 10.0 substituiu o arquivo de configuração cypress.json por cypress.config.js (ou cypress.config.ts), renomeou o diretório de especificações cypress/integration para cypress/e2e, renomeou cypress/support/index.js para cypress/support/e2e.js, e removeu o diretório cypress/plugins em favor da função setupNodeEvents no arquivo de configuração. Arquivos de especificação usam o sufixo .cy.js ao invés de .spec.js.

O diretório results armazena os resultados de varredura JSON gravados pelos seus testes. O Cypress o cria na primeira escrita, então você não precisa adicioná-lo.

Configuração

O seguinte é necessário para usar o Axe DevTools Cypress.

Inclua a seguinte linha em cypress/support/e2e.js:

import '@axe-devtools/cypress';

Dentro do arquivo cypress.config.js, você precisará adicionar o seguinte:

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

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

Arquivo de Exemplo Completo

Chame cy.axeAnalyze() e cy.getAxeResults() dentro de cada bloco it() e use um nome de arquivo único para cada teste, para evitar sobrescrever os resultados de outros testes.

Adicione este código ao arquivo test.cy.js no diretório 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)
    })
  })
})

Execute Seus Testes

Adicione scripts ao seu package.json para que você possa executar o conjunto de forma autônoma no CI ou abrir o aplicativo Cypress enquanto você escreve testes:

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

Execute todas as especificações em cypress/e2e de forma autônoma com npm test, ou abra o aplicativo Cypress interativo com npm run test:open. Para executar uma única especificação, passe o parâmetro --spec: npx cypress run --spec cypress/e2e/test.cy.js.

Iframe de Origem Cruzada e em Sandbox

cy.axeAnalyze() injeta axe-core na página em teste e em cada iframe que consegue alcançar. Iframes em que o Cypress não consegue injetar, incluindo iframes de origem cruzada e iframes com um atributo sandbox, são ignorados: a varredura continua e relata resultados para o restante da página ao invés de falhar o teste. O conteúdo dentro de um iframe ignorado não é analisado, então teste essas páginas diretamente em suas próprias especificações caso precise de cobertura delas.