Referencia de la API de Puppeteer para Axe DevTools para Web

Constructores

Existen dos constructores para Axe DevTools Puppeteer. Este es el constructor estándar:

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

Para el primer argumento, debes pasar una instancia de un Puppeteer Frame o Page. Este es el objetivo del escaneo. El segundo argumento es un objeto opcional que puede contener una de las siguientes dos propiedades:

1. axeSource (opcional): una cadena de código fuente de axe-core
2. rulesetID (opcional): un ID de conjunto de reglas predeterminado

Para usar una versión específica de axe-core (distinta de la que se incluye de forma estándar con tu versión de Axe DevTools para Web), puedes pasar un archivo fuente de axe-core como argumento. Primero, crea un objeto de fuente de axe leyendo el archivo de axe-core desde el sistema de archivos. Luego, pasa tu instancia de Axe DevTools al objeto de fuente de axe:

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

Si deseas usar un conjunto de reglas predefinido distinto del estándar, puedes pasar el rulesetID a tu instancia de Axe DevTools:

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

Un constructor alternativo puede abrir una página y realizar el bypass de CSP por ti. En lugar de pasarle una página precargada, le pasas un Browser objeto y URL. Automáticamente cierra la página después de que analyze es llamado. Además, realiza automáticamente el bypass de CSP. Este es su constructor:

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

Este constructor incluye las mismas opciones para fuentes de axe-core alternativas o conjuntos de reglas, y estos argumentos se pasan de la misma manera que antes. Aquí hay un archivo de ejemplo que utiliza el constructor alternativo, que registra los resultados del escaneo en la consola:

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

analizar

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

Este método realiza un análisis y pasa cualquier error encontrado y/o el objeto de resultado a la función de devolución de llamada o promesa proporcionada. Ten en cuenta que no se encadena porque su operación es asincrónica.

El siguiente ejemplo utiliza la promesa devuelta y registra el objeto de resultados en la consola:

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

Este ejemplo muestra el método analyse() con una función de devolución de llamada:

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

analizarUniversal

.analyzeUniversal(): Promise<UniversalExport>

Realiza un análisis y devuelve resultados en el Formato Universal de Axe. El método existente analyze() no cambia.

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

Alcance

Existen dos opciones para establecer el alcance de tus escaneos de Axe DevTools: include y exclude. Ellos limitan los escaneos a los selectores CSS especificados y pueden encadenarse juntos. Ambos usan selectores CSS únicos o arrays de selectores CSS, por lo que puedes personalizar completamente tu escaneo.

incluir

.include(selector: string | string[])

Con el método de encadenamiento include , solo se escanearán los elementos seleccionados por el selector CSS o array de selectores CSS. Esto es útil para verificar instancias únicas de páginas componentizadas o limitar los resultados al desarrollo actual.

El siguiente ejemplo muestra que el alcance está limitado a los elementos dentro de la clase results-panel :

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

excluir

.exclude(selector: string | string[])

El método de encadenamiento exclude elimina los elementos seleccionados por un selector CSS o un array de selectores CSS de la página a escanear. Al igual que el método include , se pueden pasar selectores únicos o un array de selectores. Este método también puede encadenarse con el método include .

La llamada de ejemplo a continuación muestra que el alcance excluye elementos con la clase h2 : results-panel

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

Configuración de Reglas

conReglas

.withRules(rules: string | string[])

Este método limita el análisis al ID de regla o IDs de regla especificados. Para obtener una lista completa de reglas y sus descripciones, visita la documentación de reglas de axe-core.

En el siguiente ejemplo, solo se probarán las reglas html-lang y image-alt :

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

withTags

.withTags(tags: string | string[])

El método withTags limita el escaneo a las reglas asociadas con la etiqueta o etiquetas especificadas. Se puede encontrar una lista completa de etiquetas del conjunto de reglas en la documentación de axe-core.

El siguiente ejemplo prueba solo las reglas de WCAG 2.0 Nivel A:

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

disableRules

.disableRules(rules: string | string[])

Este método elimina una regla específica o un conjunto de reglas de la lista actual de reglas a utilizar. Las reglas se especifican por su ID de regla. Las llamadas posteriores a este método anularán las llamadas anteriores. Se puede encontrar una lista completa de IDs de reglas y sus descripciones en la documentación de reglas de axe-core.

El siguiente ejemplo desactiva la verificación de contraste de color.

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

Además, disableRules se puede encadenar con otros métodos de configuración de reglas para modificar conjuntos de reglas configurados por el usuario.

En el siguiente ejemplo, el conjunto de reglas se modifica para usar solo las reglas WCAG 2.0 A y AA, luego se elimina la regla de verificación de contraste de color:

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

opciones de axe-core

opciones

.options(options: Axe.RunOptions)

El método options especifica opciones a usar por axe.run. Anulará cualquier otra opción configurada, incluidas las llamadas a withRules y withTags. Vea la documentación de la API de axe-core para obtener información.

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

configure

.configure(config: Axe.Spec)

El método configure inyecta un objeto de configuración de axe para modificar el conjunto de reglas antes de un análisis. Las llamadas subsecuentes a este método invalidarán las anteriores llamando a axe.configure() y reemplazando el objeto de configuración. Vea la documentación de la API de axe-core para la estructura del objeto.

El siguiente ejemplo crea una nueva configuración de axe-core y la pasa a Axe DevTools para ser utilizada en el escaneo:

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

Servicio de Uso

Por defecto, el servicio de uso está deshabilitado, y la URL predeterminada es https://usage.deque.com.

Variables de Entorno

Estas variables de entorno le permiten configurar el servicio de uso y cambiar las propiedades de los eventos reportados.

enableTracking

El método enableTracking() permite a los usuarios optar por enviar datos al servicio de uso.

.enableTracking(state: boolean)

Este ejemplo muestra el método enableTracking emparejado con el método analyze , que registra el objeto results en la consola:

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

setTrackingUrl

El método setTrackingUrl() permite a los usuarios cambiar el lugar donde se envían los datos de métricas de uso.

.setTrackingUrl(url: string)

Este ejemplo muestra el método setTrackingUrl() con el método analyze() y registra el objeto results en la consola:

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

setDistinctId

Este método permite a los usuarios cambiar el id distinto que se está almacenando o utilizando.

.setDistinctId(distinctId: string)

Este ejemplo muestra el setDistinctId método con el analyse método y registra el objeto de resultados en la consola:

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