Usando a Ação GitHub do Axe Developer Hub

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

Verifique automaticamente PRs e commits para defeitos de acessibilidade

Not for use with personal data

Requer:

note

Para outros pipelines de CI/CD (como aqueles no GitLab, Bitbucket, ou CircleCI) ou ao usar o Axe DevTools para Web APIs/CLI, você pode usar o Axe Developer Hub Commit Status API como base para sua própria integração.

Visão Geral

A GitHub Action do Axe Developer Hub permite configurar fluxos de trabalho do GitHub para projetos web integrando o Axe Watcher, a fim de bloquear commits e pull requests caso contenham quaisquer erros de acessibilidade.

Quando o seu suíte de testes modificada é executado, ele associa os resultados de acessibilidade a um SHA de commit Git e envia essas informações para os servidores da Deque. A ação do GitHub é executada após que a sua suíte de testes é executada, e consulta os servidores da Deque pelos resultados de acessibilidade associados ao SHA do commit mais recente da branch atual.

Os novos e resolvidos contadores de problemas que a Action relata usam a linha de base do commit anterior que possui uma varredura na mesma branch, não na branch padrão. Somente commits contra os quais sua suíte de testes realmente foi executada têm uma varredura, então esse commit base pode estar vários commits de distância. Se aquele commit executou um conjunto diferente de testes, os contadores refletirão a diferença de cobertura ao invés de uma alteração genuína; veja Melhores Práticas para Comparações Precisas.

Configuração

  1. Crie uma Variável de Ambiente para o ID do Seu Projeto - Recomendamos que você armazene seu ID do projeto em uma variável de ambiente ou outra variável do GitHub. Para este exemplo, armazenaremos o ID do projeto como uma variável de ambiente chamada PROJECT_ID.

  2. Crie um Segredo para a Sua Chave de API - Para este exemplo, o segredo criado é chamado de AXE_DEV_HUB_API_KEY, com sua chave de API pessoal como valor, mas você pode nomear o segredo como desejar. Ele deve ser referenciado pelo mesmo nome no trabalho do fluxo de trabalho. Sua chave de API é uma credencial: sempre armazene-a como um segredo do GitHub Actions em vez de codificá-la diretamente no arquivo de fluxo de trabalho.

  3. Adicione Verificações de Acessibilidade à Sua Suíte de Testes - Certifique-se de que você completou as etapas em configuração do projeto para integrar verificações de acessibilidade na suíte de testes usada no seu pipeline de CI/CD (Axe Watcher).

  4. Modifique Seu Fluxo de Trabalho Atual - Você precisa modificar o fluxo de trabalho atual do seu executor de testes em .github/workflows e adicionar a ação do GitHub após ao trabalho que executa sua suíte de testes.

Exemplo de Trabalho

O trabalho seguindo sua ação de suíte de testes deve executar a GitHub Action do Axe Developer Hub. Consulte o exemplo a seguir:

jobs:

# ...
# your-CI-test
# ...

# Add the following new job:
# Be sure to replace <choose_latest_tag> with the appropriate version tag
  axe-dev-hub:
    runs-on: ubuntu-latest
    needs: your-CI-test
    steps:
      - uses: actions/checkout@v5
      - uses: dequelabs/axe-devhub-action@<choose_latest_tag>
        with:
          api_key: ${{ secrets.axe_DEV_HUB_API_KEY }}
          project_id: ${{ env.PROJECT_ID }}

O trabalho axe-dev-hub no exemplo depende do trabalho que executa sua suíte de testes, especificado com a linha needs: your-CI-test. Certifique-se de atualizar esta linha para corresponder ao nome do trabalho que executa sua suíte de testes.

Você pode usar múltiplos parâmetros de entrada para a GitHub Action. Por exemplo, você pode habilitar o limiar de a11y usando enable_a11y_threshold: true. Uma lista completa de parâmetros de entrada pode ser encontrada no README da GitHub Action do Axe Developer Hub.

note

Você não precisa definir o parâmetro server_url se criou seu projeto em axe.deque.com. Se sua organização usa uma instância regional, nuvem privada ou implantação local do Axe Developer Hub, você deve definir server_url para a URL base dessa instância (por exemplo, https://axe-eu.deque.com).

Resultados

A GitHub Action define vários parâmetros de saída, incluindo uma contagem de problemas de acessibilidade que foram detectados, problemas que foram resolvidos, e problemas que ultrapassam o limiar de a11y.

Se você não habilitou o limiar de a11y, a GitHub Action falhará sempre que mais de zero erros de acessibilidade estiverem presentes. Se habilitado, apenas violações que ultrapassam o limiar de a11y farão a GitHub Action falhar. Saiba mais sobre o uso do limiar de a11y para personalizar o Axe Developer Hub de acordo com o que sua organização deseja priorizar.

A falha da GitHub Action anexará um comentário semelhante ao abaixo ao seu pull request, podendo bloquear a mesclagem.

Uma mensagem de exemplo que a GitHub Action anexa a uma solicitação de push quando erros de acessibilidade foram encontrados.

Clique no link no comentário do pull request para revisar as informações de defeitos de acessibilidade para aquele commit no Axe Developer Hub.

Solução de Problemas

Você pode receber um erro como o seguinte:

Error: Resource not accessible by integration

Verifique se você tem as permissões necessárias na página de configurações para ações. Você precisa de permissões de leitura e escrita para permitir que a ação adicione comentários a pull requests. Para mais granularidade, você pode optar por usar um GITHUB_TOKEN diferente para a GitHub Action. Adicione este valor ao parâmetro de entrada github_token.

Exemplo de Fluxo de Trabalho

Se você ainda não tem um fluxo de trabalho que executa sua suíte de testes, pode usar o exemplo de fluxo de trabalho como ponto de partida para criar seu próprio executor de testes.

O fluxo de trabalho exemplo é chamado Testes (tests.yml) e é executado em qualquer commit ou pull request. O trabalho que executa o conjunto de testes modificado, cypress, mostra como executar um conjunto de testes do Cypress. O trabalho seguinte no exemplo, axe-dev-hub, é uma invocação da ação Axe Developer Hub GitHub.

O trabalho de seu conjunto de testes deve sempre ser executado antes a ação Axe Developer Hub GitHub.

tip

O diretório de exemplo contém um projeto de teste completo com o qual você pode experimentar.

Referências

Is this page helpful?

Help us improve this page

Still need help?