Uso del conector Linter de axe DevTools

axe DevTools Linter Conector (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 de modo que pueda automatizar su verificación de accesibilidad. Puede usarlo, por ejemplo, para la escritura de scripts y CI/CD (integración continua y entrega continua). El Conector debe enviar sus archivos a una instancia de axe Linter Server (ya sea alojado por Deque o por su organización), o puede analizar los archivos localmente sin enviar el contenido de sus archivos a un servidor usando la opción --local , consulte Análisis local a continuación.

Casos de uso del Conector

El conector axe DevTools puede

• Verificar la accesibilidad como parte de las compilaciones de Jenkins. Para obtener más información, consulte Uso de axe DevTools Linter con Jenkins.
• Escanear sus archivos y proporcionar información sobre defectos de accesibilidad en SonarQube. Consulte Uso de axe DevTools Linter con SonarQube para obtener información sobre cómo configurar esto.
• Se utilice en un script de pre-commit de GitHub para bloquear commits que contengan errores de accesibilidad. Consulte Cómo usar un gancho de preconfirmación de Git con axe DevTools Linter.
• Proporcionar una base para verificar su código en busca de defectos de accesibilidad para servicios como:
  • Bitbucket
  • CircleCI
  • GitLab
  • Servicios de Azure DevOps

Linting local

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

• Ventajas del linting local

  • Mucho más rápido que usar el servidor.
  • Es mucho menos probable que surjan problemas de red o problemas de carga del servidor. Es especialmente eficiente cuando se analizan grandes cantidades de archivos.

• Desventajas del linting local

  • Requiere más recursos de la máquina local.
  • Las actualizaciones del conector axe DevTools Linter requieren que se descargue e instale una nueva versión de Agora.
  • No hay seguimiento de uso (si utiliza 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 administrar tus claves API como parte de tu cuenta axe (por lo que ofrecen flexibilidad). Sin embargo, debe solicitar una clave de licencia al Servicio de asistencia de Deque. El uso de 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.

Configuración

Para obtener información sobre cómo descargar el conector axe DevTools Linter, consulte Descarga del conector axe DevTools Linter.

En Linux y macOS, el archivo de comando necesita tener configurado su indicador de ejecución, como se muestra a continuación:

chmod +x axe-linter-connector-linux
chmod +x axe-linter-connector-macos

Al descargar el ejecutable en macOS, se configura el atributo de cuarentena, que debes eliminar antes de poder usar el conector:

xattr -d com.apple.quarantine axe-linter-connector-macos

Cambie el nombre del ejecutable (para quitar el sistema operativo y el guion del final del nombre del archivo) y cópielo o vincúlelo a un directorio en su ruta para que pueda usarse con otras herramientas (como con un gancho de pre-commit de Git, consulte Uso de un gancho de pre-commit de Git con axe DevTools Linter).

Variables de entorno

El conector reconoce las siguientes variables de entorno:

• AXE_LINTER_SERVER_URL
• AXE_LINTER_SERVER_PORT
• DEBUG

AXE_LINTER_SERVER_URL y AXE_LINTER_SERVER_PORT

AXE_LINTER_SERVER_URL Establece la URL para su instancia de servidor axe DevTools Linter. (También puede configurar 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, normalmente el puerto 3000.

Consulte Configuración de axe DevTools Linter para obtener más información sobre cómo configurar su servidor, y consulte Referencia rápida de URL para obtener la URL para usar con la versión SaaS de axe DevTools Linter. (No es necesario especificar un puerto cuando se utiliza la versión SaaS de axe DevTools Linter).

El siguiente ejemplo muestra la configuración de variables de entorno para axe DevTools Linter que se ejecuta en la máquina local en Linux o macOS (aunque aquí no se requiere ninguna variable de entorno 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 comando axe-linter-connector . El siguiente ejemplo muestra este uso. (Sin embargo, debido a que estos son los valores predeterminados para el servidor y el puerto, no es necesario configurarlos).

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

DEBUG

La variable de entorno te permite registrar información de depuración detallada para diagnosticar errores de linting. DEBUG Establezca la variable de entorno DEBUG en 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 comandos

Opciones de línea de comandos requeridas

El conector Linter de axe DevTools requiere las siguientes dos opciones:

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

-d, --destino **
Directorio donde Connector escribirá el informe de accesibilidad.

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

Opciones de Línea de Comandos opcionales

Es posible que se requieran varias opciones, según el servidor al que se esté conectando y qué otras funciones o formatos de informe desee utilizar.

--api-key api-key
Especifica la clave API para autorizar el linting con la instancia de SaaS axe DevTools Linter o para utilizar linting local. Consulte Cómo obtener una clave API SaaS de axe DevTools Linter para obtener más información.

--config nombre_archivo
Especifica el nombre de un archivo YAML que contiene información de configuración. También puede utilizar esta opción sin un nombre de archivo, y axe DevTools Connector seguirá los pasos en Múltiples archivos de configuración para localizar los archivos de configuración. Para obtener información sobre el archivo de configuración, consulte Archivo de configuración.

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

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

--clave de licencia clave
Especifica la clave de licencia que se utilizará para la autenticación. Comuníquese con la mesa de ayuda de Deque para obtener 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 linting local, que utiliza la máquina en la que se ejecuta el axe DevTools Connector para controlar los archivos en lugar de enviarlos a un servidor. Requiere una clave API (--api-key) o una clave de licencia (--license-key). Consulte Linting local.

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

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

--retry-backoff-limit backoff-limit
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 que se debe 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 alcance el límite de espera (especificado con --retry-backoff-limit), donde permanecerá hasta que alcance la cantidad especificada de reintentos (y falle) o se conecte al servidor sin errores.

--gravedad ** Establece el nivel de gravedad de SonarQube, predeterminado: 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 .

A continuación se muestra un archivo de configuración de ejemplo:

rules:
  image-alt: false

exclude:
  - meta-refresh.html

tags:
  - wcag2a

En el ejemplo anterior, la regla image-alt se ignorará y el archivo meta-refresh.html no se analizará con lint. Se utilizarán las reglas de la etiqueta wcag2a , como se especifica en la sección etiquetas . (Consulte Tags para obtener 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 excluiría cualquier archivo HTML en el directorio tmp o cualquiera de 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 utilizar Connector con el servidor SaaS axe DevTools Linter, puede utilizar 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 de código localmente en la computadora que ejecuta axe DevTools Connector, use la opción --local :

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