Usar Axe DevTools Linter con SonarQube

Puedes integrar Axe DevTools Linter con SonarQube para monitorear tu código en busca de problemas de accesibilidad. Puedes usar las ideas aquí para integrar sistemas CI/CD con SonarQube. En la documentación de SonarQube, consulta el Visión general de integración CI para obtener información sobre el uso de GitLab CI/CD, GitHub Actions, Azure Pipelines o Bitbucket Pipelines.

Visión General de la Integración con SonarQube

El elemento clave para integrarse con SonarQube es la herramienta de línea de comandos, Conector de Axe DevTools Linter. Esta herramienta escanea tus archivos y crea un informe que luego se carga en SonarQube a través de la herramienta CLI de SonarScanner. Los pasos en detalle incluyen:

1. Escanear archivos en tus directorios locales.
2. Enviar los archivos al Servidor de Axe DevTools Linter para análisis o analizar los archivos localmente.
3. Recoger los resultados del análisis como un informe JSON compatible con SonarQube.
4. Ejecutar SonarScanner CLI sobre este informe para enviar problemas a SonarQube como problemas externos. La herramienta SonarScanner no escanea realmente ninguno de tus archivos en este caso. Simplemente informa los problemas que Axe DevTools Linter encontró como problemas externos.

Los primeros tres pasos son realizados por Axe DevTools Connector, y el último paso es realizado por el CLI de SonarScanner.

Tu propia integración personalizada de CI/CD necesita realizar estas acciones:

1. Lanzar Axe DevTools Linter Connector con los argumentos adecuados de línea de comandos para escanear los archivos de tu proyecto y producir un informe JSON compatible con SonarQube.
2. Iniciar el CLI de SonarScanner para enviar los resultados del análisis a SonarQube.

Requisitos

• Conector de Axe DevTools Linter: Consulta Usar Conector de Axe DevTools Linter para las instrucciones de configuración y uso.
• SonarQube: Esta integración ha sido probada con SonarQube Community Build 26.4. SonarQube cambió su Formato Genérico de Importación de Problemas en la versión 10.3, y las versiones futuras pueden requerir el formato actualizado. Si encuentras advertencias o problemas de importación, verifica que tus versiones de Axe DevTools Linter Connector y SonarQube sean compatibles.
• CLI de SonarScanner: Consulta CLI de SonarScanner para obtener más información sobre cómo descargar esta herramienta.

Configurar SonarQube

Para configurar SonarQube, crea un perfil y luego elimina las reglas redundantes del perfil para desactivarlas (algunas reglas en los perfiles recién creados en SonarQube se superponen con las reglas verificadas por Axe DevTools Linter, lo que resulta en errores duplicados). Puedes eliminar las reglas superpuestas en la interfaz de administración de SonarQube. Las siguientes secciones describen cómo hacer esto.

Crear un Nuevo Perfil de Calidad

Para cambiar las reglas, haz clic en Perfiles de Calidad en la parte superior del sitio web de administración de SonarQube. Luego haz clic en el menú desplegable Filtrar perfiles por: y selecciona HTML. Ahora deberías ver el perfil HTML incorporado de SonarQube. Necesitas duplicar ese perfil haciendo clic en el menú desplegable de engranaje en el lado derecho del perfil y eligiendo Copiar. SonarQube te pedirá que nombres el perfil copiado recientemente. Llama al nuevo perfil Axe Linter y haz clic en el botón Copiar.

Ahora tienes un nuevo perfil de calidad HTML llamado Axe Linter. Elige el menú desplegable de engranaje para el perfil Axe Linter y elige Establecer como Predeterminado para que este perfil se utilice para verificar todos los archivos HTML.

Eliminar Reglas Redundantes

El siguiente paso es eliminar las reglas redundantes del perfil de Calidad Axe Linter que creaste. En la lista de reglas HTML, debería haber dos perfiles. El perfil Axe Linter y el perfil Método Sonar. Haz clic en el perfil Axe Linter para ir a la página de configuración del perfil. En la parte izquierda de la pantalla, deberías ver una lista de diferentes tipos de reglas en el perfil. Haz clic en el número en la parte superior derecha de Total y en la columna Activo para editar las reglas activas.

En el lado derecho de la pantalla hay una lista de reglas habilitadas en el perfil HTML Axe Linter. Desactiva las reglas redundantes indicadas a continuación:

• Las etiquetas <fieldset> deben contener un <legend>
• Los enlaces no deben apuntar directamente a imágenes
• Las etiquetas de imagen, área y botón con imagen deben tener un atributo "alt"
• Las etiquetas <th> deben tener atributos id o scope
• Las celdas de las tablas deben referenciar sus encabezados
• Las etiquetas <object> deben proporcionar contenido alternativo
• Las etiquetas <strong> y <em> deben ser utilizadas
• Las etiquetas <table> deben tener una descripción
• Los videos deben tener subtítulos
• No se deben usar mapas de imagen del lado del servidor (atributo ismap)
• El elemento <html> debe tener un atributo de idioma
• <frames> debe tener un atributo title
• No se debe usar <table> de HTML para propósitos de diseño
• Las tablas utilizadas para el diseño no deben incluir marcado semántico
• Se deben usar los atributos aria-label o aria-labelledby para diferenciar elementos similares
• Las tablas deben tener encabezados

Estas reglas se mencionan en el paso 5 de este artículo de soporte de Deque.

Crear un archivo de configuración de SonarQube

Necesitas crear un archivo de configuración para el CLI del SonarScanner de SonarQube. A continuación se muestra un ejemplo de archivo de configuración, sonar-project.properties.

sonar.projectKey=Test-Deque
sonar.externalIssuesReportPaths=axe-linter-report.json

El sonar.projectKey es el nombre del proyecto en SonarQube donde te gustaría que SonarScanner reportara los resultados.

Generar un Token de Seguridad de SonarQube

El escáner de SonarQube necesita poder conectarse a SonarQube para reportar resultados. Puedes hacer esto creando un token de inicio de sesión en la interfaz web de administración de SonarQube.

Para crear un token de inicio de sesión, haz clic en Administración en la parte superior central de la pantalla en la interfaz web de administración de SonarQube. Luego haz clic en el desplegable Seguridad cerca de la parte superior de la pantalla y elige Usuarios. Elige un usuario para reportar resultados a SonarQube y haz clic en el icono debajo de Tokens para crear un token de seguridad para ese usuario. En Generar Token en la ventana emergente, escribe el nombre del token y haz clic en Generar. Guarda el valor de este token (una cadena hexadecimal de 32 bits) porque no hay manera de volver a mostrarlo después de cerrar la ventana Token. (Sin embargo, puedes generar un nuevo token en cualquier momento.)

El CLI del SonarScanner utiliza este token para reportar los resultados al servidor. Debe configurarse en la variable de entorno SONAR_TOKEN.

Ejecutar la Integración

Una vez que hayas configurado las reglas de SonarQube, creado un archivo de configuración y generado un token de seguridad, puedes ejecutar la integración. El proceso tiene dos pasos:

1. Ejecuta Axe DevTools Linter Connector para escanear los archivos de tu proyecto y generar un informe compatible con SonarQube.
2. Ejecuta SonarScanner CLI para subir el informe a SonarQube.

Generar el Informe del Linter

Ejecuta Conector de Linter de Axe DevTools desde el mismo directorio que tu archivo sonar-project.properties:

axe-linter-connector -s . -d .

Esto produce axe-linter-report.json en el directorio actual. Consulta Uso del Conector de Linter de Axe DevTools para servidor, autenticación y otras opciones de línea de comandos.

Subir el informe a SonarQube

Establezca la variable de entorno SONAR_TOKEN en el token de seguridad que generó, luego ejecute la CLI de SonarScanner:

export SONAR_TOKEN=<your-sonarqube-token>
sonar-scanner -Dsonar.host.url=<sonarqube-server-url>

Reemplace <sonarqube-server-url> con la URL de su servidor SonarQube (por ejemplo, http://localhost:9000).

La CLI de SonarScanner lee el archivo sonar-project.properties, encuentra el informe especificado en sonar.externalIssuesReportPaths y sube los problemas a SonarQube como problemas externos.

Ver resultados

Cualquier problema encontrado por Axe DevTools Linter se mostrará al hacer clic en Problemas en la interfaz web de SonarQube para su proyecto. Los problemas de Axe DevTools Linter se identifican por AXE-LINTER-MD para archivos Markdown y por AXE-LINTER-HTML para archivos HTML.

El informe

El conector de Axe DevTools Linter genera un informe JSON que sigue el Formato de importación de problemas genéricos de SonarQube.

Puede cambiar algunas de las opciones en el informe utilizando las opciones de línea de comandos del conector de Axe DevTools Linter. Consulte Opciones de línea de comandos opcionales para más información.