Usando o Axe DevTools Linter com SonarQube

This page is not available in the language you requested. You have been redirected to the English version of the page.

Link to this page copied to clipboard

Como integrar o Axe DevTools Linter com o SonarQube para monitorar o código em busca de problemas de acessibilidade

Not for use with personal data

Você pode integrar o Axe DevTools Linter com o SonarQube para monitorar seu código em busca de problemas de acessibilidade. Você pode usar as ideias aqui para integrar sistemas CI/CD com o SonarQube. Na documentação do SonarQube, veja Visão Geral de integração CI para obter informações sobre como usar GitLab CI/CD, GitHub Actions, Azure Pipelines ou Bitbucket Pipelines.

Visão Geral da Integração com SonarQube

O elemento chave para integrar com o SonarQube é a ferramenta de linha de comando, Conector do Linter do Axe DevTools. A ferramenta analisa seus arquivos e cria um relatório que é então enviado para o SonarQube via a ferramenta CLI SonarScanner. As etapas detalhadas incluem:

Escanear arquivos em seus diretórios locais.
Enviar os arquivos para o servidor Axe DevTools Linter para análise ou verificar os arquivos localmente.
Coletar os resultados da verificação como um relatório JSON compatível com SonarQube.
Executar o SonarScanner CLI sobre este relatório para enviar problemas ao SonarQube como problemas externos. A ferramenta SonarScanner não analisa nenhum dos seus arquivos neste caso. Ela simplesmente reporta os problemas que o Axe DevTools Linter encontrou como problemas externos.

Os três primeiros passos são realizados pelo Axe DevTools Connector, e o último passo é realizado pelo CLI SonarScanner.

Sua própria integração CI/CD personalizada precisa realizar estas ações:

Inicie o Conector Axe DevTools Linter com os argumentos adequados de linha de comando para escanear os arquivos do seu projeto e produzir um relatório JSON compatível com SonarQube.
Inicie o CLI SonarScanner para enviar os resultados da verificação para o SonarQube.

Requisitos

Conector do Linter do Axe DevTools: Veja Usando o Conector do Linter do Axe DevTools para instruções de configuração e uso.
SonarQube: Esta integração foi testada com o SonarQube Community Build 26.4. O SonarQube alterou seu Formato Genérico de Importação de Problemas na versão 10.3, e versões futuras podem exigir o formato atualizado. Se você encontrar avisos ou problemas de importação, verifique se suas versões do Axe DevTools Linter Connector e do SonarQube são compatíveis.
CLI SonarScanner: Veja CLI SonarScanner para mais informações sobre como baixar esta ferramenta.

Configurar o SonarQube

Para configurar o SonarQube, crie um perfil, depois exclua regras redundantes do perfil para desativá-las (algumas regras em perfis recém-criados no SonarQube se sobrepõem às regras verificadas pelo Axe DevTools Linter, resultando em erros duplicados). Você pode excluir as regras sobrepostas na interface de administração do SonarQube. As seções a seguir descrevem como fazer isso.

Criar um Novo Perfil de Qualidade

Para alterar as regras, clique em Perfis de Qualidade no topo do site de administração do SonarQube. Em seguida, clique no menu suspenso Filtrar perfis por: e selecione HTML. Agora você deve ver o perfil embutido de HTML do SonarQube. É necessário duplicar esse perfil clicando no menu de engrenagem à direita do perfil e escolhendo Copiar. O SonarQube solicitará que você nomeie o novo perfil copiado. Chame o novo perfil de **Axe Linter** e clique no botão Copiar.

Agora você tem um novo perfil de qualidade HTML chamado **Axe Linter**. Escolha o menu de engrenagem para o perfil **Axe Linter** e escolha **Definir como Padrão** para que este perfil seja usado na verificação de todos os arquivos HTML.

Remover Regras Redundantes

O próximo passo é remover regras redundantes do perfil de qualidade **Axe Linter** que você criou. Na lista de regras HTML, devem existir dois perfis. O perfil **Axe Linter** e o perfil **Sonar way**. Clique no perfil **Axe Linter** para ir à página de configuração do perfil. Na parte esquerda da tela, você deve ver uma lista de diferentes tipos de regras no perfil. Clique no número no canto superior direito de **Total** e na coluna **Ativo** para editar as regras ativas.

No lado direito da tela está uma lista de regras habilitadas no perfil HTML **Axe Linter**. Desative as regras redundantes indicadas abaixo:

Tags <fieldset> devem conter um <legend>
Links não devem direcionar diretamente imagens
Imagem, área e botão com tags de imagem devem ter um atributo "alt"
Tags <th> devem ter atributos id ou scope
Células de tabela devem referenciar seus cabeçalhos
Tags <object> devem fornecer conteúdo alternativo
Tags <strong> e <em> devem ser usadas
Tags <table> devem ter uma descrição
Vídeos devem ter legendas
Mapas de imagem do lado do servidor (atributo ismap) não devem ser usados
O elemento <html> deve ter um atributo de idioma
<frames> deve ter um atributo title
HTML <table> não deve ser usado para propósitos de layout
Tabelas usadas para layout não devem incluir marcação semântica
Atributos aria-label ou aria-labelledby devem ser usados para diferenciar elementos semelhantes
Tabelas devem ter cabeçalhos

Estas regras são mencionadas no passo 5 de Deque.

important

Você precisará de uma conta Deque para acessar o artigo de suporte que inclui as regras redundantes. Veja este artigo para mais informações sobre o Centro de Ajuda e como obter uma conta.

Criar um Arquivo de Configuração do SonarQube

Você precisa criar um arquivo de configuração para o SonarScanner CLI do SonarQube. O seguinte mostra um exemplo de arquivo de configuração, **sonar-project.properties**.

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

O sonar.projectKey é o nome do projeto no SonarQube onde você gostaria que o SonarScanner reportasse os resultados.

Gerar um Token de Segurança do SonarQube

O Scanner do SonarQube precisa ser capaz de se conectar ao SonarQube para relatar os resultados. Você pode fazer isso criando um token de login na interface web do administrador do SonarQube.

Para criar um token de login, clique em Administração no topo central da tela na interface administrativa do SonarQube. Em seguida, clique no menu suspenso segurança perto do topo da tela e escolha Usuários. Escolha um usuário para reportar os resultados ao SonarQube e clique no ícone sob Tokens para criar um token de segurança para esse usuário. Na janela pop-up sob Gerar Token, digite o nome do token e clique Gerar. Salve o valor deste token (uma string hex de 32 bits) porque não há como resgatá-lo depois de fechar a janela Janela de Token. (Você pode, no entanto, gerar um novo token a qualquer momento.)

O SonarScanner CLI usa este token para reportar os resultados ao servidor. Ele deve ser configurado na variável de ambiente SONAR_TOKEN.

Executar a Integração

Depois de configurar as regras do SonarQube, criar um arquivo de configuração e gerar um token de segurança, você pode executar a integração. O processo tem duas etapas:

Execute o Conector do Linter do Axe DevTools para escanear seus arquivos de projeto e gerar um relatório compatível com o SonarQube.
Execute o CLI do SonarScanner para enviar o relatório para o SonarQube.

Gerar o Relatório do Linter

Execute Conector do Linter do Axe DevTools a partir do mesmo diretório do seu arquivo **sonar-project.properties**:

axe-linter-connector -s . -d .

Isso produz axe-linter-report.json no diretório atual. Veja Usando o Conector do Linter do Axe DevTools para opções de servidor, autenticação e outros comandos da linha de comando.

important

O Conector deve ser executado a partir do diretório base do projeto do SonarScanner para que os caminhos dos arquivos no relatório correspondam aos arquivos que o SonarQube espera.

Envie o Relatório para o SonarQube

Defina a variável de ambiente SONAR_TOKEN para o token de segurança que você gerou, então execute o SonarScanner CLI:

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

Substitua <sonarqube-server-url> pelo URL do seu servidor SonarQube (por exemplo, http://localhost:9000).

O SonarScanner CLI lê o arquivo **sonar-project.properties**, encontra o relatório especificado em sonar.externalIssuesReportPaths, e envia os problemas para o SonarQube como problemas externos.

Ver Resultados

Qualquer problema encontrado pelo Axe DevTools Linter será mostrado quando você clicar em **Problemas** na interface web do SonarQube para o seu projeto. Os problemas do Axe DevTools Linter são identificados por **AXE-LINTER-MD** para arquivos Markdown e por **AXE-LINTER-HTML** para arquivos HTML.

O Relatório

O Axe DevTools Linter Connector gera um relatório JSON que segue o Formato de Importação de Problemas Genérico do SonarQube.

Você pode alterar algumas das opções no relatório usando as opções de linha de comando do Axe DevTools Linter Connector. Veja Opções de Linha de Comando Opcionais para mais informações.