Referencia de la API de JavaScript del navegador para axe DevTools for Web

Introducción

La API de axe DevTools está diseñada para ser una mejora con respecto a la generación anterior de API de accesibilidad. Proporciona los siguientes beneficios:

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

Comenzando

Esta sección describe brevemente cómo utilizar las API de DevTools de axe para analizar el contenido de la página web y devolver un objeto JSON que enumera todas las violaciones de accesibilidad encontradas.

La API de DevTools de axe se puede utilizar como parte de un proceso más amplio que se realiza en muchas, si no en todas, las páginas de un sitio web. La API analiza el contenido de la página web y devuelve un objeto JSON que enumera todas las violaciones de accesibilidad encontradas. Aquí te explicamos cómo empezar:

1. Cargar página en el sistema de pruebas
2. Opcionalmente, establezca las opciones de configuración para la API de JavaScript (AxeDevTools.configure)
3. Llame a la API de JavaScript 'analyze' (AxeDevTools.run)
4. O bien haga afirmaciones contra los resultados o guárdelos para su procesamiento posterior

Referencia de la API

Visión general

Las API de axe DevTools se proporcionan en el archivo JavaScript axe-devtools.js. Debe estar incluido 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 reglas se compone de subpruebas. Cada subprueba se devuelve en un array de 'verificaciones'
• El "helpUrl" en el objeto de resultados lleva a una descripción más amplia del problema de accesibilidad y a una solución sugerida. Todos los enlaces apuntan a las páginas de ayuda de la Universidad Deque.

AxeDevTools.init

Propósito

Inicialice la API de axe DevTools para utilizar uno de los conjuntos de reglas estándar integrados.

Descripción

Inicializa el motor axe DevTools, anulando 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
  • ttv5
  • wcag2
  • wcag21
  • wcag22
  • wcag2aaa
  • wcag21aaa
  • wcag22aaa

Devuelve: undefined

AxeDevTools.ruleSets

Propósito

Un arreglo de definiciones de conjuntos de reglas estándar

Descripción

Proporciona acceso directo al arreglo de definición del conjunto de reglas estándar. El arreglo consta de objetos 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 array para encontrar la definición del conjunto de reglas 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

Para obtener información sobre todas las reglas del 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 utilizadas para filtrar las reglas devueltas. Si se omite, devolverá todas las reglas.

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

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

Ejemplo 1

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

Llamar: 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

Para configurar el formato de los datos utilizados por axe DevTools. Esto se puede usar para agregar nuevas reglas, que deben registrarse en la biblioteca para ejecutarse.

Descripción

El usuario especifica el formato de la estructura JSON pasada al callback 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 - de tipo mixto (opcional) Se utiliza para establecer la marca del helpUrls.
    • brand - string (opcional) establece la cadena de marca--predeterminado: "worldspace"
    • application - cadena (opcional) establece la cadena de la aplicación—predeterminado: "AxeDevToolsAPI"
  • reporter - Se utiliza para establecer el formato de salida que pasará la función AxeDevTools.run a la función de devolución de llamada
    • v1 para utilizar el formato de la versión anterior: AxeDevTools.configure({ reporter: "v1" });
    • v2 para utilizar el formato de la versión actual: AxeDevTools.configure({ reporter: "v2" });
  • checks - Se utiliza para agregar verificaciones a la lista de verificaciones utilizadas por las reglas o para anular las propiedades de las verificaciones existentes.
    • El atributo checks es una matriz de objetos de verificación.
    • Cada objeto de verificación puede contener los siguientes atributos:
    • id - cadena (obligatoria). Esto identifica de forma única la verificación. Si la verificación ya existe, se anularán todas las propiedades de verificación suministradas. Las propiedades a continuación marcadas como requeridas si es nuevo son opcionales cuando se anula la verificación.
    -Función evaluate - (requerida si es nueva). Esta es la función que implementa la funcionalidad de la validación. -Función after - (opcional). Esta función se llama para las validaciones que operan a nivel de página para procesar los resultados de los iframes.
    • options - mixto (opcional). Este options objeto se pasa a la evaluate función y está destinado a ser utilizado para configurar comprobaciones. Es la propiedad más común que se pretende anular en las comprobaciones existentes.
    • matches - cadena (opcional). Esta cadena de selector CSS filtrará los nodos pasados a la evaluate función.
    • enabled - booleano (opcional, predeterminado true). Esto indica si la verificación está activada o desactivada de forma predeterminada. No se evalúan las comprobaciones desactivadas, incluso cuando se incluyen en una regla. Sobrescribir esto es una forma común de deshabilitar una verificación particular en múltiples reglas.
  • rules - Se utiliza para agregar reglas al conjunto de reglas existente o anular las propiedades de las reglas existentes. El atributo rules es una matriz de rule objetos. Cada rule objeto puede contener los siguientes atributos:
    • id - cadena (obligatoria). Esto identifica la regla de forma única. Si la regla ya existe, se sobrescribirá con cualquier atributo suministrado. Los atributos a continuación que están marcados como obligatorios solo son necesarios para las reglas nuevas.
    • selector - cadena (opcional, predeterminada *). Un selector CSS utilizado para identificar los elementos pasados a la regla para su evaluación.
    • excludeHidden - booleano (opcional, predeterminado true). Esto indica si los elementos ocultos deben pasarse a la regla para su 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 funciona solo cuando el alcance es la página completa. Un ejemplo de una regla como esta es la regla de salto de enlace . No se recomienda anular esta propiedad a menos que también se cambie la implementación.
    • any - array (opcional, predeterminado []). Esta es la lista de verificaciones que todos deben pasar o habrá una violación.
    • all - array (opcional, por defecto []). Esta es la lista de comprobaciones que, si alguna falla, generarán una violación.
    • none - array (opcional, por defecto []). Esta es una lista de las comprobaciones que, si ninguna pasa, generarán una violación.
    • tags - array (opcional, por defecto []). Una lista de las etiquetas que clasifican 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 WCAG 2, el párrafo de la Sección 508 y los criterios de éxito 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, predeterminada *). Un selector CSS que excluirá los elementos que no coincidan con él.

Devuelve: Nada

AxeDevTools.reset

Propósito

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

Descripción

Sobrescriba cualquier llamada anterior a AxeDevTools.configure o AxeDevTools.reset y restablezca la configuración a la configuración predeterminada.

Sinopsis

AxeDevTools.reset();

Parámetros

Ninguno

Devuelve: undefined

AxeDevTools.run

Propósito

Analizar la página cargada actualmente.

Descripción

Ejecuta varias reglas en la página HTML proporcionada y devuelve la lista de problemas resultante.

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. Normalmente será el document o un selector específico como el nombre de la clase, ID, selector, etc.
• options: (opcional) Conjunto de opciones pasadas a reglas o comprobaciones, 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 un resultado de error como primer parámetro, y el objeto de resultados cuando el análisis se completó correctamente o undefined si no se completó.

context Parámetro

De forma predeterminada, AxeDevTools.run probará todo el documento. El objeto context es un parámetro opcional que especifica qué elemento se debe probar y cuál no. Se puede pasar una de las siguientes:

1. Una referencia de elemento que representa la parte del documento que debe analizarse
   • Ejemplo: Para limitar el análisis al elemento <div id="content"> : document.getElementById("content")
2. Una lista de nodos como la devuelta por document.querySelectorAll.
3. Un selector CSS que selecciona la parte del documento que debe analizarse. 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 identificador de elemento (por ejemplo, #tag)
4. Un objeto de inclusión-exclusión (ver más abajo)

include y objetos exclude

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

• Un nodo, o
• Una matriz de matrices de selectores CSS

En la mayoría de los casos, las matrices contendrán solo un selector CSS. Solo se requieren varios selectores CSS 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 los iframes y el selector n-ésimo selecciona las regiones dentro de los iframes.

context Ejemplos de parámetros

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

   {
     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. Incluya todo el documento excepto cualquier estructura cuyo padre contenga la clase exclude1 o exclude2

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

options Parámetro

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

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

options Ejemplos de parámetros

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

   Existen ciertos estándares definidos que pueden utilizarse para seleccionar un conjunto de reglas. Los estándares y la cadena de etiquetas se definen de la siguiente manera:

   Nombre de la etiqueta	Norma 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	Trusted Tester v5
   best-practice	Mejores prácticas avaladas por Deque

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

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

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

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

2. Ejecutar solo una lista específica de reglas

   Si solo desea ejecutar determinadas reglas, especifique opciones como:

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

   Este ejemplo solo ejecutará las reglas con el id de ruleId1 , ruleId2 y ruleId3. No se aplicará 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 WCAG 2.0 Nivel A y Nivel AA. Si se debe deshabilitar la ejecución de ciertas reglas, especifíquelo options de la siguiente manera:

   {
     "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 ID de reglas válidas se especifica en la sección siguiente.

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

   Se puede definir un conjunto modificado combinando runOnly con type establecido en 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 de nivel A excepto valid-lang, y también incluirá la regla de contraste de color de nivel AA.

5. Ejecutar sólo algunas reglas, pero excluir otras

   La opción runOnly puede aceptar un objeto con propiedad include y exclude . Solo se ejecutarán aquellas 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 incluye primero reglas wcag2a y wcag2aa . Luego, todas las reglas etiquetadas como experimental se eliminan de las reglas a ejecutar.

callback Parámetro

El parámetro callback es una función que se llamará cuando se complete la función AxeDevTools.run asíncrona. A la función callback se le pasan dos parámetros. El primer parámetro será un error generado dentro de Axe DevTools si AxeDevTools.run no se puede completar. 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 no se definió el callback, axe DevTools devolverá una promesa en su lugar. Sin embargo, axe DevTools no polyfill 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 para promesas, le sugerimos que utilice el callback proporcionado por AxeDevTools.run en su lugar.

error Resultado

Esto será null o un objeto que es una instancia de Error. Si recibe errores constantemente, informe este problema a Deque Systems.

results Objeto

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

url

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

timestamp

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

passes y violations matriz

• description - Una cadena de texto que describe lo que hace la regla
• 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 infracción. Puede ser menor, moderado, grave o crítico si la regla falló o null si la comprobación fue exitosa.
• tags - Un array de etiquetas asignadas a esta regla. Las etiquetas se pueden usar option en el objeto para seleccionar qué reglas se ejecutan (consulte Parámetro de opciones arriba).
• nodes - Un array de todos los elementos que la regla probó
  • html - Un fragmento de HTML del elemento
  • impact - La gravedad de la infracción. Puede ser menor, moderado, grave o crítico si la prueba falló o null si la comprobación pasó.
  • target - Una matriz de selectores donde cada elemento corresponde a un nivel de iframe o marco. Si hay un iframe o marco, debe haber dos entradas en target. Si hay tres niveles de iframe, debería haber cuatro entradas en target.
  • any - Una serie de validaciones donde al menos una debe haber sido aprobada. Cada entrada del Array contiene:
    • id - Identificador único para esta comprobación. Los identificadores de validación pueden ser los mismos que los identificadores de reglas.
    • impact - La gravedad de la validación. Puede ser menor, moderado, grave o crítico. Cada verificación que forma parte de una regla puede tener diferentes impactos. Para la regla, se informa el mayor impacto de todas las comprobaciones que fallan.
    • message - La descripción de por qué esta verificación se aprobó 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 comprobación. Por ejemplo, una violación de verificación de identificación duplicada enumeraría los otros selectores con la misma identificación duplicada. Cada entrada de la matriz contiene la siguiente información:
      • target - Un arreglo de selectores para el nodo relacionado
      • html - La fuente HTML del nodo relacionado
  • all - Un arreglo de comprobaciones realizadas donde todas deben haber sido aprobadas. Cada entrada en el arreglo contiene la misma información que el any arreglo.
  • none - Un arreglo de comprobaciones realizadas donde todas deben no haber sido aprobadas. Cada entrada en el arreglo contiene la misma información que el any arreglo.

Ejemplo Dos

En este ejemplo, pasaremos el selector del documento completo, no proporcionaremos opciones, lo que significa que se ejecutarán todas las reglas activadas, y tendremos una función de callback simple que registra el objeto completo de resultados en el log de la consola:

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

passes array

• 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 passes matriz contiene dos entradas correspondientes a las dos reglas probadas. El primer elemento de 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 en cuanto a 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 se ejecutaron.

violations array

• 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] ...

La matriz violations contiene una entrada para una prueba que verifica si los botones tienen texto alternativo válido (la norma button-name ). Esta primera entrada en la matriz tiene los campos help, helpUrl y id .

La matriz target demuestra cómo especificamos los selectores cuando el nodo especificado está dentro de un iframe o frame. El primer elemento de la matriz target (target[0]) especifica el selector para el iframe que contiene el botón. El segundo elemento de la matriz target (target[1]) especifica el selector del botón real, pero comienza desde dentro del iframe seleccionado en target[0].

Cada entrada subsiguiente en la matriz de violaciones tiene el mismo formato pero detallará las reglas que generaron violaciones de accesibilidad.

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 todo el objeto de resultados en el registro de la consola:

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