Uso de Axe DevTools Linter Connector

El Axe DevTools Linter Connector (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 sus archivos a fin de que pueda automatizar la comprobación de accesibilidad. Puede, por ejemplo, usarlo para script y CI/CD (integración continua y entrega continua). El Conector necesita enviar sus archivos a una instancia de Axe Linter Server, ya sea alojada por Deque (SaaS) o por su organización (en las instalaciones o en sitio), o puede analizar los archivos localmente sin enviar el contenido de sus archivos a un servidor utilizando la --local opción (ver Analizador Local más abajo).

Casos de uso del Conector

El Axe DevTools Connector puede

• Verificar la accesibilidad como parte de las compilaciones de Jenkins. Para más información, ver Uso de Axe DevTools Linter con Jenkins.
• Escanear sus archivos y enviar información sobre defectos de accesibilidad a SonarQube. Ver Uso de Axe DevTools Linter con SonarQube para obtener información sobre cómo configurarlo.
• Usarse en un script de precompromiso de GitHub para bloquear compromisos que contengan errores de accesibilidad. Ver 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

Analizador Local

El Conector le permite evitar enviar sus archivos a un servidor mediante el uso de análisis local con la --local opción de línea de comandos.

• 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 linting local requiere una clave API o una clave de licencia. Puedes gestionar tus claves API como parte de tu cuenta de Axe (por lo que ofrecen flexibilidad). Sin embargo, debes solicitar una clave de licencia a la mesa de ayuda de Deque. Usar linting local con claves de licencia no rastrea el uso de los 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 Connector. 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 Connector según 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 las -u o --url opciones de línea de comandos). AXE_LINTER_SERVER_PORT especifica el puerto en el que escucha el servidor, típicamente el puerto 3000.

Consulta Configuración de Axe DevTools Linter para obtener más información sobre la configuración de tu servidor, y consulta Referencia Rápida de URLs para la URL de uso con la versión SaaS de Axe DevTools Linter. (No necesitas especificar un puerto al usar 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 configurar las variables de entorno en la misma línea de comando que el axe-linter-connector comando. 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

El AXE_SERVICE_URL variable de entorno te permite especificar un servidor alternativo para validar tu clave API. Esta variable de entorno es útil para las organizaciones que utilizan una instancia de servidor privada para la validación de claves API. El valor predeterminado es https://axe.deque.com.

Para obtener más información sobre el uso de servidores alternativos para la validación de claves API, contacta a la mesa de ayuda de Deque.

DEBUG

La DEBUG variable de entorno te permite registrar información detallada de depuración para diagnosticar fallos de linting. Establece la DEBUG variable de entorno 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 en busca de errores de accesibilidad. También se buscan subdirectorios. Para excluir archivos del linting, consulte la opción exclude en el Archivo de Configuración sección.

-d, --destination directorio
El directorio donde el Conector escribirá el informe de accesibilidad.

-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
Agrega propiedades extra 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 involucre un componente mapeado a medida obtiene una customName propiedad en el informe cuyo valor es el nombre de la etiqueta del componente personalizado que desencadenó la violación. Los problemas de componentes que no son parte de una asignación personalizada no tendrán una customName propiedad.

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

Por ejemplo, si <MyButton> es un componente mapeado a medida y desencadena una button-name violación, 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 linting con la instancia SaaS de Axe DevTools Linter o para usar linting 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 obtener 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 para usar en la autenticación. Contacte con la Mesa de Ayuda de Deque para obtener más información sobre cómo conseguir una clave de licencia. Esta opción también requiere la opción --local .

--local
Activa el linting local, que utiliza la máquina en la que se ejecuta el Conector de Axe DevTools para analizar sus archivos en lugar de enviar los archivos a un servidor. Requiere una clave de API (--api-key) o una clave de licencia (--license-key). Ver Linting Local.

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

-R, --reporter reportero
Especifica el reportero a utilizar, por defecto: sonarqube

--retry-backoff-limit límite de retroceso
Especifica el máximo tiempo en milisegundos que el Conector esperará antes de intentar reconectar con el servidor tras un error. El valor predeterminado es 30,000 milisegundos (30 segundos).

--retry-count reintentos
Especifica el número de veces que se intentará reconectar con el 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 alcanzar el límite de retroceso (especificado con --retry-backoff-limit), donde permanecerá hasta que alcance el número especificado de reintentos (y falle) o se conecte al servidor sin error.

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

Archivo de Configuración

Puede utilizar 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 serán utilizadas, como se especifica en la sección tags . (Ver Etiquetas para más información.)

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

exclude:
  - tmp/**/*.html

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

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

Ejemplo de Uso

Para usar el Conector con el servidor SaaS de Axe DevTools Linter, puede usar la --api-key opción 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 toda la verificación localmente en el ordenador que ejecuta Axe DevTools Connector, utilice la --local opción:

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