Generazione di Rapporti dai Risultati JSON di Axe DevTools

Utilizza il reporter di Axe DevTools con Playwright per produrre rapporti di accessibilità per le pagine scansionate

Generare rapporti è ora facile quanto eseguire scansioni. Con il reporter di Axe DevTools, puoi generare rapporti HTML immediatamente visualizzabili, rapporti JUnit XML per visualizzazione negli ambienti di test CI e rapporti CSV da importare in una moltitudine di altri strumenti. Questa guida illustra come installare, configurare e usare il reporter di Axe DevTools.

Prerequisiti

Per utilizzare il reporter Axe DevTools, è necessario avere un progetto Node.js esistente in cui integrare sia Axe DevTools che il reporter. Questa parte della guida copre solo la configurazione del reporter, quindi se non hai ancora Axe DevTools che esegue scansioni, leggi questa guida per sapere come eseguire le scansioni con Axe DevTools.

Installazione del Reporter

Se hai già configurato il tuo file ~/.npmrc per scaricare i pacchetti npm di Axe DevTools, tutto ciò che devi fare è eseguire il comando:

npm install @axe-devtools/reporter

Se non hai già configurato l'autenticazione dell'installazione, leggi uno dei guide all'installazione di base.

Aggiunta del Reporter al tuo Progetto

Importa il reporter con la sintassi che corrisponde al tuo progetto:

JavaScript con moduli CommonJS

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

JavaScript con moduli ES

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

TypeScript

TypeScript utilizza la stessa sintassi import dei moduli ES. @axe-devtools/reporter include le proprie dichiarazioni di tipo, quindi non c'è un pacchetto @types/ separato da installare:

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

Per utilizzare il reporter, anche la tua libreria Axe DevTools e il webdriver dovranno essere importato e inizializzato.

Opzioni del Reporter

Ci sono tre scelte principali che devi fare quando usi il reporter di Axe DevTools

1. Come nominare i rapporti
2. Dove memorizzare i rapporti
3. In quale formato generare i rapporti

Puoi nominare i rapporti come preferisci. Quando inizializzi il reporter, gli passi un nome di suite che tutti i rapporti generati con quell'istanza condivideranno. Ogni rapporto include anche un nome assegnato a ciascuna scansione. Anche la posizione, o directory, in cui verranno memorizzati i rapporti è completamente a discrezione dell'utente. Questo percorso directory è impostato anche a livello di istanza, quindi tutti i rapporti generati su un'istanza di reporter condivideranno una directory. I formati opzionali dei rapporti sono HTML, che consigliamo per la visualizzazione immediata da parte dell'utente, JUnit XML, che consigliamo per l'uso in ambienti CI, CSV, che consente di importare i risultati delle scansioni in altri strumenti, e EARL (Evaluation and Report Language), che genera un documento W3C EARL JSON-LD per rapporti di accessibilità leggibili da macchina.

Utilizzo del Reporter

Una volta importato il reporter nel tuo progetto, puoi inizializzarlo. Il costruttore accetta due argomenti: il nome della suite di rapporti e la directory di destinazione per i rapporti. La tua dichiarazione di inizializzazione dovrebbe apparire in questo modo:

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

Ci sono due passaggi per eseguire il reporter una volta che una scansione Axe DevTools è stata eseguita. Prima, i risultati devono essere registrati affinché il reporter possa accedervi. Poi, il reporter elabora questi risultati per comporre il rapporto.

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

Visualizzazione anticipata dei report HTML

Un report HTML è autonomo e si visualizza automaticamente quando viene aperto in un browser. Prima di scriverlo, il reporter cerca anche di pre-renderizzarlo in un markup statico, in modo che il contenuto del report sia presente nel file stesso e si mostri non appena il file viene aperto.

La pre-renderizzazione necessita di un browser o jsdom. A partire dalla versione 4.15.0, jsdom è una dipendenza opzionale e non è più installata insieme al reporter, quindi scegli quella che meglio si adatta al tuo ambiente:

• Fornire un browser. Passare browserPath nell'argomento renderOptions a buildHTML, o impostare la variabile d'ambiente AXE_DEVTOOLS_REPORTER_BROWSER_PATH, puntando a un eseguibile basato su Chromium. Non è necessario alcun driver del browser o libreria di automazione.

• Installa jsdom da solo. Questo mantiene il comportamento delle versioni precedenti:

  npm install jsdom

• Affidarsi a un browser già installato sulla macchina. Se non fornisci un browser e non installi jsdom, il reporter cerca un browser basato su Chromium nei luoghi di installazione standard di questa macchina e poi su PATH.

Ogni volta che chiami buildHTML, il reporter sceglie una delle seguenti opzioni nell'ordine:

1. Il browser fornito da browserPath o AXE_DEVTOOLS_REPORTER_BROWSER_PATH, se quel percorso esiste.
2. jsdom, se è installato.
3. Un browser basato su Chromium trovato su questa macchina, a meno che non imposti autoDetectBrowser su false.
4. Nessuna delle opzioni precedenti, nel qual caso la pre-renderizzazione viene saltata. Il report viene comunque scritto e si visualizza quando viene aperto in un browser.

Quando viene utilizzato un browser, esso viene eseguito con il suo sandbox abilitato e senza accesso alla rete. I report contengono contenuti presi dalle pagine che hai scansionato, quindi lascia il sandbox abilitato, a meno che tu non sia in un ambiente fidato e limitato che non possa supportarlo. Vedi RenderOptions per l'elenco completo delle opzioni.

File di esempio

Questo file di esempio utilizza la stessa base dell'esempio esempio di scrittura di test, ma integra anche il reporter. Lo stesso file è mostrato in JavaScript e in 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();
})();

Esempio di output

Gli esempi seguenti mostrano cosa contiene ogni report in formato leggibile dalla macchina per un singolo controllo fallito. Valori come il nome della suite e dei test provengono dagli argomenti passati al reporter; i campi rimanenti sono riempiti dai risultati di axe-core. Un report HTML è destinato ad essere aperto in un browser piuttosto che letto come sorgente, quindi non viene mostrato qui.

CSV

buildCSV scrive una riga per risultato, preceduta da una riga di intestazione che descrive ciascuna colonna. I campi che contengono virgole o interruzioni di linea, come Remediation, sono quotati.

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 raggruppa i risultati in un testcase per regola, con un elemento failure per ogni regola che non ha superato il test. Quando una regola fallisce su più di un elemento, le occorrenze sono elencate all'interno dello stesso failure, separate da un divisore --------.

<?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 EARL (Evaluation and Report Language) W3C per il reporting di accessibilità in formato leggibile dalla macchina. Il @context dichiara i vocabolari utilizzati, e @graph contiene un'asserzione per ogni risultato.

{
  "@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"]
      }
    }
  ]
}

Risoluzione dei problemi

Un messaggio indica che la pre-renderizzazione dello statico HTML è stata saltata

Se un'esecuzione stampa un messaggio che inizia con axe-devtools-reporter: skipping static HTML pre-rendering, il reporter non ha trovato alcun browser né alcun jsdom installato. Il report viene comunque scritto e si visualizza quando lo apri in un browser, quindi questo è un avvertimento piuttosto che un errore. Per pre-renderizzare nuovamente il report, fornisci un browser o installa jsdom come descritto in Visualizzazione anticipata dei report HTML. Il messaggio viene stampato una volta per esecuzione, non una volta per report.

Un report HTML viene scritto senza il suo contenuto

Un report che si apre vuoto quando è stato pre-renderizzato solitamente significa che al browser non è stato dato abbastanza tempo per costruirlo. Aumenta virtualTimeBudgetMs nell'argomento renderOptions a buildHTML. I report di grandi dimensioni sono la causa comune.

Un report di grandi dimensioni fallisce a causa di un overflow del buffer

Aumenta maxBufferBytes nell'argomento renderOptions a buildHTML. Limita la quantità di output renderizzato che il reporter accetta dal browser, e il valore predefinito è 64 MB.

Ottenere ulteriore aiuto

Se hai difficoltà a ottenere i risultati delle scansioni, contatta direttamente il tuo rappresentante Deque, raggiungici tramite il nostro desk di supporto, o inviaci un'email. Saremo felici di aiutarti.

Vedi Anche

• Caricamento dei risultati di accessibilità JSON su Axe Reports descrive come caricare i tuoi risultati su Axe Reports.
• Ottenere una chiave API per Axe Reports spiega come ottenere una chiave API per iniziare a utilizzare Axe Reports.
• Creazione e filtraggio dei report mostra come puoi creare report di accessibilità in formato CSV, XML o HTML dai tuoi risultati di accessibilità JSON. Puoi anche filtrare il tuo output per gravità utilizzando questo strumento.
• Come vengono memorizzati i risultati JSON sul disco descrive le convenzioni di denominazione dei file per i risultati di accessibilità JSON.
• Utilizzo della CLI per inviare i risultati di accessibilità a Axe Developer Hub mostra come puoi caricare i tuoi file di risultati .json su Axe Developer Hub.