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 Frame ou Page. Este é o alvo da varredura. O segundo argumento é um objeto opcional que pode conter uma das seguintes duas propriedades:

1. axeSource (opcional): uma string de código-fonte 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 realizar o bypass CSP por você. Em vez de passar uma página pré-carregada, você passa um Browser objeto e URL. Ele fecha a página automaticamente 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 resultados no Formato Universal do Axe. O método existente analyze() permanece inalterado.

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

Escopo

Existem duas opções para limitar o escopo das suas varreduras Axe DevTools: include e exclude. Elas limitam as varreduras aos seletores CSS especificados e podem ser encadeadas juntas. Ambas usam seletores CSS únicos ou arrays de seletores CSS, de modo que você pode personalizar completamente sua varredura.

include

.include(selector: string | string[])

Com o método de encadeamento include , apenas elementos selecionados pelo seletor CSS ou array de seletores CSS serão escaneados. Isso é útil para verificar instâncias únicas de páginas com componentes 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 a ser escaneada. Assim como o método include , seletores únicos ou um array de seletores podem ser passados. 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 IDs de regra. Para uma lista completa de regras e suas descrições, visite a 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 withTags método limita a verificação às regras associadas à ou às tags especificadas. Uma lista completa das tags de conjunto de regras pode ser encontrada na 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 utilizadas. 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 na 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 configuradas 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 options método especifica opções a serem usadas pelo axe.run. Isso substituirá quaisquer outras opções configuradas, incluindo chamadas para withRules e withTags. Veja a documentação da API axe-core para mais informações.

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

configurar

.configure(config: Axe.Spec)

O configure método 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 a 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 enableTracking() método permite que os usuários optem por enviar dados para o serviço de uso.

.enableTracking(state: boolean)

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

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

definirUrlDeRastreamento

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

.setTrackingUrl(url: string)

Este exemplo mostra o setTrackingUrl() método com o analyze() método 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 setDistinctId método com o analyse método e registra o objeto de resultados no console:

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