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

Not for use with personal data

Você pode integrar o Axe DevTools Linter com o SonarQube para monitorar seu código quanto a problemas de acessibilidade. Você pode usar as ideias aqui para integrar sistemas CI/CD com o SonarQube. Na documentação do SonarQube, veja a Visão Geral da integração CI para informações sobre o uso do 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 Axe DevTools Linter. A ferramenta escaneia seus arquivos e cria um relatório que é então enviado ao SonarQube via a ferramenta CLI SonarScanner. Os passos em detalhe incluem:

Escanear arquivos em seus diretórios locais.
Enviar os arquivos para o Servidor Axe DevTools Linter para verificação ou verificar os arquivos localmente.
Coletar os resultados da verificação como um relatório JSON compatível com SonarQube.
Executar o CLI SonarScanner sobre este relatório para enviar problemas para o SonarQube como problemas externos. A ferramenta SonarScanner não escaneia realmente nenhum de seus arquivos neste caso. Ela apenas 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 Axe DevTools Linter: Veja Usando o Conector Axe DevTools Linter para instruções de configuração e uso.
SonarQube: Esta integração foi testada com o SonarQube Community Build 26.4. O SonarQube mudou o 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 Conector Axe DevTools Linter 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 Filtrar perfis por: dropdown e selecione HTML. Agora você deve ver o perfil HTML padrão do SonarQube. Você precisa duplicar esse perfil clicando na engrenagem dropdown do lado direito do perfil e escolhendo Copiar. O SonarQube solicitará que você nomeie o novo perfil copiado. Chame o novo perfil de Axe Linter e clique em Copiar botão.

Você agora tem um novo perfil de qualidade HTML chamado **Axe Linter**. Escolha a engrenagem para o perfil **Axe Linter** e escolha **Definir como Padrão** para que esse perfil seja utilizado para verificar 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, deve haver dois perfis. O perfil **Axe Linter** e o perfil **Sonar way** . Clique no perfil **Axe Linter** para ir para a 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:

<fieldset> tags 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"
<th> tags devem ter id ou scope atributos
Células de tabela devem referenciar seus cabeçalhos
<object> tags devem fornecer conteúdo alternativo
<strong> e <em> tags devem ser usadas
<table> tags devem ter uma descrição
Vídeos devem ter legendas
Mapas de imagem do lado do servidor (ismap atributo) não devem ser usados
<html> elemento deve ter um atributo de idioma
<frames> deve ter um title atributo
HTML <table> não deve ser usado para fins de layout
Tabelas usadas para layout não devem incluir marcação semântica
aria-label ou aria-labelledby atributos devem ser usados para diferenciar elementos semelhantes
Tabelas devem ter cabeçalhos

Essas regras são mencionadas no passo 5 deste artigo de Suporte da 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 CLI do SonarScanner do SonarQube. A seguir está 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 relatasse 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 centro superior da tela na interface web do administrador do SonarQube. Em seguida, clique no segurança dropdown próximo ao topo da tela e escolha Usuários. Escolha um usuário para relatar os resultados ao SonarQube e clique no ícone em Tokens para criar um token de segurança para esse usuário. Em Gerar Token na janela popup, digite o nome do token e clique em Gerar. Salve o valor deste token (uma string hexadecimal de 32 bits) porque não há como exibi-lo novamente após você fechar a Janela de Token . (Você pode, no entanto, gerar um novo token a qualquer momento.)

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

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 o Conector do Linter do Axe DevTools a partir do mesmo diretório que seu 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 parâmetros de 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

Configure a SONAR_TOKEN variável de ambiente para o token de segurança que você gerou, em seguida, execute o CLI do SonarScanner:

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

Substituir <sonarqube-server-url> com o 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 carrega os problemas no 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 Conector Axe DevTools Linter 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 Conector Axe DevTools Linter. Consulte Opções de Linha de Comando Opcionais para mais informações.