Generación de informes a partir de resultados JSON de Axe DevTools

Usa el generador de informes de Axe DevTools junto con Playwright para producir informes de accesibilidad de las páginas escaneadas

Generar informes ahora es tan fácil como ejecutar escaneos. Con el generador de informes de Axe DevTools, puedes generar informes en HTML visibles inmediatamente, informes en XML JUnit para ver en entornos de pruebas de CI y informes en CSV para importar en una multitud de otras herramientas. Esta guía detalla cómo instalar, configurar y usar el generador de informes de Axe DevTools.

Requisitos previos

Para utilizar el generador de informes de Axe DevTools, necesitas un proyecto existente de Node.js para integrar tanto Axe DevTools como el generador de informes. Esta parte de la guía solo cubre la configuración del generador de informes, así que si aún no tienes Axe DevTools realizando análisis, lee esta guía sobre cómo ejecutar análisis con Axe DevTools.

Instalación del reportero

Si ya configuraste tu archivo ~/.npmrc para descargar los paquetes npm de Axe DevTools, todo lo que necesitas hacer es ejecutar el comando:

npm install @axe-devtools/reporter

Si aún no has configurado la autenticación de tu instalación, lee una de las guías básicas de instalación.

Añadir el reportero a tu proyecto

Importa el generador de informes con la sintaxis que coincida con tu proyecto:

JavaScript con módulos CommonJS

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

JavaScript con ES modules

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

TypeScript

TypeScript utiliza la misma sintaxis import que los ES modules. @axe-devtools/reporter incluye sus propias declaraciones de tipos, por lo que no hay un paquete @types/ separado para instalar:

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

Para usar el generador de informes, tu biblioteca de Axe DevTools y el controlador webdriver también deberán estar importados.

Opciones del reportero

Hay tres decisiones principales que debes tomar al usar el generador de informes de Axe DevTools

1. Qué nombre dar a los informes
2. Dónde almacenar los informes
3. En qué formato generar los informes

Puedes nombrar los informes como prefieras. Cuando inicializas el reportero, le pasas un nombre de suite que todos los informes generados con esa instancia compartirán. Cada informe también incluye un nombre asignado en cada escaneo. La ubicación, o directorio, donde se almacenarán los informes también depende completamente del usuario. Esta ubicación de directorio también se establece a nivel de instancia, por lo que todos los informes generados en una instancia del reportero compartirán un directorio. Los formatos opcionales de informe son HTML, que recomendamos para la visualización inmediata por el usuario, JUnit XML, que recomendamos para su uso en entornos CI, CSV, que permite importar los resultados del escaneo en otras herramientas, y EARL (Lenguaje de Evaluación e Informe), que produce un documento W3C EARL JSON-LD para informes de accesibilidad legibles por máquina.

Usando el reportero

Una vez que el reportero está importado en tu proyecto, puedes inicializarlo. El constructor toma dos argumentos: el nombre de la suite de informes y el directorio de destino para los informes. Tu declaración de inicialización debería verse algo así:

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

Hay dos pasos para ejecutar el generador de informes una vez que se ha ejecutado un escaneo de Axe DevTools. Primero, se deben registrar los resultados para que el generador de informes los acceda. Luego, el generador procesa estos resultados en el informe.

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

Pre-renderizar informes HTML

Un informe HTML es autónomo y se renderiza cuando se abre en un navegador. Antes de escribir uno, el generador de informes también intenta pre-renderizarlo en un marcado estático, para que el contenido del informe esté presente en el archivo y se muestre tan pronto como se abra el archivo.

La pre-renderización requiere un navegador o jsdom. A partir de la versión 4.15.0, jsdom es una dependencia opcional necesaria y ya no se instala junto con el generador de informes, por lo que elige lo que se adapte a tu entorno:

• Proporciona un navegador. Pasa browserPath como argumento en renderOptions a buildHTML, o establece la variable de entorno AXE_DEVTOOLS_REPORTER_BROWSER_PATH, apuntando a un ejecutable basado en Chromium. No se necesita un controlador de navegador o biblioteca de automatización.

• Instala jsdom tú mismo. Esto mantiene el comportamiento de las versiones anteriores:

  npm install jsdom

• Confía en un navegador ya instalado en la máquina. Si no proporcionas un navegador y no instalas jsdom, el generador de informes busca un navegador basado en Chromium en las ubicaciones estándar de instalación de esta máquina y luego en el PATH.

Cada vez que llamas a buildHTML, el generador de informes elige uno de estos en el siguiente orden:

1. El navegador proporcionado por browserPath o AXE_DEVTOOLS_REPORTER_BROWSER_PATH, si esa ruta existe.
2. jsdom, si está instalado.
3. Un navegador basado en Chromium encontrado en esta máquina, a menos que configures autoDetectBrowser como false.
4. Ninguno de los anteriores, en cuyo caso se omite la pre-renderización. El informe todavía se escribe y todavía se renderiza cuando se abre en un navegador.

Cuando se utiliza un navegador, se ejecuta con su espacio aislado habilitado y sin acceso a la red. Los informes contienen contenido tomado de las páginas que escaneaste, así que deja el espacio aislado habilitado a menos que estés en un entorno confiable y restringido que no pueda soportarlo. Consulta RenderOptions para ver la lista completa de opciones.

Archivo de ejemplo

Este archivo de muestra utiliza la misma base que el ejemplo escribir pruebas, pero también integra el generador de informes. El mismo archivo se muestra en JavaScript y en 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();
})();

Ejemplo de salida

Los ejemplos a continuación muestran lo que contiene cada informe legible por máquina para un solo chequeo fallido. Los valores como los nombres del conjunto y la prueba provienen de los argumentos que proporcionas al generador de informes; los campos restantes se rellenan con los resultados de axe-core. Un informe HTML está destinado a ser abierto en un navegador en lugar de ser leído como código fuente, por lo que no se muestra aquí.

CSV

buildCSV escribe una fila por resultado, precedida por una fila de encabezado que describe cada columna. Los campos que contienen comas o saltos de línea, como Remediation, están entrecomillados.

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 los resultados en un testcase por regla, con un elemento failure para cada regla que no pasó. Cuando una regla falla en más de un elemento, las ocurrencias se enumeran dentro del mismo failure, separadas por un 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 produce un documento JSON-LD W3C EARL (Evaluación y Lenguaje de Informe) para crear informes de accesibilidad legibles por máquina. El @context declara los vocabularios utilizados, y @graph contiene una afirmación 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"]
      }
    }
  ]
}

Solución de problemas

Un mensaje indica que se omitió la pre-renderización de HTML estático

Si una ejecución imprime un mensaje que comienza con axe-devtools-reporter: skipping static HTML pre-rendering, el generador de informes no encontró ningún navegador ni jsdom instalado. El informe aún se escribe y aún se renderiza cuando lo abres en un navegador, por lo que esta es una advertencia en lugar de un error. Para pre-renderizar el informe nuevamente, proporciona un navegador o instala jsdom como se describe en Pre-renderizar informes HTML. El mensaje se imprime una vez por ejecución, no una vez por informe.

Un informe HTML se escribe sin su contenido

Un informe que se abre vacío cuando se pre-renderizó generalmente significa que no se le dio al navegador suficiente tiempo para construirlo. Aumenta virtualTimeBudgetMs en el argumento renderOptions a buildHTML. Los informes grandes son la causa común.

Un informe grande falla con un desbordamiento de búfer

Aumenta maxBufferBytes en el argumento renderOptions a buildHTML. Esto limita la cantidad de salida renderizada que el generador de informes acepta desde el navegador, y por defecto es de 64 MB.

Obteniendo más ayuda

Si tienes problemas para obtener resultados de los escaneos, contacta directamente a tu representante de Deque, comunícanos a través de nuestro centro de soporte, o envíanos un correo electrónico. Estaremos encantados de ayudar.

Ver también

• Cargando Resultados de Accesibilidad JSON a Axe Reports describe cómo cargar tus resultados en Axe Reports.
• Obteniendo una Clave API de Axe Reports explica cómo obtener una clave API para comenzar a usar Axe Reports.
• Crear y Filtrar Informes muestra cómo puedes crear informes de accesibilidad en CSV, XML o HTML a partir de tus resultados de accesibilidad JSON. También puedes filtrar tu salida por severidad utilizando esta herramienta.
• Cómo se Almacenan los Resultados JSON en el Disco describe las convenciones de nomenclatura de archivos para resultados de accesibilidad JSON.
• Usando la CLI para Enviar Resultados de Accesibilidad al Centro de Desarrolladores de Axe muestra cómo puedes subir tus archivos de resultados .json a Centro de Desarrolladores de Axe.