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, debe pasar una instancia de un Puppeteer Frame o Page. Este es el objetivo del análisis. 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 usted. En lugar de pasarle una página precargada, le pasa un objeto Browser y una URL. Cierra automáticamente la página después de que se llame a analyze. 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 analyze() existente no se altera.

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

Alcance

Existen dos opciones para delimitar sus análisis de Axe DevTools: include y exclude. Delimitan los análisis a los selectores CSS especificados y pueden encadenarse juntos. Ambos utilizan selectores CSS simples o arreglos de selectores CSS, por lo que puede personalizar completamente su análisis.

incluir

.include(selector: string | string[])

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

El ejemplo a continuación muestra que el alcance se limita a elementos dentro de la clase results-panel:

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

excluir

.exclude(selector: string | string[])

El método en cadena exclude elimina los elementos seleccionados por un selector CSS o un arreglo de selectores CSS de la página a analizar. Al igual que el método include, se pueden pasar selectores individuales o un arreglo de selectores. Este método también puede encadenarse con el método include.

La llamada de ejemplo a continuación muestra el alcance excluyendo elementos h2 con la clase 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, visite el 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 análisis a las reglas asociadas con la etiqueta o etiquetas especificadas. Se puede encontrar una lista completa de etiquetas de conjuntos de reglas dentro del 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 arreglo de reglas de la lista actual de reglas a utilizar. Las reglas se especifican por su ID de regla. Las llamadas subsecuentes a este método anularán las llamadas previas. Una lista completa de IDs de regla y sus descripciones se puede encontrar en el 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. Consulte el 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 previas llamando a axe.configure() y reemplazando el objeto de configuración. Consulte 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

De forma predeterminada, el servicio de uso está habilitado y la URL predeterminada es https://usage.deque.com. Establezca la variable de entorno AXE_TRACK_USAGE en false para desactivarlo.

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 o no datos al servicio de uso. El envío está habilitado de forma predeterminada.

.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 a dónde 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 método setDistinctId con el método analyse y registra el objeto de resultados en la consola:

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