Gerando Relatórios a partir dos Resultados JSON do Axe DevTools

Use o relator do Axe DevTools com o Playwright para produzir relatórios de acessibilidade para as páginas analisadas

Gerar relatórios agora é tão fácil quanto executar as análises. Com o relator do Axe DevTools, você pode gerar relatórios HTML que são visualizáveis imediatamente, relatórios JUnit XML para visualização em ambientes de teste CI, e relatórios CSV para importar em uma variedade de outras ferramentas. Este guia detalha como instalar, configurar e usar o relator do Axe DevTools.

Pré-requisitos

Para usar o Axe DevTools reporter, você precisa de um projeto Node.js existente para integrar tanto o Axe DevTools quanto o reporter. Esta parte do guia cobre apenas a configuração do reporter, portanto, se você ainda não tem o Axe DevTools fazendo verificações, leia este guia sobre como executar verificações com o Axe DevTools.

Instalando o Reporter

Se você já configurou seu arquivo ~/.npmrc para baixar os pacotes npm do Axe DevTools, tudo o que você precisa fazer é executar o comando:

npm install @axe-devtools/reporter

Se você ainda não configurou a autenticação da instalação, leia um dos guias básicos de instalação.

Adicionando o Reporter ao seu Projeto

Importe o reporter com a sintaxe que corresponde ao seu projeto:

JavaScript com módulos CommonJS

const { Reporter } = require('@axe-devtools/reporter');

JavaScript com módulos ES

import { Reporter } from '@axe-devtools/reporter';

TypeScript

TypeScript usa a mesma sintaxe import que módulos ES. @axe-devtools/reporter traz suas próprias declarações de tipos, portanto, não há um pacote @types/ separado para instalar:

import { Reporter } from '@axe-devtools/reporter';

Para usar o relator, sua biblioteca Axe DevTools e o webdriver também precisarão ser importados.

Opções do Reporter

Existem três principais escolhas que você precisa fazer ao usar o relator do Axe DevTools

1. Como nomear os relatórios
2. Onde armazenar os relatórios
3. Em que formato gerar os relatórios

Você pode nomear os relatórios como preferir. Quando você inicia o reporter, você passa um nome de suíte que todos os relatórios gerados com essa instância compartilharão. Cada relatório também inclui um nome atribuído com base em cada escaneamento. O local, ou diretório, onde os relatórios serão armazenados também é completamente de escolha do usuário. Esse local de diretório também é definido no nível da instância, então todos os relatórios gerados em uma instância de reporter compartilharão um diretório. Os formatos opcionais de relatório são HTML, que recomendamos para visualização imediata do usuário, JUnit XML, que recomendamos para uso em ambientes de CI, CSV, que permite importar os resultados do escaneamento em outras ferramentas, e EARL (Evaluation and Report Language), que gera um documento W3C EARL JSON-LD para relatórios de acessibilidade legíveis por máquina.

Usando o Reporter

Uma vez que o reporter é importado para o seu projeto, você pode inicializá-lo. O construtor leva dois argumentos: o nome do conjunto de relatórios e o diretório de destino para os relatórios. Sua declaração de inicialização deve se parecer com esta:

const reporter = new Reporter('<suite-name>', '<dir-name>');

Há duas etapas para executar o relator após uma varredura do Axe DevTools. Primeiro, os resultados devem ser registrados para que o relator possa acessá-los. Depois, o relator processa esses resultados no relatório.

reporter.logTestResult('<scan-name>', <results-object>);
reporter.buildHTML('<scan-dir>');

Pré-renderização de relatórios HTML

Um relatório HTML é autossuficiente e se renderiza quando aberto em um navegador. Antes de escrevê-lo, o gerador de relatórios também tenta pré-renderizá-lo em uma marcação estática, para que o conteúdo do relatório esteja presente no próprio arquivo e seja exibido assim que o arquivo for aberto.

A pré-renderização precisa de um navegador ou de jsdom. A partir da versão 4.15.0, jsdom é uma dependência peer opcional e não é mais instalada junto com o gerador de relatórios, então escolha o que melhor se adapta ao seu ambiente:

• Forneça um navegador. Passe browserPath no argumento renderOptions para buildHTML, ou defina a variável de ambiente AXE_DEVTOOLS_REPORTER_BROWSER_PATH, apontando para um executável baseado em Chromium. Não é necessário driver de navegador ou biblioteca de automação.

• Instale jsdom você mesmo. Isso mantém o comportamento das versões anteriores:

  npm install jsdom

• Confie em um navegador já instalado na máquina. Se você não fornecer um navegador e não instalar jsdom, o gerador de relatórios procura por um navegador baseado em Chromium nos locais padrão de instalação desta máquina e, em seguida, em PATH.

Cada vez que você chama buildHTML, o gerador de relatórios escolhe um desses na seguinte ordem:

1. O navegador fornecido por browserPath ou AXE_DEVTOOLS_REPORTER_BROWSER_PATH, se esse caminho existir.
2. jsdom, se estiver instalado.
3. Um navegador baseado em Chromium encontrado nesta máquina, a menos que você defina autoDetectBrowser como false.
4. Nenhuma das opções acima, caso em que a pré-renderização é ignorada. O relatório ainda é escrito e ainda é renderizado quando aberto em um navegador.

Quando um navegador é usado, ele é executado com sua sandbox habilitada e sem acesso à rede. Os relatórios contêm conteúdo retirado das páginas que você escaneou, então deixe a sandbox habilitada, a menos que você esteja em um ambiente confiável e restrito que não possa suportá-la. Veja RenderOptions para a lista completa de opções.

Arquivo de exemplo

Este arquivo de exemplo usa a mesma base do exemplo escrever testes, mas também integra o reporter. O mesmo arquivo é mostrado em JavaScript e TypeScript.

JavaScript

const rimraf = require('rimraf');
const { AxeDevToolsBuilder } = require('@axe-devtools/playwright');
const playwright = require('playwright');
const { Reporter } = require('@axe-devtools/reporter');

(async () => {
  rimraf.sync('./a11y_results/*');

  const browser = await playwright.chromium.launch();
  const context = await browser.newContext();
  const page = await context.newPage();

  const reporter = new Reporter('playwright', './a11y_results');

  await page.goto('https://dequeuniversity.com/demo/mars/');

  const results = await new AxeDevToolsBuilder({ page }).analyze();

  reporter.logTestResult('tested-page', results);
  reporter.buildHTML('./a11y_results');
  await browser.close();
})();

TypeScript

import rimraf from 'rimraf';
import { AxeDevToolsBuilder } from '@axe-devtools/playwright';
import * as playwright from 'playwright';
import { Reporter } from '@axe-devtools/reporter';
import type { AxeResults } from 'axe-core';

(async () => {
  rimraf.sync('./a11y_results/*');

  const browser = await playwright.chromium.launch();
  const context = await browser.newContext();
  const page = await context.newPage();

  const reporter = new Reporter('playwright', './a11y_results');

  await page.goto('https://dequeuniversity.com/demo/mars/');

  const results: AxeResults = await new AxeDevToolsBuilder({ page }).analyze();

  reporter.logTestResult('tested-page', results);
  reporter.buildHTML('./a11y_results');
  await browser.close();
})();

Resultado do exemplo

Os exemplos abaixo mostram o que cada relatório legível por máquina contém para uma única verificação falha. Valores como os nomes da suíte e dos testes vêm dos argumentos que você passa para o reporter; os campos restantes são preenchidos a partir dos resultados do axe-core. Um relatório HTML deve ser aberto em um navegador em vez de ser lido como fonte, portanto, não é mostrado aqui.

CSV

buildCSV escreve uma linha por resultado, precedida por uma linha de cabeçalho descrevendo cada coluna. Campos que contêm vírgulas ou quebras de linha, como Remediation, são citados.

Page URL,Page Title,Outcome,Impact,Code Snippet,Selector,Remediation,Manual,Rule ID,Help,Description,Help URL,Standard,WCAG 2 Success Criteria,Section 508 Paragraph,Tags,Date,axe-core,Needs Review,IGT,Found By,Test Title,Share URL
https://dequeuniversity.com/demo/mars/,My Test Suite,Failed,Serious,<h3>Be Bold...</h3>,"a[href=""mars2.html?a=be_bold""] > h3","Fix any of the following:
  Element has insufficient color contrast of 4.31 (foreground color: #ff9999, background color: #344b6e, font size: 13.5pt (18px), font weight: normal). Expected contrast ratio of 4.5:1",false,color-contrast,Elements must meet minimum color contrast ratio thresholds,Ensure the contrast between foreground and background colors meets WCAG 2 AA minimum contrast ratio thresholds,https://dequeuniversity.com/rules/axe/4.12/color-contrast,WCAG 2.0 Level AA,1.4.3 Contrast (Minimum),,"cat.color, wcag2aa, wcag143, TTv5, TT13.c, EN-301-549, EN-9.1.4.3, ACT, RGAAv4, RGAA-3.2.1",2026-07-10T18:11:41.859Z,4.12.1,No,,,My Test Suite,

JUnit XML

buildJUnitXML agrupa resultados em um testcase por regra, com um elemento failure para cada regra que não passou. Quando uma regra falha em mais de um elemento, as ocorrências são listadas dentro do mesmo failure, separadas por um divisor --------.

<?xml version="1.0" encoding="utf-8"?>
<testsuites>
<testsuite name="My Test Suite" package="axe-result" timestamp="2026-07-10T11:11:42-0700">
<properties>
<property name="platform.userAgent" value="" />
<property name="platform.testMachine" value="" />
<property name="testSubject.fileName" value="https://dequeuniversity.com/demo/mars/" />
<property name="testSubject.lineNum" value="-1" />
</properties>
<testcase name="color-contrast">
<failure message="Ensure the contrast between foreground and background colors meets WCAG 2 AA minimum contrast ratio thresholds
https://dequeuniversity.com/rules/axe/4.12/color-contrast" impact="serious">
<![CDATA[https://dequeuniversity.com/demo/mars/]]>
CSS Path: <![CDATA[a[href="mars2.html?a=be_bold"] > h3]]>
HTML: <![CDATA[<h3>Be Bold...</h3>]]>
</failure>
</testcase>
</testsuite>
</testsuites>

EARL

buildEARL produz um documento W3C EARL (Evaluation and Report Language) JSON-LD para relatórios de acessibilidade legíveis por máquina. O @context declara os vocabulários usados, e @graph mantém uma asserção por resultado.

{
  "@context": {
    "@vocab": "http://www.w3.org/ns/earl#",
    "earl": "http://www.w3.org/ns/earl#",
    "WCAG2": "http://www.w3.org/TR/WCAG21/#",
    "dct": "http://purl.org/dc/terms/",
    "sch": "https://schema.org/",
    "source": "dct:source",
    "title": "dct:title",
    "assertedBy": { "@type": "@id" },
    "outcome": { "@type": "@id" },
    "mode": { "@type": "@id" },
    "isPartOf": { "@id": "http://purl.org/dc/terms/isPartOf", "@type": "@id" }
  },
  "@graph": [
    {
      "@type": "Assertion",
      "mode": "earl:automatic",
      "subject": {
        "@type": ["earl:TestSubject", "sch:WebPage"],
        "source": "https://dequeuniversity.com/demo/mars/"
      },
      "assertedBy": "https://github.com/dequelabs/axe-core/releases/tag/v4.12.1",
      "result": {
        "@type": "TestResult",
        "outcome": "earl:failed"
      },
      "test": {
        "@type": "TestCase",
        "title": "color-contrast",
        "@id": "https://dequeuniversity.com/rules/axe/4.12/color-contrast",
        "isPartOf": ["WCAG2:contrast-minimum"]
      }
    }
  ]
}

Solução de problemas

Uma mensagem diz que a pré-renderização do HTML estática foi ignorada

Se uma execução imprimir uma mensagem começando com axe-devtools-reporter: skipping static HTML pre-rendering, o gerador de relatórios não encontrou navegador e nenhum jsdom instalado. O relatório ainda é escrito e ainda é renderizado quando você o abre em um navegador, então isso é um aviso em vez de um erro. Para pré-renderizar o relatório novamente, forneça um navegador ou instale jsdom como descrito em Pré-renderização de relatórios HTML. A mensagem é impressa uma vez por execução, não uma vez por relatório.

Um relatório HTML é escrito sem seu conteúdo

Um relatório que abre vazio quando foi pré-renderizado geralmente significa que o navegador não teve tempo suficiente para construí-lo. Aumente virtualTimeBudgetMs no argumento renderOptions para buildHTML. Relatórios grandes são a causa comum.

Um relatório grande falha com um estouro de buffer

Aumente maxBufferBytes no argumento renderOptions para buildHTML. Ele limita quanto da saída renderizada o gerador de relatórios aceita do navegador, e o padrão é 64 MB.

Obter mais ajuda

Se você tiver problemas para obter os resultados das análises, entre em contato diretamente com seu representante Deque, alcance-nos via nosso balcão de suporte, ou nos envie um email. Ficaremos felizes em ajudar.

Veja também

• Carregando resultados de acessibilidade JSON para o Axe Reports descreve como carregar seus resultados no Axe Reports.
• Obtendo uma chave de API do Axe Reports explica como obter uma chave de API para começar a usar o Axe Reports.
• Criando e Filtrando Relatórios mostra como você pode criar relatórios de acessibilidade em CSV, XML ou HTML a partir dos seus resultados de acessibilidade em JSON. Você também pode filtrar sua saída por gravidade usando esta ferramenta.
• Como Resultados JSON são Armazenados no Disco descreve as convenções de nomenclatura de arquivos para resultados de acessibilidade em JSON.
• Usando o CLI para enviar resultados de acessibilidade para o Axe Developer Hub mostra como você pode enviar seus arquivos de resultados .json para Axe Developer Hub.