Usando Axe DevTools Linter com Bitbucket Pipelines

Você pode submeter seu código ao Axe DevTools Linter para ser verificado quanto a problemas de acessibilidade como parte de uma build do Bitbucket Pipelines. Ao contrário do GitHub, não há um pipe dedicado do Bitbucket para o Axe DevTools Linter, então este guia mostra como invocar o Conector Axe DevTools Linter diretamente como um passo em seu bitbucket-pipelines.yml.

Requisitos

• Um repositório Bitbucket com Pipelines habilitados.
• Node.js e npm disponíveis na imagem do pipeline (a imagem padrão do Bitbucket Pipelines inclui ambos) para que o Conector possa ser instalado com npm. Veja Instalando o Conector Axe DevTools Linter como um pacote npm.
• Uma chave de API ou uma chave de licença para autorizar o Conector. Veja Escolhendo a Configuração Correta para saber como seu modelo de implementação (SaaS, nuvem privada ou local) determina qual delas você deve usar.

Etapa 1: Adicione uma Variável de Repositório para sua Chave

Adicione sua chave como uma variável de repositório protegida para que não seja exposta nos logs do seu pipeline. Vá para a página de Configurações do repositório do seu repositório, depois para Variáveis do repositório, e adicione uma das seguintes opções, marcadas como Protegido:

• AXE_LINTER_API_KEY para uma chave de API
• AXE_LINTER_LICENSE_KEY para uma chave de licença

Para mais informações, veja a própria documentação do Bitbucket sobre variáveis e segredos do repositório.

Etapa 2: Adicione um Passo no Pipeline

Adicione um passo ao seu bitbucket-pipelines.yml que instale o Conector e o execute com a opção --local. A lintagem local analisa seus arquivos no próprio runner do pipeline em vez de enviá-los para um servidor, funcionando da mesma forma independentemente se sua implementação subjacente é SaaS, nuvem privada ou local.

Com uma Chave de Licença

Usar uma chave de licença significa que o Conector não realiza nenhuma chamada de rede:

image: node:20

pipelines:
  default:
    - step:
        name: Lint for accessibility issues
        script:
          - npm install -g @axe-devtools/axe-linter-connector
          - axe-linter-connector -s . -d . --license-key $AXE_LINTER_LICENSE_KEY --local

Com uma Chave de API

Usar uma chave de API ainda exige que o Conector acesse um servidor de autenticação para validar a chave e registrar o uso, mesmo com --local:

image: node:20

pipelines:
  default:
    - step:
        name: Lint for accessibility issues
        script:
          - npm install -g @axe-devtools/axe-linter-connector
          - axe-linter-connector -s . -d . --api-key $AXE_LINTER_API_KEY --local

Para o Axe DevTools Linter SaaS, o servidor de autenticação padrão (https://axe.deque.com) é usado automaticamente. Clientes de nuvem privada precisam definir a variável de ambiente AXE_SERVICE_URL para a URL de autenticação de sua instância de nuvem privada antes de executar o Conector.

Lintagem Baseada em Servidor (Alternativa)

Se você não quiser fazer a lintagem localmente, pode enviar arquivos para um servidor Axe DevTools Linter omitindo --local e especificando --url. Qual servidor você pode alcançar depende do seu modelo de implementação:

• SaaS: os runners hospedados do Bitbucket podem alcançar o servidor SaaS da Deque sem configuração extra, já que ele já está acessível pela internet.
• Local: não exponha seu servidor local à internet apenas para que os runners hospedados do Bitbucket possam alcançá-lo. Em vez disso, use um runner auto-hospedado do Bitbucket para que seu passo do pipeline seja executado dentro da sua própria rede, da mesma forma que seu servidor local é alcançado por outras ferramentas internas.

Resultados do Passo do Pipeline

O Conector escreve um relatório de acessibilidade no diretório de destino (axe-linter-report.json por padrão), contendo os erros específicos de acessibilidade encontrados, incluindo nome de arquivo e número da linha. Violações de acessibilidade por si só não alteram o código de saída do Conector nem falham o passo do Bitbucket; o Conector só sai com código diferente de zero se houver um problema com a verificação em si, como uma opção ausente, um servidor inalcançável ou uma chave rejeitada. Veja Códigos de Saída para a lista completa.

Próximos Passos

Para informações sobre as regras usadas pelo Axe DevTools Linter para verificar seu código, veja Regras de Acessibilidade. Se você quiser alimentar o relatório no SonarQube, veja Usando Axe DevTools Linter com SonarQube.