Recuperar Resultados do Axe Watcher com axe-watcher-results

axe-watcher-results recupera os resultados de uma análise concluída do Axe Watcher do Axe Developer Hub e os transforma em um sinal de aprovação/rejeição para um pipeline de CI.

Pré-requisitos

Antes de executar axe-watcher-results, você precisa:

• Um Chave de API do Axe Developer Hub (um UUID).
• O ID do projeto para o projeto do Axe Developer Hub para o qual a análise foi enviada (um UUID).
• Uma análise concluída do Axe Watcher para o commit que você deseja verificar.

Instalar

axe-watcher-results é distribuído como um binário autônomo para Linux, macOS e Windows. Baixe o binário para sua plataforma na página Downloads (o acesso requer uma licença do axe DevTools for Web), depois siga Preparar Binários após o Download para torná-lo executável e, no macOS, para limpar o atributo de quarentena.

Coloque o binário no seu PATH (ou faça referência a ele pelo caminho) para que você possa executá-lo como axe-watcher-results.

Autenticar

axe-watcher-results lê sua chave de API do Axe Developer Hub da variável de ambiente AXE_DEVHUB_API_KEY. Defina-a uma vez antes de executar qualquer comando — no seu shell para uso local, ou no armazenamento seguro do sistema de CI para um pipeline:

export AXE_DEVHUB_API_KEY=<your-api-key>

Os exemplos abaixo assumem que esta variável está definida.

Procurar Resultados para um Commit (Gating de CI)

Execute axe-watcher-results sessions get com o ID do seu projeto e um SHA de commit do Git:

axe-watcher-results sessions get <project-id> <commit-sha>

• <project-id>: o UUID do projeto.
• <commit-sha>: um SHA de commit do Git de 7 a 40 caracteres que já possui uma análise concluída do Axe Watcher.

Esta é a consulta que controla uma compilação: se a contagem de problemas da execução exceder o limite de acessibilidade do seu projeto, axe-watcher-results sai com o código 10 (veja Códigos de Saída). Por exemplo, com --format=json:

{
  "project": "your-project-name",
  "project-id": "7347af86-ff4e-4e14-8957-8fc2255ed4ec",
  "commit-sha": "e220798b6558cdfc7c3e592378be67e1e78e7377",
  "run-url": "https://axe.deque.com/axe-watcher/projects/7347af86-ff4e-4e14-8957-8fc2255ed4ec/branches/main/compare/0d4a85a2-9e6f-44ef-b814-fee8412abeb0/0d4a85a2-9e6f-44ef-b814-fee8412abeb0?settings_hash=0757ca72c5e10951ddbb2ede4edab06e&issues_over_a11y_threshold=2",
  "issues": 17,
  "new-issues": 17,
  "resolved-issues": 0,
  "issues-over-a11y-threshold": 2,
  "page-states": 2,
  "difference-in-page-states": 0,
  "created-at": "2026-07-07T18:13:00.641Z",
  "message": "Run exceeded the a11y threshold by 2."
}

Se você analisar a saída em um script, use --format=json: os nomes dos campos acima são estáveis. A saída padrão --format=text é destinada a humanos lendo logs de compilação, não para análise.

Procurar Resultados para uma Sessão

Você também pode procurar uma análise específica pelo ID da sessão em vez de um SHA de commit:

axe-watcher-results sessions get <project-id> <session-id>

<session-id> é um UUID de sessão. axe-watcher-results distingue um ID de sessão de um SHA de commit pelo seu formato (um UUID versus uma string hexadecimal de 7 a 40 caracteres), então você pode passá-lo na mesma posição. O argumento <project-id> ainda é necessário e validado, mesmo que uma consulta de sessão resolva seu projeto a partir da sessão e chave de API ao invés do argumento.

Use --detail=summary (o padrão) para contagens de problemas por gravidade e regra, ou --detail=full para obter o documento completo do resultado como JSON bruto (isso ignora --format).

--format=json --detail=summary se parece com isto:

{
  "report_id": "14c16b50-a6ce-46ab-9974-0ad3b94eafde",
  "source": {
    "product_name": "axe-devtools-html",
    "product_component_name": "axe-devtools-watcher",
    "product_version": "4.0.0"
  },
  "test_details": {
    "test_id": "0d4a85a2-9e6f-44ef-b814-fee8412abeb0",
    "start_date": "2026-07-07T18:13:00.641Z",
    "end_date": "2026-07-07T18:13:05.472Z"
  },
  "commit": {
    "sha": "e220798b6558cdfc7c3e592378be67e1e78e7377",
    "author": "Jane Doe",
    "author_email": "jane@example.com",
    "message": "fix: correct login form labels",
    "branch_name": "main",
    "tag": "",
    "repository_url": "https://github.com/your-org/your-repo"
  },
  "devhub_summary": {
    "issue_count_total": 17,
    "issue_count_by_impact": {
      "critical": 0,
      "serious": 2,
      "moderate": 15,
      "minor": 0
    },
    "issue_count_by_rule": [
      {
        "severity": "serious",
        "rule_id": "color-contrast",
        "rule_help": "Elements must meet minimum color contrast ratio thresholds",
        "rule_help_url": "https://dequeuniversity.com/rules/axe/4.11/color-contrast?application=axeAPI",
        "count": 2
      }
    ]
  }
}

Se a análise ainda estiver processando, axe-watcher-results consulta o servidor (até 5 minutos) e escreve o progresso para stderr; se a análise não terminar de processar a tempo, ela termina com o código 11.

Listar Sessões para um Projeto

O subcomando sessions list lista as sessões de análise registradas de um projeto, o que é útil para encontrar um ID de sessão para buscar:

axe-watcher-results sessions list <project-id>

Filtre os resultados com --git-branch, --commit-sha, --git-url, --created-after/--created-before (timestamps ISO-8601), --created-by-user-email, e --is-canonical-source. Use --page-size (1-100) e --after para percorrer os resultados. sessions list também aceita --format, --network-timeout-seconds, e --verbose/-v, que se comportam da mesma maneira que para sessions get.

Opções

Essas opções se aplicam ao comando sessions get (buscas de commit-SHA e ID de sessão):

--version (no comando raiz axe-watcher-results) imprime a versão axe-watcher-results e sai; --help está disponível em todos os comandos.

A saída vai para stdout como texto limpo ou JSON; mensagens de progresso e erro vão para stderr, para que você possa capturar stdout para logs de construção sem processamento extra.

Exemplo de Limitação em CI

Execute axe-watcher-results como uma etapa após a conclusão da sua análise Axe Watcher, usando um SHA de commit para que o código de saída reflita o limite de a11y:

# AXE_DEVHUB_API_KEY is provided by your CI system's secret store
axe-watcher-results sessions get --format=json "$PROJECT_ID" "$GIT_COMMIT_SHA"

Um código de saída diferente de zero falha a etapa chamada. Veja Códigos de Saída para entender o que cada código significa e como responder a ele.

Códigos de Saída

Recuperando do Código de Saída 12

Código de saída 12 significa que o commit tem resultados de varredura, mas o Axe Developer Hub não tem nada para compará-los. Axe Developer Hub seleciona uma linha de base nesta ordem:

1. Uma sessão anterior no mesmo SHA do commit.
2. A sessão mais recente em um SHA diferente no mesmo ramo.
3. A própria sessão atual, mas apenas se a sessão for canônica (veja Usar Axe Watcher em Ambientes de Integração Contínua (CI)).

Se nenhum destes estiver disponível e a sessão não for canônica, o Axe Developer Hub retorna um 404 e axe-watcher-results encerra com o código 12. Para recuperar:

• Execute novamente a varredura do Axe Watcher com CI=true configurado, para que a sessão se torne canônica e realize a auto-comparação em um início a frio.
• Execute uma varredura adicional, contra este commit ou um commit anterior no mesmo ramo, para estabelecer uma linha de base.