Usando a Ação GitHub do Axe DevTools Linter

Este artigo mostra como usar a ação GitHub do Axe DevTools Linter da Deque para verificar seu código em busca de erros de acessibilidade ao criar uma solicitação de pull no GitHub. Após a execução da ação, a solicitação de pull conterá comentários mostrando os erros de acessibilidade nos arquivos comprometidos.

As seções a seguir mostram os passos para configurar esta ação do GitHub com seu repositório.

Passo 1: Obter uma Chave da API (Somente SaaS)

Para a versão SaaS do Axe DevTools Linter, você precisa obter uma chave da API. Você pode conseguir uma seguindo os passos em Obtendo uma Chave de API do Axe DevTools Linter SaaS, ou pode usar uma chave da API existente na página de configurações da sua conta Axe. Se tiver problemas para obter uma chave de API, entre em contato com o atendimento ao cliente da Deque.

Passo 2: Criar um Segredo do Repositório para Sua Chave da API (Somente SaaS)

Se você estiver usando a versão SaaS do Axe DevTools Linter, precisará adicionar sua chave da API aos segredos do seu repositório, o que pode ser feito acessando a Configuração do seu repositório no GitHub. Para mais informações, veja Criando segredos criptografados para um repositório na documentação do GitHub.

Para o fluxo de trabalho de exemplo no próximo passo, os segredos devem ser chamados de:

• AXE_LINTER_API_KEY para a chave da API

Passo 3: Criar o Fluxo de Trabalho

Em seguida, é necessário criar um fluxo de trabalho para verificar seus arquivos em busca de erros de acessibilidade. Você pode criar um arquivo chamado axe-linter.yml no diretório .github/workflows do seu repositório.

Você pode criar este arquivo online como um novo fluxo de trabalho na aba Ações na página do seu repositório (clique em configure um fluxo de trabalho por você mesmo na seção Comece a usar o GitHub Actions no topo da página Ações ) ou criá-lo localmente e enviá-lo para o seu repositório.

O axe-linter-action é invocado no fluxo de trabalho quando uma solicitação de pull é criada (on: [pull_request]). O fluxo de trabalho utiliza duas dependências:

• actions/checkout@v4
• dequelabs/axe-linter-action@v1

As seções a seguir mostram exemplos de .github/workflows/axe-linter.yml que você pode usar para as versões SaaS ou on-premises do Axe DevTools Linter:

Para SaaS

A versão SaaS do fluxo de trabalho inclui o api_key parâmetro, mas não inclui o axe_linter_url parâmetro:

name: Linting for accessibility issues

on: [pull_request]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
      - uses: dequelabs/axe-linter-action@v1
        with:
          api_key: ${{ secrets.AXE_LINTER_API_KEY }}          github_token: ${{ secrets.GITHUB_TOKEN }}

Para On-Premises

A versão local do fluxo de trabalho inclui o axe_linter_url parâmetro, mas não inclui o api_key parâmetro:

name: Linting for accessibility issues

on: [pull_request]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
      - uses: dequelabs/axe-linter-action@v1
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          axe_linter_url: $AXE_LINTER_URL

O valor para axe_linter_url é lido neste exemplo a partir do ambiente de shell como AXE_LINTER_URL.

Para a versão local do Axe DevTools Linter, você não precisa de uma chave de API, mas a sua instância do Axe DevTools Linter deve ser acessível para os fluxos de trabalho do GitHub através de uma conexão de rede.

Parâmetros da Ação do GitHub

O dequelabs/axe-linter-action usa os seguintes parâmetros (especificados nos exemplos acima na cláusula with ):

Resultados do Fluxo de Trabalho

A captura de tela a seguir mostra o resultado de criar uma pull request com um arquivo que tem um erro de acessibilidade. O arquivo, bad-file.md, contém níveis de cabeçalho que vão do nível 1 ao nível 3, pulando o nível 2, o que é um erro de acessibilidade.

Solução de Problemas

Depurar problemas com as ações do GitHub pode ser desafiador porque as mensagens de erro frequentemente não representam o problema subjacente com precisão. Esta seção contém alguns exemplos de erros que você pode encontrar.

Segredo Nomeado Incorretamente (Somente SaaS)

Se o nome que você der ao segredo da sua chave de API não corresponder ao nome no fluxo de trabalho, você pode receber erros sobre um comando ausente em vez de um erro que a chave não está definida:

... line 41: Missing: command not found

Erros de Permissão

Existem muitos lugares com ações do GitHub onde as permissões podem estar incorretas. Por exemplo, se você referenciar um repositório que não é público com uma uses cláusula, você frequentemente receberá o erro de que o repositório não foi encontrado em vez de que você não tem acesso a ele:

fatal: repository 'name' not found

Error: Resource not accessible by integration

Se o seu fluxo de trabalho falhar ao rodar com o erro, Resource not accessible by integration, você pode adicionar as seguintes permissões ao seu fluxo de trabalho para corrigi-lo:

permissions:
  contents: read
  pull-requests: read 

Seu fluxo de trabalho completo ficaria assim:

on: [pull_request]

permissions:
  contents: read
  pull-requests: read

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
      - uses: dequelabs/axe-linter-action@v1
        with:
          api_key: ${{ secrets.AXE_LINTER_API_KEY }}
          github_token: ${{ secrets.GITHUB_TOKEN }}

Arquivos Verificados pela Ação

Arquivos com essas extensões serão verificados quanto a erros de acessibilidade:

• .js
• .jsx
• .tsx
• .html
• .vue
• .md
• .markdown

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ê gostaria de saber mais sobre como prevenir que arquivos com erros de acessibilidade sejam comitados no Git, veja Usando um Pré-Commit Hook do Git.