Rapporten genereren van Axe DevTools JSON-resultaten

Gebruik de Axe DevTools rapportagefunctie met Playwright om toegankelijkheidsrapporten te produceren voor gescande pagina's

Rapporten genereren is nu net zo eenvoudig als het uitvoeren van scans. Met de Axe DevTools rapportagefunctie kun je direct leesbare HTML-rapporten genereren, JUnit XML-rapporten voor weergave in CI-testomgevingen en CSV-rapporten om in een veelheid aan andere tools te importeren. Deze gids beschrijft hoe je de Axe DevTools rapportagefunctie installeert, instelt en gebruikt.

Vereisten

Om de Axe DevTools-verzorger te gebruiken, heb je een bestaand Node.js-project nodig om Axe DevTools evenals de verzorger in te integreren. Dit deel van de gids behandelt alleen de installatie van de verzorger, dus als je nog geen scans uitvoert met Axe DevTools, lees dan deze gids over hoe je scans met Axe DevTools uitvoert.

Installeren van de Reporter

Als je je ~/.npmrc bestand al hebt geconfigureerd om Axe DevTools npm-pakketten te downloaden, hoef je alleen maar het volgende commando uit te voeren:

npm install @axe-devtools/reporter

Als je de authenticatie voor de installatie nog niet hebt geconfigureerd, lees dan een van de basis installatiehandleidingen.

De Reporter toevoegen aan je Project

Importeer de verzorger met de syntax die bij je project past:

JavaScript met CommonJS-modules

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

JavaScript met ES-modules

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

TypeScript

TypeScript gebruikt dezelfde import syntax als ES-modules. @axe-devtools/reporter levert zijn eigen typedeclaraties, dus er is geen afzonderlijk @types/ pakket om te installeren:

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

Om de rapportagefunctie te gebruiken, moeten je Axe DevTools-bibliotheek en webdriver ook geïmporteerd worden.

Reportermogelijkheden

Er zijn drie belangrijke keuzes die je moet maken bij het gebruik van de Axe DevTools rapportagefunctie

1. Hoe je de rapporten gaat noemen
2. Waar je de rapporten gaat opslaan
3. In welk formaat je de rapporten gaat genereren

Je kunt de rapporten noemen zoals je wilt. Wanneer je de reporter initialiseert, geef je een suitenaam om mee te geven, die alle rapporten die met die instantie worden gegenereerd, zullen delen. Elk rapport bevat ook een naam die aan elke scan afzonderlijk wordt toegewezen. De locatie of directory waar de rapporten worden opgeslagen, is ook volledig aan de gebruiker. Deze locatie is ook ingesteld op instansieniveau, zodat alle rapporten die op één reporterinstantie worden gegenereerd, een directory delen. De optionele rapportformaten zijn HTML, die we aanbevelen voor directe gebruikersweergave, JUnit XML, die we aanbevelen voor gebruik in CI-omgevingen, CSV, waarmee de scanresultaten kunnen worden geïmporteerd in andere tools, en EARL (Evaluation and Report Language), die een W3C EARL JSON-LD-document output voor machinaal leesbare toegankelijkheidsrapportage.

De Reporter gebruiken

Zodra de reporter in je project is geïmporteerd, kun je deze initialiseren. De constructor neemt twee argumenten: de reportsuitennaam en de doelmap voor de rapporten. Je initialisatie-uitspraak moet er ongeveer zo uitzien:

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

Er zijn twee stappen om de rapportagefunctie te gebruiken nadat een Axe DevTools-scan is uitgevoerd. Eerst moeten de resultaten worden gelogd zodat de rapportagefunctie er toegang toe heeft. Vervolgens verwerkt de rapportagefunctie deze resultaten in het rapport.

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

HTML-rapporten vooraf renderen

Een HTML-rapport is zelfvoorzienend en rendert zichzelf wanneer het in een browser wordt geopend. Voordat het wordt geschreven, probeert de rapportgenerator het ook vooraf te renderen naar statische markup, zodat de inhoud van het rapport in het bestand zelf aanwezig is en direct wordt weergegeven zodra het bestand wordt geopend.

Vooraf renderen vereist ofwel een browser ofwel jsdom. Vanaf versie 4.15.0 is jsdom een optionele peer-afhankelijkheid en wordt het niet langer samen met de rapportgenerator geïnstalleerd, dus kies degene die het beste bij je omgeving past:

• Lever een browser. Geef browserPath door in het renderOptions-argument aan buildHTML, of stel de omgevingsvariabele AXE_DEVTOOLS_REPORTER_BROWSER_PATH in, die wijst naar een Chromium-gebaseerde uitvoerbare file. Er is geen browserdriver of automatiseringsbibliotheek nodig.

• Installeer jsdom zelf. Dit behoudt het gedrag van eerdere versies:

  npm install jsdom

• Vertrouw op een browser die al op de machine is geïnstalleerd. Als je geen browser levert en jsdom niet installeert, zoekt de rapportgenerator naar een Chromium-gebaseerde browser op de standaardinstallatielocaties van deze machine en vervolgens op de PATH.

Elke keer dat je buildHTML aanroept, kiest de rapportgenerator een van deze in de volgende volgorde:

1. De browser opgegeven door browserPath of AXE_DEVTOOLS_REPORTER_BROWSER_PATH, als dat pad bestaat.
2. jsdom, als het is geïnstalleerd.
3. Een Chromium-gebaseerde browser gevonden op deze machine, tenzij je autoDetectBrowser instelt op false.
4. Geen van bovenstaande, in welk geval vooraf renderen wordt overgeslagen. Het rapport wordt nog steeds geschreven en rendert nog steeds wanneer het in een browser wordt geopend.

Wanneer een browser wordt gebruikt, draait deze met zijn sandbox ingeschakeld en zonder netwerktoegang. Rapporten bevatten inhoud die afkomstig is van de pagina's die je hebt gescand, dus laat de sandbox ingeschakeld tenzij je je in een vertrouwde, beperkte omgeving bevindt die het niet kan ondersteunen. Zie RenderOptions voor de volledige lijst met opties.

Voorbeeldbestand

Dit voorbeeldbestand gebruikt dezelfde basis als het tests schrijven voorbeeld, maar integreert ook de verzorger. Hetzelfde bestand wordt getoond in JavaScript en 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();
})();

Voorbeelduitvoer

De onderstaande voorbeelden laten zien wat elk machineleesbaar rapport bevat voor één enkele mislukte controle. Waarden zoals de suite- en testnamen komen van de argumenten die je de verzorger meegeeft; de overige velden worden gevuld met de resultaten van axe-core. Een HTML-rapport is bedoeld om in een browser te worden geopend in plaats van als bron te lezen, dus het wordt hier niet getoond.

CSV

buildCSV schrijft één rij per resultaat, voorafgegaan door een koprij die elke kolom beschrijft. Velden die komma's of regeleinden bevatten, zoals Remediation, worden geciteerd.

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 groepeert resultaten in een testcase per regel, met een failure element voor elke regel die niet slaagde. Wanneer een regel faalt op meer dan één element, worden de voorkomens binnen dezelfde failure opgesomd, gescheiden door een -------- scheidingsteken.

<?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 produceert een W3C EARL (Evaluation and Report Language) JSON-LD document voor machineleesbare toegankelijkheidsrapportages. De @context verklaart de gebruikte vocabulaires, en @graph houdt één bewering per resultaat.

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

Problemen oplossen

Er verschijnt een bericht dat statische HTML-vooraf rendering is overgeslagen

Als een run een bericht afdrukt dat begint met axe-devtools-reporter: skipping static HTML pre-rendering, heeft de rapportgenerator geen browser en geen geïnstalleerde jsdom gevonden. Het rapport wordt nog steeds geschreven en rendert nog steeds wanneer je het in een browser opent, dus dit is een waarschuwing in plaats van een fout. Om het rapport opnieuw vooraf te renderen, lever je een browser of installeer je jsdom zoals beschreven in HTML-rapporten vooraf renderen. Het bericht wordt eenmaal per run afgedrukt, niet eenmaal per rapport.

Een HTML-rapport is geschreven zonder zijn inhoud

Een rapport dat leeg opent wanneer het vooraf is gerenderd, betekent meestal dat er niet genoeg tijd aan de browser is gegeven om het op te bouwen. Verhoog virtualTimeBudgetMs in het renderOptions-argument aan buildHTML. Grote rapporten zijn de gebruikelijke oorzaak.

Een groot rapport faalt met een buffer-overflow

Verhoog maxBufferBytes in het renderOptions-argument aan buildHTML. Dit beperkt hoeveel gerenderde output de rapportgenerator accepteert van de browser en standaard is dat 64 MB.

Meer hulp krijgen

Als je problemen ondervindt bij het verkrijgen van scanresultaten, neem dan direct contact op met je Deque-vertegenwoordiger, bereik ons via onze support desk, of stuur ons een e-mail. We helpen je graag.

Zie ook

• JSON-toegankelijkheidsresultaten uploaden naar Axe Reports beschrijft hoe u uw resultaten naar Axe Reports uploadt.
• Een Axe Reports API-sleutel verkrijgen legt uit hoe u een API-sleutel kunt verkrijgen om te beginnen met het gebruik van Axe Reports.
• Rapporten maken en filteren laat zien hoe u toegankelijkheidsrapporten kunt maken in CSV, XML of HTML op basis van uw JSON-toegankelijkheidsresultaten. U kunt uw output ook filteren op ernst met dit hulpmiddel.
• Hoe JSON-resultaten op schijf worden opgeslagen beschrijft de naamgevingsconventies voor JSON-toegankelijkheidsresultaten.
• De CLI gebruiken om toegankelijkheidsresultaten naar Axe Developer Hub te sturen laat zien hoe u uw .json resultatenbestanden kunt uploaden naar Axe Developer Hub.