Referência da API Puppeteer para Axe DevTools para Web

Construtores

Existem dois construtores para Axe DevTools Puppeteer. Este é o construtor padrão:

AxeDevToolsPuppeteer(page: Frame | Page, options?: IOptions)

Para o primeiro argumento, você deve passar uma instância de um Puppeteer Frame ou Page. Este é o alvo da verificação. O segundo argumento é um objeto opcional que pode conter uma das duas propriedades a seguir:

1. axeSource (opcional): uma string de código-fonte do axe-core
2. rulesetID (opcional): um ID de conjunto de regras padrão

Para usar uma versão específica do axe-core (diferente daquela incluída como padrão na sua versão do Axe DevTools para Web), você pode passar um arquivo fonte do axe-core como argumento. Primeiro, crie um objeto fonte do axe lendo o arquivo axe-core do sistema de arquivos. Em seguida, passe sua instância do Axe DevTools para o objeto fonte do axe:

const axeSource = fs.readFileSync('./axe-3.0.js', 'utf8');
const builder = new AxeDevToolsPuppeteer(page, { axeSource });

Se desejar usar um conjunto de regras predefinido além do padrão, você pode passar o rulesetID para sua instância do Axe DevTools:

const builder = new AxeDevToolsPuppeteer(page, { rulesetID: 'wcag2' });

Um construtor alternativo pode abrir uma página e executar o bypass CSP para você. Em vez de passar uma página pré-carregada, você passa um objeto Browser e uma URL. Ele fecha automaticamente a página após analyze ser chamado. Além disso, ele executa automaticamente o bypass CSP. Este é o seu construtor:

loadPage(browser: Browser, url: string, options?: IOptions)

Este construtor inclui as mesmas opções para fontes alternativas do axe-core ou conjuntos de regras, e esses argumentos são passados da mesma forma que acima. Aqui está um arquivo de exemplo usando o construtor alternativo, que registra os resultados da varredura no console:

const puppeteer = require('puppeteer');
const { AxeDevToolsPuppeteer } = require('@axe-devtools/puppeteer');

(async () => {
    //launch puppeteer web driver
    const browser = await puppeteer.launch();
    const page = await browser.newPage();

    //launch page for testing
    await page.goto('https://broken-workshop.dequelabs.com');

    //analyze page
    const results = await new AxeDevToolsPuppeteer(page).analyze();
    //log results to console
    console.log(results);

    //close browser
    browser.close();
})();

analyze

.analyze([callback: (Error | null[, Object]) => void])

Este método realiza uma análise e passa qualquer erro encontrado e/ou o objeto de resultado para a função de callback ou função de promessa fornecida. Esteja ciente de que ele não encadeia, pois sua operação é assíncrona.

O exemplo a seguir usa a promessa retornada e registra o objeto de resultados no console:

new AxeDevToolsPuppeteer(page)
  .analyze()
  .then(function(results) {
    console.log(results);
  })
  .catch(err => {
    // Handle error somehow
  });

Este exemplo mostra o método analyse() com uma função de callback:

new AxeDevToolsPuppeteer(page).analyze(function(err, results) {
  if (err) {
    // Handle error somehow
  }
  console.log(results);
});

analyzeUniversal

.analyzeUniversal(): Promise<UniversalExport>

Realiza uma análise e retorna os resultados no Formato Universal do Axe. O método analyze() existente permanece inalterado.

new AxeDevToolsPuppeteer(page)
  .analyzeUniversal()
  .then(function(results) {
    console.log(results);
  })
  .catch(err => {
    // Handle error somehow
  });

Escopo

Existem duas opções para delimitar suas verificações Axe DevTools: include e exclude. Elas delimitam as verificações para os seletores CSS especificados e podem ser encadeadas. Ambas utilizam seletores CSS únicos ou arrays de seletores CSS, permitindo que você personalize completamente sua verificação.

include

.include(selector: string | string[])

Com o método de encadeamento include, apenas os elementos selecionados pelo seletor CSS ou pelo array de seletores CSS serão verificados. Isso é útil para verificar instâncias únicas de páginas componentizadas ou para limitar os resultados ao desenvolvimento atual.

O exemplo abaixo mostra que o escopo está limitado aos elementos dentro da classe results-panel:

new AxeDevToolsPuppeteer(page).include('.results-panel');

exclude

.exclude(selector: string | string[])

O método de encadeamento exclude remove elementos selecionados por um seletor CSS ou um array de seletores CSS da página que será verificada. Como o método include, seletores únicos ou um array de seletores pode ser passado. Este método também pode ser encadeado com o método include.

A chamada de exemplo abaixo mostra o escopo excluindo elementos h2 com a classe results-panel:

new AxeDevToolsPuppeteer(page).include('.results-panel h2');

Configuração de Regras

withRules

.withRules(rules: string | string[])

Este método limita a análise ao ID de regra especificado ou aos IDs de regra especificados. Para uma lista completa de regras e suas descrições, visite o documentação de regras do axe-core.

No exemplo a seguir, apenas as regras html-lang e image-alt serão testadas:

new AxeDevToolsPuppeteer(page).withRules(['html-lang', 'image-alt']);

comTags

.withTags(tags: string | string[])

O método withTags limita a verificação às regras associadas à etiqueta ou etiquetas especificadas. Uma lista completa de etiquetas de conjuntos de regras pode ser encontrada no documentação do axe-core.

O exemplo a seguir testa apenas para as regras do Nível A da WCAG 2.0:

new AxeDevToolsPuppeteer(page).withTags('wcag2a');

desativarRegras

.disableRules(rules: string | string[])

Este método remove uma regra específica ou um array de regras da lista atual de regras a serem usadas. As regras são especificadas pelo seu ID de regra. Chamadas subsequentes a este método substituirão as chamadas anteriores. Uma lista completa de IDs de regras e suas descrições pode ser encontrada no documentação de regras do axe-core.

O exemplo a seguir desativa a verificação de contraste de cores.

new AxeDevToolsPuppeteer(page).disableRules('color-contrast');

Além disso, disableRules pode ser encadeado com outros métodos de configuração de regras para modificar conjuntos de regras configurados pelo usuário.

No exemplo a seguir, o conjunto de regras é modificado para usar apenas as regras WCAG 2.0 A e AA, e então remove a regra de verificação de contraste de cores:

new AxeDevToolsPuppeteer(page)
  .withTags(['wcag2a', 'wcag2aa'])
  .disableRules('color-contrast');

opções do axe-core

opções

.options(options: Axe.RunOptions)

O método options especifica as opções a serem usadas pelo axe.run. Ele substituirá quaisquer outras opções configuradas, incluindo chamadas para withRules e withTags. Veja o documentação da API axe-core para informações.

new AxeDevToolsPuppeteer(page).options({
  checks: { 'valid-lang': ['orcish'] }
});

configurar

.configure(config: Axe.Spec)

O método configure injeta um objeto de configuração do axe para modificar o conjunto de regras antes de uma análise. Chamadas subsequentes a este método invalidarão as anteriores ao chamar axe.configure() e substituir o objeto de configuração. Veja documentação da API axe-core para a estrutura do objeto.

O exemplo a seguir cria uma nova configuração axe-core e a passa para o Axe DevTools para ser usada na verificação:

const config = {
  checks: [Object],
  rules: [Object]
};
const results = await new AxeDevToolsPuppeteer(page).configure(config).analyze();

Serviço de Uso

Por padrão, o serviço de uso está desativado, e a URL padrão é https://usage.deque.com.

Variáveis de Ambiente

Essas variáveis de ambiente permitem configurar o serviço de uso e alterar as propriedades dos eventos reportados.

ativarRastreamento

O método enableTracking() permite que os usuários optem por enviar dados ao serviço de uso.

.enableTracking(state: boolean)

Este exemplo mostra o método enableTracking emparelhado com o método analyze, que registra o objeto results no console:

new AxeDevToolsPuppeteer(page)
  .enableTracking(true)
  .analyze()
  .then(function(results) {
    console.log(results)
  })

definirUrlDeRastreamento

O método setTrackingUrl() permite que os usuários mudem o destino para onde os dados de métricas de uso são enviados.

.setTrackingUrl(url: string)

Este exemplo mostra o método setTrackingUrl() com o método analyze() e registra o objeto results no console:

new AxeDevToolsPuppeteer(page)
  .enableTracking(true)
  .setTrackingUrl('https://foobar.biz')
  .analyze()
  .then(function(results) {
    console.log(results)
  })

definirIdDistinto

Este método permite que os usuários mudem o id distinto que está sendo armazenado ou usado.

.setDistinctId(distinctId: string)

Este exemplo mostra o método setDistinctId com o método analyse e registra o objeto de resultados no console:

new AxeDevToolsPuppeteer(page)
  .enableTracking(true)
  .setDistinctId('foobar')
  .analyze()
  .then(function(results) {
    console.log(results)
  })