Uso de Axe DevTools Linter Connector

El Conector de Axe DevTools Linter (también conocido como el Conector) es una herramienta de línea de comandos para Linux, macOS y Windows. Proporciona una interfaz de línea de comandos para analizar tus archivos y así automatizar la verificación de accesibilidad. Puedes, por ejemplo, usarlo para la creación de scripts y CI/CD (integración continua y entrega continua). El Conector necesita enviar tus archivos a una instancia del servidor Axe Linter, ya sea alojada por Deque (SaaS) o por tu organización (en las instalaciones o en sitio), o puedes analizar los archivos localmente sin enviar el contenido de tus archivos a un servidor usando la opción --local (ver Linting Local a continuación).

Casos de uso del Conector

El Axe DevTools Connector puede

• Comprueba la accesibilidad como parte de las construcciones de Jenkins. Para más información, consulta Uso de Axe DevTools Linter con Jenkins.
• Analiza tus archivos y proporciona información sobre los defectos de accesibilidad a SonarQube. Consulta Uso de Axe DevTools Linter con SonarQube para obtener información sobre cómo configurarlo.
• Utilízalo en un script de pre-commit de GitHub para bloquear commits que contengan errores de accesibilidad. Consulta Uso de un Hook de Precompromiso de Git con Axe DevTools Linter.
• Proporcionar una base para verificar su código en busca de defectos de accesibilidad para servicios tales como:
  • Bitbucket
  • CircleCI
  • GitLab
  • Azure DevOps Services

Linting Local

El Conector te permite evitar enviar tus archivos a un servidor utilizando linting local con la opción de línea de comandos --local.

• Ventajas del Análisis Local

  • Mucho más rápido que usar el servidor.
  • Mucho menos propenso a encontrar problemas de red o cargas del servidor. Es especialmente eficiente al analizar un gran número de archivos.

• Desventajas del Análisis Local

  • Requiere más recursos de la máquina local.
  • Las actualizaciones del Axe DevTools Linter Connector requieren descargar una nueva versión de Agora e instalarla.
  • Sin seguimiento de uso (si usas una clave de licencia en lugar de una clave API).

Claves de Licencia Comparadas con Claves API

El análisis local requiere una clave API o una clave de licencia. Puedes gestionar tus claves API como parte de tu cuenta de Axe (así ofrecen flexibilidad). Sin embargo, debes solicitar una clave de licencia a la mesa de ayuda de Deque. Usar el análisis local con claves de licencia no rastrea el uso de tus usuarios (líneas de código analizadas), pero las claves de licencia tampoco requieren autenticación remota.

Opciones de Instalación

Existen dos opciones para instalar el Axe DevTools Linter Connector:

• Configura un registro npm de Agora y utiliza la infraestructura proporcionada por NodeJS y npm para instalar, ejecutar y actualizar el Conector. Consulta Instalando el Axe DevTools Linter Connector como un paquete npm para más información.
• La otra opción es descargar manualmente el binario del Conector para la arquitectura de tu computadora y prepararlo para su uso configurando su bit de ejecución (Linux y macOS) y eliminando cualquier atributo de cuarentena extendido (macOS). Consulta la página de descargas.

Variables de Entorno

El Connector reconoce las siguientes variables de entorno:

• AXE_LINTER_SERVER_URL
• AXE_LINTER_SERVER_PORT
• AXE_SERVICE_URL
• DEBUG

AXE_LINTER_SERVER_URL y AXE_LINTER_SERVER_PORT

AXE_LINTER_SERVER_URL establece la URL para tu instancia del servidor de Axe DevTools Linter. (También puedes establecer la URL del servidor con el -u o --url opciones de línea de comandos). AXE_LINTER_SERVER_PORT especifica el puerto en el que el servidor escucha, típicamente el puerto 3000.

Consulta Configuración de Axe DevTools Linter para obtener más información sobre cómo configurar tu servidor, y consulta Referencia Rápida de URLs para obtener la URL para usar con la versión SaaS de Axe DevTools Linter. (No necesitas especificar un puerto cuando uses la versión SaaS de Axe DevTools Linter.)

El siguiente ejemplo muestra cómo configurar las variables de entorno para Axe DevTools Linter ejecutándose en la máquina local en Linux o macOS (aunque ninguna de las variables de entorno es necesaria aquí porque estos son los valores predeterminados):

export AXE_LINTER_SERVER_URL=http://localhost
export AXE_LINTER_SERVER_PORT=3000

Alternativamente, en Linux y macOS, también puedes establecer las variables de entorno en la misma línea de comando que el comando axe-linter-connector. El ejemplo a continuación muestra este uso. (Sin embargo, dado que estos son los valores predeterminados para el servidor y el puerto, no necesitas configurarlos.)

AXE_LINTER_SERVER_PORT=3000 AXE_LINTER_SERVER_URL=http://localhost axe-linter-connector -s . -d .

AXE_SERVICE_URL

La variable de entorno AXE_SERVICE_URL te permite especificar un servidor alternativo para validar tu clave API. El valor predeterminado es https://axe.deque.com.

Los clientes de nube privada tienen un servidor de autenticación dedicado en una URL específica del cliente. Para usar el análisis local, configura AXE_SERVICE_URL a la URL de tu instancia de nube privada antes de ejecutar el Conector:

export AXE_SERVICE_URL=https://your-org-axedevtools.dequecloud.com
axe-linter-connector -s . -d . --api-key <your-api-key> --local

La URL de tu instancia de nube privada fue proporcionada cuando se configuró tu instancia de nube privada. Si no la tienes, contacta con la mesa de ayuda de Deque.

DEBUG

La variable de entorno DEBUG te permite registrar información detallada de depuración para diagnosticar fallos de análisis. Establece la variable de entorno DEBUG a axe-devtools-linter:* para activar el registro de depuración, como se muestra a continuación:

DEBUG=axe-devtools-linter:* axe-linter-connector -s . -d .

Opciones de Línea de Comando

Opciones de Línea de Comando Requeridas

El Conector de Linter de Axe DevTools requiere las siguientes dos opciones:

-s, --source directorio-o-archivo
Indica un archivo o un directorio que contiene archivos para verificar errores de accesibilidad. También se buscan subdirectorios. Para excluir archivos del análisis, consulta la opción exclude en la sección Archivo de Configuración.

-d, --destination directorio
The directory where the Connector will write the accessibility report.

-u, --url URL
Especifica el servidor a utilizar. El predeterminado es http://localhost. Para usar el servidor SaaS, especifica --url https://axe-linter.deque.com/

Opciones de Línea de Comando Opcionales

Varias opciones podrían ser requeridas, dependiendo de a qué servidor te estés conectando y qué otras funciones o formatos de informes desees utilizar.

--additional-properties propiedad
Añade propiedades adicionales a los problemas en el informe de accesibilidad para violaciones encontradas en componentes mapeados a medida. El único valor actualmente soportado es customName. Cuando se especifica, cada problema que involucra un componente mapeado de manera personalizada obtiene una propiedad customName en el informe cuyo valor es el nombre de la etiqueta del componente personalizado que activó la violación. Los problemas de componentes que no forman parte de un mapeo personalizado no tendrán una propiedad customName.

axe-linter-connector -s . -d . --additional-properties customName

Por ejemplo, si <MyButton> es un componente mapeado de manera personalizada y activa una violación button-name, el problema en el informe se verá así:

{
    "engineId": "axe-linter-jsx",
    "ruleId": "button-name (https://dequeuniversity.com/rules/axe/4.11/button-name?application=axe-linter)",
    "customName": "MyButton",
    "severity": "MAJOR",
    "type": "BUG",
    "primaryLocation": {
        "filePath": "/path/to/app.jsx",
        "message": "Buttons must have discernible text",
        "textRange": {
            "startLine": 7,
            "endLine": 7,
            "startColumn": 12,
            "endColumn": 20
        }
    }
}

--api-key clave-api
Especifica la clave API para autorizar el análisis con la instancia de SaaS de Axe DevTools Linter o para usar el análisis local. Consulta Obtención de una Clave API de Axe DevTools Linter SaaS para más información.

--config nombre de archivo
Especifica el nombre de un archivo YAML que contiene información de configuración. También puedes usar esta opción sin un nombre de archivo, y el Conector de Axe DevTools seguirá los pasos en Orden de Búsqueda de Archivos de Configuración para localizar el archivo de configuración. Para información sobre el archivo de configuración, consulta Archivo de Configuración.

--filename nombre de archivo
Especifica el nombre del informe de SonarQube, predeterminado: axe-linter-report.json

--issue-type tipo
Se utiliza para indicar el tipo de problema para SonarQube, predeterminado: BUG, valores permitidos: VULNERABILITY, CODE_SMELL, o BUG

--license-key clave
Especifica la clave de licencia a utilizar para la autenticación. Contacta la Mesa de Ayuda de Deque para más información sobre cómo obtener una clave de licencia. Esta opción también requiere la opción --local.

--local
Activa el análisis local, que utiliza la máquina en la que se ejecuta el Conector de Axe DevTools para analizar tus archivos en lugar de enviarlos a un servidor. Requiere una clave API (--api-key) o una clave de licencia (--license-key). Consulta Linting Local.

axe-linter-connector -s . -d . --api-key 1234 --local --url https://axe-linter.deque.com/

-R, --reporter reportero
Especifica el reporte a utilizar, predeterminado: sonarqube

--retry-backoff-limit límite de retroceso
Especifica el tiempo máximo en milisegundos que el Conector esperará antes de volver a intentar la conexión al servidor en caso de error. El valor predeterminado es 30,000 milisegundos (30 segundos).

--retry-count reintentos
Especifica el número de veces a reintentar la conexión al servidor después de encontrar un error de conexión. El Conector duplicará el tiempo entre reintentos (comenzando en 500 milisegundos o 0.5 segundos) hasta que llegue al límite de retroceso (especificado con --retry-backoff-limit), donde permanecerá hasta alcanzar el número especificado de reintentos (y falla) o conectarse al servidor sin error.

--severity nivel
Establece el nivel de severidad para SonarQube, predeterminado: MAJOR, valores permitidos: BLOCKER, CRITICAL, MAJOR, MINOR, o INFO.

Archivo de Configuración

Puedes usar un archivo de configuración YAML con la opción --config.

Lo siguiente muestra un ejemplo de archivo de configuración:

rules:
  image-alt: false

exclude:
  - meta-refresh.html

tags:
  - wcag2a

En el ejemplo anterior, la regla image-alt será ignorada, y el archivo meta-refresh.html no será analizado. Las reglas en la etiqueta wcag2a se usarán, como se especifica en la sección tags. (Consulta Etiquetas para más información.)

El valor exclude permite valores de glob (*) y globstar (**), por lo que se permite lo siguiente:

exclude:
  - tmp/**/*.html

El ejemplo anterior excluye cualquier archivo HTML en el directorio tmp y sus subdirectorios.

Para obtener más información sobre las opciones de configuración permitidas, consulta Configuración de Axe DevTools Linter.

Ejemplo de Uso

Para usar el Conector con el servidor SaaS de Axe DevTools Linter, puedes usar la opción --api-key como se muestra a continuación:

axe-linter-connector -s . -d . --api-key 83cc5831-a35b-4a2d-9c2b-84fd2eec0a4d  --url https://axe-linter.deque.com/

Para realizar todo el análisis localmente en la computadora que ejecuta el Conector de Axe DevTools, usa la opción --local:

axe-linter-connector -s . -d . --api-key b5a34bba-7b0f-4ccb-9eb2-195ac6c56aee --local --url https://axe-linter.deque.com/