Referencia de la API de JavaScript del Navegador para Axe DevTools para Web

Introducción

La API de Axe DevTools está diseñada para ser una mejora sobre la generación anterior de APIs de accesibilidad. Ofrece los siguientes beneficios:

• Funciona en cualquier navegador moderno
• Diseñada para trabajar con la infraestructura de pruebas existente
• Funciona localmente; no es necesaria una conexión a un servidor de terceros
• Realiza la verificación de violaciones en múltiples niveles de iframes anidados
• Proporciona una lista de reglas y elementos que pasaron la verificación de accesibilidad, asegurando que las reglas se han ejecutado en todo el documento

Comenzando

Esta sección describe brevemente cómo usar las APIs de Axe DevTools para analizar el contenido de páginas web y devolver un objeto JSON que lista cualquier violación de accesibilidad encontrada.

La API de Axe DevTools se puede utilizar como parte de un proceso más amplio que se realiza en muchas, si no todas, las páginas de un sitio web. La API analiza el contenido de las páginas web y devuelve un objeto JSON que lista cualquier violación de accesibilidad encontrada. Aquí está cómo empezar:

1. Cargar la página en el sistema de pruebas
2. Opcionalmente, configurar las opciones de la API de JavaScript (AxeDevTools.configure)
3. Llamar a la API de JavaScript para análisis (AxeDevTools.run)
4. Ya sea asegurar los resultados o guardarlos para procesarlos más tarde

Referencia de la API

Visión general

Las APIs de Axe DevTools se proporcionan en el archivo JavaScript axe-devtools.js. Debe incluirse en la página web bajo prueba. Los parámetros se envían como parámetros de función de JavaScript. Los resultados se devuelven en formato JSON.

Notas de la API

• Una prueba de regla se compone de sub-pruebas. Cada sub-prueba se devuelve en un array de 'verificaciones'
• El "helpUrl" en el objeto de resultados enlaza con una descripción más amplia del problema de accesibilidad y la remediación sugerida. Todos los enlaces apuntan a las páginas de ayuda de Deque University.

AxeDevTools.init

Propósito

Inicializa la API de Axe DevTools para utilizar uno de los conjuntos de reglas estándar integrados.

Descripción

Inicializa el motor de Axe DevTools, reemplazando el conjunto de reglas predeterminado y habilitando uno de los subconjuntos de reglas estándar.

Sinopsis

AxeDevTools.init(ruleSetID);

Parámetros

• ruleSetID - opcional Cadena que identifica el conjunto de reglas. Los valores válidos actuales son:

  • 508
  • en301549
  • rgaav4
  • ttv5
  • wcag2
  • wcag21
  • wcag22
  • wcag2aaa
  • wcag21aaa
  • wcag22aaa

Devuelve: indefinido

AxeDevTools.ruleSets

Propósito

Un array de las definiciones de conjuntos de reglas estándar

Descripción

Proporciona acceso directo al array de definición de conjuntos de reglas estándar. El array consiste en objetos de JavaScript con la siguiente estructura:

{
  id: String identifier for the rule set,
  defn: Object containing the rule set definition
}

Ejemplo Uno

Cómo filtrar el arreglo para encontrar la definición del conjunto de reglas de WCAG 2 nivel A y AA.

var rsets = AxeDevTools.ruleSets;
var wcag2 = rsets.filter(function (item) {
  return item.id === 'wcag2';
})[0].defn;

AxeDevTools.getRules

Propósito

Obtener información sobre todas las reglas en el sistema

Descripción

Devuelve una lista de todas las reglas con su ID y descripción.

Sinopsis

AxeDevTools.getRules([Tag Name 1, Tag Name 2...]);

Parámetros

• tags - opcional Array de etiquetas usadas para filtrar las reglas devueltas. Si se omite, devolverá todas las reglas.

Devuelve: Array de reglas que coinciden con el filtro de entrada, donde cada entrada tiene un formato de {ruleId: <id>, description: <desc>}

El conjunto actual de etiquetas soportadas se enumera en la siguiente tabla:

Ejemplo 1

En este ejemplo, pasamos las etiquetas WCAG 2 A y AA en AxeDevTools.getRules para recuperar solo esas reglas. La llamada a la función devuelve un array de reglas.

Llamada: AxeDevTools.getRules(['wcag2aa', 'wcag2a']);

Datos Devueltos:

[
  { ruleId: "area-alt", description: "Checks the <area> elements of image…" },
  { ruleId: "aria-allowed-attr", description: "Checks all attributes that start…" },
  { ruleId: "aria-required-attr", description: "Checks all elements that contain…" },
  …
]

AxeDevTools.configure

Propósito

Configurar el formato de los datos utilizados por Axe DevTools. Esto se puede usar para agregar nuevas reglas, las cuales deben ser registradas con la biblioteca para ejecutarse.

Descripción

El usuario especifica el formato de la estructura JSON pasada al callback de AxeDevTools.run.

Sinopsis

AxeDevTools.configure({
  branding: {
    brand: String,
    application: String
  },
  reporter: 'option',
  checks: [Object],
  rules: [Object]
});

Parámetros

• configurationOptions - Objeto de opciones donde los pares nombre/valor válidos son:
  • branding - mixto (opcional) Usado para establecer la marca de la helpUrls.
    • brand - cadena (opcional) establece la cadena de la marca--predeterminado: "worldspace"
    • application - cadena (opcional) establece la cadena de la aplicación--predeterminado: "AxeDevToolsAPI"
  • reporter - Usado para establecer el formato de salida que la función AxeDevTools.run enviará a la función de devolución de llamada
    • v1 para usar el formato de la versión anterior: AxeDevTools.configure({ reporter: "v1" });
    • v2 para usar el formato de la versión actual: AxeDevTools.configure({ reporter: "v2" });
  • checks - Usado para añadir verificaciones a la lista de verificaciones usadas por reglas o para sobrescribir las propiedades de verificaciones existentes.
    • El atributo verificaciones es un arreglo de objetos de verificación.
    • Cada objeto de verificación puede contener los siguientes atributos:
    • id - cadena (requerido). Esto identifica de forma única la verificación. Si la verificación ya existe, cualquier propiedad de verificación proporcionada será sobrescrita. Las propiedades a continuación marcadas requerido si nuevo son opcionales cuando la verificación es sobrescrita.
    • evaluate - función (requerido si nuevo). Esta es la función que implementa la funcionalidad de la verificación.
    • after - función (opcional). Esta función se llama para verificaciones que operan a nivel de página para procesar los resultados de los iframes.
    • options - mixto (opcional). Este objeto options se pasa a la función evaluate y está destinado a ser usado para configurar verificaciones. Es la propiedad más común que se pretende sobrescribir para verificaciones existentes.
    • matches - cadena (opcional). Esta cadena de selector CSS filtrará los nodos pasados a la función evaluate.
    • enabled - booleano (opcional, predeterminado true). Esto indica si la verificación está encendida o apagada de forma predeterminada. Las verificaciones que están apagadas no son evaluadas, incluso cuando son incluidas en una regla. Sobrescribir esto es una forma común de desactivar una verificación en particular en varias reglas.
  • rules - Usado para agregar reglas al conjunto existente de reglas o sobrescribir las propiedades de reglas existentes. El atributo rules es un arreglo de objetos rule. Cada objeto rule puede contener los siguientes atributos:
    • id - cadena (requerido). Esto identifica de forma única la regla. Si la regla ya existe, será sobrescrita con cualquier atributo proporcionado. Los atributos a continuación que están marcados como requeridos solo son requeridos para nuevas reglas.
    • selector - cadena (opcional, predeterminado *). Un selector CSS usado para identificar los elementos pasados a la regla para evaluación.
    • excludeHidden - booleano (opcional, predeterminado true). Esto indica si los elementos ocultos deben ser pasados a la regla para evaluación.
    • enabled - booleano (opcional, predeterminado true). Si la regla está activada (un atributo común para sobrescribir).
    • pageLevel - booleano (opcional, predeterminado false). Esto indica si la página opera solo cuando el ámbito es toda la página. Un ejemplo de una regla como esta es la regla omitir enlace. No se recomienda sobrescribir esta propiedad a menos que la implementación también se cambie.
    • any - arreglo (opcional, predeterminado []). Esta es la lista de verificaciones que deben todas aprobarse o hay una violación.
    • all - arreglo (opcional, predeterminado []). Esta es la lista de verificaciones que, si alguna falla, generará una violación.
    • none - arreglo (opcional, predeterminado []). Esta es la lista de verificaciones que, si ninguna pasa, generará una violación.
    • tags - arreglo (opcional, predeterminado []). Una lista de las etiquetas que clasificar la regla. En la práctica, debe proporcionar algunas etiquetas válidas, o la evaluación predeterminada no invocará la regla. La convención es incluir el estándar (WCAG 2 y/o sección 508), el nivel de WCAG 2, el párrafo de la Sección 508 y los criterios de éxito de WCAG 2. Las etiquetas se construyen convirtiendo todas las letras a minúsculas, eliminando espacios y puntos, y concatenando el resultado. Por ejemplo, el criterio de éxito 1.1.1 de WCAG 2 A se convertiría en ["wcag2a", "wcag111"]
    • matches - cadena (opcional, predeterminado *). Un selector CSS que excluirá los elementos que no coincidan con él.

Retorna: Nada

AxeDevTools.reset

Propósito

Restablecer la configuración a la configuración predeterminada.

Descripción

Sobrescribir cualquier llamada previa a AxeDevTools.configure o AxeDevTools.reset y restablecer la configuración a la configuración predeterminada.

Sinopsis

AxeDevTools.reset();

Parámetros

Ninguno

Retorna: indefinido

AxeDevTools.run

Propósito

Analizar la página actualmente cargada.

Descripción

Ejecuta varias reglas contra la página HTML proporcionada y devuelve la lista de problemas resultantes.

Sinopsis

AxeDevTools.run(context, options, callback);

Parámetros para AxeDevTools.run

• context: (opcional) Define el alcance del análisis: la parte del DOM que desea analizar. Esto típicamente será el document o un selector específico como el nombre de clase, ID, selector, etc.
• options: (opcional) Conjunto de opciones pasadas a reglas o verificaciones, modificándolas temporalmente. Esto contrasta con AxeDevTools.configure, que es más permanente. Ver arriba para más información
• callback: (opcional) La función de devolución de llamada que recibe ya sea null o un resultado de error como el primer parámetro, y el objeto de resultados cuando el análisis se ha completado con éxito o undefined si no fue así.

Parámetro context

Por defecto, AxeDevTools.run analizará todo el documento. El objeto context es un parámetro opcional que especifica qué elemento debe y cuál no debe analizarse. Puede pasar uno de los siguientes:

1. Una referencia a un elemento que representa la porción del documento que debe ser analizada
   • Ejemplo: Para limitar el análisis al elemento <div id="content">: document.getElementById("content")
2. Una NodeList tal como la devuelta por document.querySelectorAll.
3. Un selector CSS que selecciona la porción del documento que debe ser analizada. Esto incluye:
   • Un selector CSS como nombre de clase (por ejemplo, .classname)
   • Un selector CSS como nombre de nodo (por ejemplo, div)
   • Un selector CSS de un ID de elemento (por ejemplo, #tag)
4. Un objeto de inclusión-exclusión (ver abajo)

Objetos include y exclude

El objeto de inclusión-exclusión es un objeto JSON con dos atributos: include y exclude. Se requiere al menos include o exclude. Si solo se especifica exclude, include por defecto abarcará todo el document.

• Un nodo, o
• Un arreglo de arreglos de selectores CSS

En la mayoría de los casos, los arreglos contendrán solo un selector CSS. Se requieren múltiples selectores CSS solo si desea incluir o excluir regiones de una página que estén dentro de iframes (o iframes dentro de iframes dentro de iframes). En este caso, los primeros n-1 selectores seleccionan el o los iframes, y el n-ésimo selector selecciona la región o regiones dentro del iframe.

Ejemplos de Parámetro context

1. Incluir el primer ítem en la NodeList $fixture pero excluir su primer hijo

   {
     include: $fixture[0],
     exclude: $fixture[0].firstChild
   }

2. Incluir el elemento con el ID de fix pero excluir cualquier div dentro de él

   {
     include: [['#fix']],
     exclude: [['#fix div']]
   }

3. Incluir todo el documento excepto cualquier estructura cuyo padre contenga la clase exclude1 o exclude2

   {
     exclude: [['.exclude1'], ['.exclude2']];
   }

Parámetro options

El parámetro options es una forma flexible de configurar cómo opera AxeDevTools.run. Los diferentes modos de operación son:

• Ejecutar todas las reglas correspondientes a uno de los estándares de accesibilidad.
• Ejecutar todas las reglas definidas en el sistema excepto por la lista de reglas especificadas.
• Ejecutar un conjunto específico de reglas provistas como una lista de IDs de reglas.

Ejemplos de Parámetro options

1. Ejecutar solo Reglas para un estándar de accesibilidad

   Hay ciertos estándares definidos que se pueden usar para seleccionar un conjunto de reglas. Los estándares definidos y la cadena de etiqueta se definen de la siguiente manera:

   Nombre de Etiqueta	Estándar de Accesibilidad
   wcag2a	WCAG 2.0 Nivel A
   wcag2aa	WCAG 2.0 Nivel AA
   wcag2aaa	WCAG 2.0 Nivel AAA
   wcag21a	WCAG 2.1 Nivel A
   wcag21aa	WCAG 2.1 Nivel AA
   wcag21aaa	WCAG 2.1 Nivel AAA
   wcag22a	WCAG 2.2 Nivel A
   wcag22aa	WCAG 2.2 Nivel AA
   wcag22aaa	WCAG 2.2 Nivel AAA
   section508	Sección 508
   EN-301-549	EN 301 549
   TTv5	Probador de Confianza v5
   mejores-prácticas	Mejores prácticas respaldadas por Deque

   Para ejecutar solo las reglas de WCAG 2.0 Nivel A, especifique options como:

   {
     runOnly: {
      type: "tag",
      values: ["wcag2a"]
     }
   }

   Para ejecutar tanto las reglas de WCAG 2.0 Nivel A como Nivel AA, debe especificar tanto wcag2a como wcag2aa:

   {
     runOnly: {
       type: "tag",
       values: ["wcag2a", "wcag2aa"]
     }
   }

2. Ejecutar solo una lista especificada de reglas

   Si solo desea ejecutar ciertas reglas, especifique las opciones como:

   {
     runOnly: {
       type: "rule",
       values: [ "ruleId1", "ruleId2", "ruleId3" ]
     }
   }

   Este ejemplo ejecutará solo las reglas con el id de ruleId1, ruleId2 y ruleId3. No se ejecutará ninguna otra regla.

3. Ejecutar todas las reglas habilitadas excepto una lista de reglas

   La operación predeterminada para AxeDevTools.run es ejecutar todas las reglas de WCAG 2.0 Nivel A y Nivel AA. Si ciertas reglas deben deshabilitarse para no ejecutarse, especifique options como:

   {
     "rules": {
       "color-contrast": { enabled: false },
       "valid-lang": { enabled: false }
     }
   }

   Este ejemplo deshabilitará las reglas con el ID color-contrast o valid-lang. Todas las demás reglas se ejecutarán. La lista de IDs de regla válidos se especifica en la sección a continuación.

4. Ejecutar un conjunto modificado de reglas usando etiquetas y activación de reglas

   Un conjunto modificado puede definirse combinando runOnly con type configurado a las etiquetas deseadas y usando la opción rules. Esto le permite incluir reglas con etiquetas no especificadas y excluir reglas con la etiqueta o etiquetas especificadas.

   {
     runOnly: {
       type: "tag",
       values: ["wcag2a"]
     },
     "rules": {
       "color-contrast": { enabled: true },
       "valid-lang": { enabled: false }
     }
   }

   Este ejemplo incluye todas las reglas del nivel A excepto valid-lang, y también incluirá la regla de contraste de color de nivel AA.

5. Ejecutar solo algunas etiquetas, pero excluir otras

   La opción runOnly puede aceptar un objeto con una propiedad include y exclude. Solo se ejecutarán las comprobaciones que coincidan con una etiqueta incluida, excepto aquellas que compartan una etiqueta de la lista de exclusión.

   {
     runOnly: {
       type: 'tags',
       value: {
         include: ['wcag2a', 'wcag2aa'],
         exclude: ['experimental']
       }
     }
   }

   Este ejemplo primero incluye todas las reglas wcag2a y wcag2aa. Todas las reglas etiquetadas como experimental son luego eliminadas de las reglas a ejecutar.

Parámetro callback

El parámetro callback es una función que se llamará cuando la función asincrónica AxeDevTools.run se complete. La función callback recibe dos parámetros. El primer parámetro será un error lanzado dentro de Axe DevTools si AxeDevTools.run no puede completarse. Si Axe DevTools se completó correctamente, el primer parámetro será nulo, y el segundo parámetro será el objeto de resultados.

Devolver Promesa

Si el callback no fue definido, Axe DevTools devolverá una promesa en su lugar. Sin embargo, Axe DevTools no incluye la biblioteca de promesas. Por lo tanto, en sistemas sin soporte para promesas, esta función no está disponible. Si no está seguro de si los sistemas en los que necesitará Axe DevTools tienen soporte de promesas, le sugerimos que use el callback proporcionado por AxeDevTools.run en su lugar.

Resultado error

Esto será bien null o un objeto que es una instancia de Error. Si consistentemente recibe errores, por favor reporte este problema a Deque Systems.

Objeto results

La función de callback pasada como el tercer parámetro de AxeDevTools.a11yCheck se ejecuta en el objeto results. Este objeto tiene dos componentes: un arreglo passes y un arreglo violations. El arreglo passes lleva un registro de todas las pruebas aprobadas y de la información detallada sobre cada prueba. Esto lleva a pruebas más eficientes, especialmente con pruebas manuales, ya que el usuario puede determinar fácilmente las pruebas ya aprobadas. De manera similar, el arreglo violations lleva un registro de todas las pruebas fallidas y de la información detallada sobre cada una.

url

La URL de la página que se probó.

timestamp

La fecha y hora en que se completó el análisis.

Arreglo passes y violations

• description - Una cadena de texto que describe lo que la regla hace
• help - Texto de ayuda que describe la prueba que se realizó
• helpUrl - Una URL que proporciona más información sobre los detalles de la violación. Enlaces a una página en el sitio de la Universidad Deque.
• id - Un identificador único para la regla; ver la lista de reglas
• impact - La gravedad de la violación. Puede ser uno de menor, moderada, grave, o crítica si la regla falló o null si la verificación pasó.
• tags - Un arreglo de etiquetas asignadas a esta regla. Las etiquetas pueden usarse en el objeto option para seleccionar qué reglas se ejecutan (vea Parámetro de Opciones arriba).
• nodes - Una matriz de todos los elementos que la regla probó
  • html - Un fragmento de HTML del elemento
  • impact - La gravedad de la infracción. Puede ser una de leve, moderado, grave o crítico si la prueba falló o null si la verificación fue exitosa.
  • target - Una matriz de selectores donde cada elemento corresponde a un nivel de iframe o frame. Si hay un iframe o frame, debe haber dos entradas en target. Si hay tres niveles de iframe, deben haber cuatro entradas en target.
  • any - Una matriz de verificaciones donde al menos una debe haber pasado. Cada entrada en la matriz contiene:
    • id - Identificador único para esta verificación. Los IDs de verificación pueden ser los mismos que los IDs de las reglas.
    • impact - La gravedad de la verificación. Puede ser una de leve, moderado, grave o crítico. Cada verificación que es parte de una regla puede tener diferentes impactos. El impacto más alto de todas las verificaciones que fallan se informa para la regla.
    • message - La descripción de por qué esta verificación pasó o falló.
    • data - Información adicional y opcional específica del tipo de verificación. Por ejemplo, una verificación de contraste de color incluiría el color de primer plano, el color de fondo, la relación de contraste, etc.
    • relatedNodes - Una matriz opcional de información sobre otros nodos relacionados con esta verificación. Por ejemplo, una infracción de verificación de ID duplicada enumeraría los otros selectores con el mismo ID duplicado. Cada entrada en la matriz contiene la siguiente información:
      • target - Una matriz de selectores para el nodo relacionado
      • html - El código fuente HTML del nodo relacionado
  • all - Una matriz de verificaciones realizadas donde todas deben haber pasado. Cada entrada en la matriz contiene la misma información que la matriz any.
  • none - Una matriz de verificaciones realizadas donde ninguna debe haber pasado. Cada entrada en la matriz contiene la misma información que la matriz any.

Ejemplo Dos

En este ejemplo, pasaremos el selector para todo el documento, sin pasar opciones, lo que significa que se ejecutarán todas las reglas habilitadas, y tendremos una función de devolución de llamada simple que registra el objeto completo de resultados en el registro de la consola:

AxeDevTools.run(document, function (err, results) {
  if (err) throw err;
  console.log(results);
});

matriz passes

• passes[0] ...

  • help - "Elements must have sufficient color contrast"
  • helpURL - "https://dequeuniversity.com/courses/html-css/visual-layout/color-contrast"
  • id - "color-contrast"
    • nodes
    • target[0] - "#js_off-canvas-wrap > .inner-wrap >.kinja-title.proxima.js_kinja-title-desktop"

• passes[1] ...

En el ejemplo anterior, la matriz passes contiene dos entradas correspondientes a las dos reglas probadas. El primer elemento en la matriz describe una verificación de contraste de color. Los campos help, helpUrl y id se devuelven para cada entrada en la matriz passes. La matriz target tiene un elemento con un valor de:

#js_off-canvas-wrap > .inner-wrap >.kinja-title.proxima.js_kinja-title-desktop

El elemento seleccionado por target[0] fue verificado para la regla de contraste de color y pasó.

Cada entrada subsiguiente en la matriz de pases tiene el mismo formato, pero detallará las diferentes reglas que fueron ejecutadas.

matriz violations

• violations[0]

  • help - "<button> elements must have alternate text"
  • helpURL - "https://dequeuniversity.com/courses/html-css/forms/form-labels#id84_example_button"
  • id - "button-name"
    • nodes
    • target[0]
    • "post_5919997 > .row.content-wrapper > .column > span > iframe" * target[1]
    • "#u_0_1 > .pluginConnectButton > .pluginButtonImage > button"

• violations[1] ...

The violations array contains one entry for a test that checks if buttons have valid alternate text (the button-name rule). This first entry in the array has the help, helpUrl, and id fields.

The target array demonstrates how we specify the selectors when the node specified is inside an iframe or frame. The first element in the target array (target[0]) specifies the selector to the iframe containing the button. The second element in the target array (target[1]) specifies the selector to the actual button but starts from inside the iframe selected in target[0].

Ejemplo Tres

En este ejemplo, pasamos el selector para todo el documento, habilitamos dos reglas de mejores prácticas adicionales, y tenemos una función de devolución de llamada simple que registra el objeto completo de resultados en el registro de la consola:

In this example, we pass the selector for the entire document, enable two additional best practice rules, and have a simple callback function that logs the entire results object to the console log:

AxeDevTools.run(
  document,
  {
    rules: {
      'heading-order': { enabled: true },
      'label-title-only': { enabled: true }
    }
  },
  function (err, results) {
    if (err) throw err;
    console.log(results);
  }
);