Uso avanzado de la API con Ruby
Uso avanzado de Axe DevTools para Web Ruby, incluyendo reglas personalizadas, opciones de informes y el servicio de uso
Este documento discute las reglas personalizadas, las opciones de informes y el servicio de uso con Ruby.
Elementos personalizados e ElementInternals
A partir de Axe DevTools Ruby 4.13.0, los análisis leen las semánticas ARIA que los componentes web declaran en JavaScript a través de ElementInternals, en lugar de solo los atributos role y aria-* presentes en el marcado. No se requiere configuración. Las semánticas en el DOM siguen teniendo prioridad: un atributo role o aria-* explícito en el elemento anula el valor de ElementInternals.
Tus componentes deben publicar sus internos para que cualquiera de estas acciones surta efecto, y un componente que los almacene en un campo de clase privado no se puede leer. Consulte Pruebas de elementos personalizados que utilizan ElementInternals.
Reglas personalizadas
Puedes especificar reglas personalizadas de axe-core en un archivo JSON.
Si aún no tiene reglas personalizadas y desea comenzar con un conjunto de reglas vacío, cree un archivo axe-ruleset.json en el directorio local con un objeto JavaScript vacío, por ejemplo: {}.
Configurar reglas personalizadas mediante una variable de entorno
La configuración predeterminada espera que la ubicación del archivo de reglas personalizadas sea config/axe-ruleset.json, relativa al directorio de trabajo actual.
Puede sobrescribir esta ubicación con la variable de entorno AXE_RULESET_PATH o manualmente a través de la configuración de Axe DevTools.
Configure la variable de entorno AXE_RULESET_PATH para cambiar la ubicación de su axe-ruleset.json:
AXE_RULESET_PATH=/path/to/your/axe-ruleset.jsonConfiguración de reglas personalizadas a través de la configuración de Axe DevTools
Un objeto de configuración está disponible para definir una ubicación de regla personalizada utilizando el método AxeDevTools.configure si no desea trabajar con la variable de entorno AXE_RULESET_PATH.
Todas las configuraciones a continuación son opcionales. Puede omitir toda la invocación AxeDevTools.configure para usar los valores predeterminados originales.
AxeDevTools.configure do |config|
# path to json configuration providing custom rules and checks
# set defaults to "config/axe-ruleset.json"
config.axe_ruleset_path = "config/axe-ruleset.json"
# Configure user pre-defined standard rule sets. Custom
# rules override these rule sets. See https://github.com/dequelabs/axe-core/blob/develop/doc/rule-descriptions.md
config.rule_set_id = '508'
endOpciones de informe
Configuración de opciones de informe con la configuración de Axe DevTools
Las gemas axe-devtools-* permiten registrar los resultados de las pruebas. Use la invocación AxeDevTools.Configure para configurar una configuración global para informes:
AxeDevTools.configure do |config|
config.output_directory: 'my-results',
config.test_machine: 'my-server',
config.test_suite_name: 'Accessibility Tests For Application',
config.user_agent: 'Headless Chrome'
end
expect(page).to be_audited_for_accessibility.logging_results({
ui_state: 'Landing Page Load',
})La configuración de informes puede tomar las siguientes propiedades:
| Atributo | Valor por Defecto | Descripción |
|---|---|---|
| ui_state (Obligatorio) | Atributo para pasar en el objeto options. |
|
| output_directory (Opcional) | axe-reports |
Nombre del directorio en el que se deben generar los informes. |
| test_machine (Opcional) | Valor para mostrar dónde se ejecuta la prueba. Ej., CircleCI, TesterMachine01 |
|
| test_suite_name (Opcional) | axe-a11yCheck |
Nombre de la suite para las pruebas. Ej., My Module Test Suite |
| user_agent (Opcional) | null | Pase un agente de usuario objetivo. Ej., chrome. |
| verbose (Opcional) | false | indicador para habilitar/deshabilitar el registro detallado del seguimiento de la pila y los mensajes. |
Además, tenga en cuenta que todas las opciones anteriores para AxeDevTools.configure se pueden pasar al configurar el WebDriver de su elección. Por ejemplo:
require 'axe-devtools-capybara'
AxeCapybara.configure do |config|
config.axe_config_path = 'config/my-ruleset.json'
endVer También
- Cargando Resultados de Accesibilidad JSON a Axe Reports describe cómo cargar tus resultados en Axe Reports.
- Obteniendo una Clave API de Axe Reports explica cómo obtener una clave API para comenzar a usar Axe Reports.
- Crear y Filtrar Informes muestra cómo puedes crear informes de accesibilidad en CSV, XML o HTML a partir de tus resultados de accesibilidad JSON. También puedes filtrar tu salida por severidad utilizando esta herramienta.
- Cómo se Almacenan los Resultados JSON en el Disco describe las convenciones de nomenclatura de archivos para resultados de accesibilidad JSON.
- Usando la CLI para Enviar Resultados de Accesibilidad al Centro de Desarrolladores de Axe muestra cómo puedes subir tus archivos de resultados
.jsona Centro de Desarrolladores de Axe.
Servicio de uso
Puede obtener información sobre las tendencias de uso de Axe DevTools dentro de su organización con el servicio de uso.
Por defecto, el servicio de uso está habilitado, y la URL de seguimiento es https://usage.deque.com.
En la API de Ruby, utiliza la propiedad de configuración enableTracking descrita a continuación para desactivar el seguimiento de uso, en lugar de la variable de entorno AXE_TRACK_USAGE. Si tus eventos de uso no llegan a Deque, establece la URL de seguimiento explícitamente con setTrackingUrl.
Configuración de opciones de servicio de uso con la configuración de Axe DevTools
Las gemas axe-devtools-* permiten configurar el servicio de uso a través de una configuración global:
AxeDevTools.configure do |config|
config.setTrackingUrl: 'https://usage.deque.com',
endLas propiedades de configuración específicas del servicio de uso son:
| Atributo | Valor por Defecto | Descripción |
|---|---|---|
| enableTracking | true | Opción para habilitar el seguimiento de uso. |
| setTrackingUrl | https://usage.deque.com |
Opción para anular la URL de seguimiento. |
| equipos | Los equipos que ejecutan tus pruebas, como un arreglo de { id: "...", name: "..." } hashes. Ver Equipos. |
Además, observa que todas las opciones mencionadas anteriormente para AxeDevTools.configure también se pueden pasar al configurar el WebDriver de tu elección. Por ejemplo, para Capybara:
require 'axe-devtools-capybara'
AxeCapybara.configure do |config|
config.enableTracking = false
endEquipos
Puedes registrar los equipos que ejecutan tus pruebas en los eventos de uso. Cada equipo es un hash con valores de cadena id y name. Las entradas sin ambos se eliminan, y un arreglo vacío no envía equipos.
Puedes establecer equipos en tres lugares. Si se establece más de uno, se utiliza el primero de esta lista:
-
Para una única verificación de RSpec, la cláusula
for_teams. -
Para toda la ejecución, la propiedad de configuración
teams:AxeDevTools.configure do |config| config.teams = [{ id: "1", name: "Web" }] end -
La variable de entorno
AXE_TEAMS, configurada en un arreglo JSON de objetos{ "id": "...", "name": "..." }o en la ruta de un archivo JSON que contenga uno. Si no se puede leer el valor, la API imprime una advertencia y no envía equipos, y el escaneo continúa.
La gema Cucumber no tiene opción por verificación, así que usa la propiedad de configuración teams o AXE_TEAMS con Cucumber.
Los eventos de uso también registran si una persona o un flujo de trabajo automatizado ejecutó las pruebas. La API informa automation cuando se establece una variable de entorno CI común como CI, GITHUB_ACTIONS o JENKINS_URL, y human en caso contrario. Configura AXE_ACTOR en human o automation para anular esto.
Configuración de opciones de servicio de uso con variables de entorno
Además, las opciones de servicio de uso se pueden configurar a través de variables de entorno.
| Nombre | Tipo | Puede sobrescribir | Descripción |
|---|---|---|---|
AXE_DISTINCT_ID |
Cadena | — | Un identificador UUID que permanece igual para el usuario registrado (a menos que se regenere). En Ruby, esta variable se llama DEQUE_DISTINCT_ID. |
AXE_INCLUDE_TEST_RESULTS |
Booleano | — | Configúrelo en true para incluir los resultados completos de axe-core en el objeto testResults de cada evento (el valor predeterminado es false). Compatible solo con el CLI y las API de Node.js. |
AXE_METRICS_URL |
Cadena | — | La URL del punto final de uso de REST (el valor predeterminado es https://usage.deque.com) |
AXE_TRACK_USAGE |
Booleano | — | Configúrelo en false para desactivar la generación de informes del servicio de uso. El informe está habilitado de forma predeterminada. |
AXE_ACTOR |
Cadena | — | Establece en human o automation para anular si los eventos registran a una persona o a un proceso automatizado como ejecutando las pruebas. Por defecto, automation se detecta a partir de variables comunes del entorno de CI. Solo es compatible con el CLI, las API de Node.js y la API de Ruby. |
AXE_APPLICATION |
Cadena | falso | La aplicación que se utilizó para verificar errores de accesibilidad |
AXE_DEV_INSTANCE |
Booleano | verdadero | Indica si este evento es producto de las acciones de un desarrollador de software. Útil para marcar y luego eliminar eventos registrados durante el desarrollo o las pruebas. |
AXE_DEPARTMENT |
Cadena | verdadero | El departamento del usuario dentro de la organización |
AXE_KEYCLOAK_ID |
Cadena | falso | El ID de Keycloak del usuario |
AXE_LOGGED_IN |
Booleano | falso | Registra si el usuario está conectado a la aplicación bajo prueba |
AXE_ORGANIZATION |
Cadena | verdadero | La organización del usuario. Para que su uso aparezca en Axe Reports, configúrelo con el ID de su organización (contacte a Deque para obtenerlo). |
AXE_SESSION_ID |
Cadena | falso | Un UUID que identifica la sesión del usuario |
AXE_TEAMS |
Cadena | falso | Los equipos que ejecutan las pruebas, como un arreglo JSON de { "id": "...", "name": "..." } objetos o la ruta a un archivo JSON que contenga uno. Un valor pasado a la opción --set-teams del CLI, al método setTeams de la API de Node.js, o a la cláusula for_teams o propiedad de configuración teams de la API de Ruby tiene prioridad. Solo es compatible con el CLI, las API de Node.js y la API de Ruby. |
AXE_USER_ID |
Cadena | falso | La identidad específica de un usuario, como una dirección de correo electrónico, nombre o ID de inicio de sesión. Axe Reports cuenta usuarios únicos a partir de este valor. |
AXE_USER_JOB_ROLE |
Cadena | falso | El rol laboral del usuario |
AXE_USER_STATUS |
Cadena | falso | Información de estado que desea asociar con el usuario |
