Referencia de APIs de Puppeteer para axe DevTools for Web

Constructores

Hay 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 dos propiedades siguientes:

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

Para utilizar una versión específica de axe-core (que no sea la que se incluye como estándar con su versión de axe DevTools for Web), puede pasar un archivo fuente de axe-core como argumento. Primero, cree un objeto de origen axe leyendo el archivo axe-core del sistema de archivos. Luego, pase su instancia de axe DevTools al objeto de origen axe:

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

Si desea utilizar un conjunto de reglas predefinido distinto del estándar, puede pasar el rulesetID a su instancia de axe DevTools:

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

Un constructor alternativo puede abrir una página y realizar la omisión de CSP por usted. En lugar de pasarle una página precargada, le pasa un Browser objeto y una URL. Cierra automáticamente la página después de llamar a analyze . Además, realiza automáticamente la omisión de CSP. Este es su constructor:

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

Este constructor incluye las mismas opciones para fuentes o conjuntos de reglas de axe-core alternativos, y estos argumentos se pasan de la misma manera que arriba. Aquí hay un archivo de muestra 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. Tenga en cuenta que no se enlaza porque su funcionamiento es asincrónico.

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

Delimitación

Existen dos opciones para delimitar el alcance de los escaneos de axe DevTools: include y exclude. Definen el alcance de los escaneos a los selectores CSS especificados y se pueden encadenar entre sí. Ambos utilizan selectores CSS individuales o conjuntos de selectores CSS, por lo que puede personalizar completamente su escaneo.

incluir

.include(selector: string | string[])

Con el include método de cadena, solo se escanearán los elementos seleccionados por el selector CSS o el arreglo de selectores CSS. Esto es útil para comprobar instancias individuales 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 results-panel la clase:

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

excluir

.exclude(selector: string | string[])

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

El ejemplo de llamada a continuación muestra el alcance excluyendo h2 los elementos con results-panel la clase:

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

Configuración de reglas

withRules

.withRules(rules: string | string[])

Este método limita el análisis al ID de regla o ID de regla especificados. Para obtener una lista completa de las 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. Puede encontrar una lista completa de etiquetas de conjuntos de reglas en la documentación de axe-core.

El siguiente ejemplo prueba únicamente las reglas WCAG 2.0 Nivel A:

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

Desactivar reglas

.disableRules(rules: string | string[])

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

El siguiente ejemplo deshabilita la verificación del 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, se modifica el conjunto de reglas para utilizar 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 las opciones que utilizará axe.run. Anulará cualquier otra opción configurada, incluidas las llamadas a withRules y withTags. Consulte la documentación de la API de axe-core para obtener información.

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

configurar

.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 posteriores a este método invalidarán las anteriores llamando a axe.configure() y reemplazando el objeto de configuración. Consulte la documentación de la API de axe-core para conocer la estructura del objeto.

El siguiente ejemplo crea una nueva configuración de axe-core y la pasa a axe DevTools para que se use para escanear:

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á deshabilitado y la URL predeterminada es https://usage.deque.com.

Variables de entorno

Este método permite a los usuarios cambiar valores específicos del servicio de uso a través de variables de entorno.

Habilitar seguimiento

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 dónde se envían los datos de las 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 distinct id que se almacena o utiliza.

.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)
  })