Berichte aus Axe DevTools JSON-Ergebnissen generieren

Verwenden Sie den Axe DevTools Reporter mit Playwright, um Barrierefreiheitsberichte für gescannte Seiten zu erstellen

Berichte zu generieren ist jetzt genauso einfach wie Scans durchzuführen. Mit dem Axe DevTools Reporter können Sie sofort anzeigbare HTML-Berichte, JUnit XML-Berichte zur Anzeige in CI-Testumgebungen und CSV-Berichte zur Integration in eine Vielzahl anderer Tools erstellen. Diese Anleitung beschreibt, wie Sie den Axe DevTools Reporter installieren, einrichten und verwenden.

Voraussetzungen

Um den Axe DevTools Reporter zu nutzen, benötigen Sie ein bestehendes Node.js-Projekt, in das Sie Axe DevTools und den Reporter integrieren können. Dieser Abschnitt des Leitfadens behandelt nur die Einrichtung des Reporters. Falls Sie noch keine Scans mit Axe DevTools durchführen, lesen Sie diesen Leitfaden, wie Sie Scans mit Axe DevTools durchführen können.

Installation des Reporters

Wenn Sie Ihre ~/.npmrc-Datei bereits konfiguriert haben, um Axe DevTools npm-Pakete herunterzuladen, müssen Sie nur den folgenden Befehl ausführen:

npm install @axe-devtools/reporter

Falls Sie Ihre Installationsauthentifizierung noch nicht eingerichtet haben, lesen Sie einen der Grundlagen-Installationsleitfäden.

Hinzufügen des Reporters zu Ihrem Projekt

Importieren Sie den Reporter mit der Syntax, die zu Ihrem Projekt passt:

JavaScript mit CommonJS-Modulen

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

JavaScript mit ES-Modulen

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

TypeScript

TypeScript verwendet die gleiche import-Syntax wie ES-Module. @axe-devtools/reporter liefert seine eigenen Typdeklarationen, sodass kein separates @types/-Paket installiert werden muss:

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

Um den Reporter zu verwenden, müssen auch Ihre Axe DevTools-Bibliothek und der Webdriver importiert werden.

Reporter-Optionen

Es gibt drei wichtige Entscheidungen, die Sie treffen müssen, wenn Sie den Axe DevTools Reporter verwenden

1. Wie Sie die Berichte benennen
2. Wo Sie die Berichte speichern möchten
3. In welchem Format Sie die Berichte generieren möchten

Sie können die Berichte benennen, wie Sie möchten. Beim Initialisieren des Reporters übergeben Sie einen Suite-Namen, den alle mit dieser Instanz generierten Berichte teilen werden. Jeder Bericht enthält auch einen Namen, der je Scan-Durchführung zugewiesen wird. Der Ort oder das Verzeichnis, in dem die Berichte gespeichert werden, ist ebenfalls völlig dem Benutzer überlassen. Dieser Verzeichnispfad wird auf Instanzebene festgelegt, sodass alle Berichte, die auf einer Reporterinstanz generiert werden, ein Verzeichnis gemeinsam nutzen. Die optionalen Berichtsformate sind HTML, das wir für die sofortige Benutzeransicht empfehlen, JUnit XML, das wir für die Nutzung in CI-Umgebungen empfehlen, CSV, womit die Scan-Ergebnisse in andere Tools importiert werden können, und EARL (Evaluation and Report Language), welches ein W3C EARL JSON-LD-Dokument zur maschinenlesbaren Barrierefreiheit-Berichterstattung ausgibt.

Verwendung des Reporters

Sobald der Reporter in Ihr Projekt importiert wurde, können Sie ihn initialisieren. Der Konstruktor nimmt zwei Parameter entgegen: den Bericht-Suite-Namen und das Zielverzeichnis für die Berichte. Ihre Initialisierungsanweisung sollte in etwa so aussehen:

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

Es gibt zwei Schritte, um den Reporter auszuführen, sobald ein Axe DevTools-Scan durchgeführt wurde. Zuerst müssen die Ergebnisse protokolliert werden, damit der Reporter darauf zugreifen kann. Dann verarbeitet der Reporter diese Ergebnisse in den Bericht.

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

HTML-Berichte vorab rendern

Ein HTML-Bericht ist eigenständig und rendert sich selbst, wenn er in einem Browser geöffnet wird. Bevor ein solcher erstellt wird, versucht der Reporter, ihn in ein statisches Markup vorzurendern, damit der Berichtinhalt direkt in der Datei vorhanden ist und angezeigt wird, sobald die Datei geöffnet wird.

Das Vorabrendern benötigt entweder einen Browser oder jsdom. Ab Version 4.15.0 ist jsdom eine optionale Peer-Abhängigkeit und wird nicht mehr zusammen mit dem Reporter installiert. Wählen Sie daher die für Ihre Umgebung passende Option:

• Stellen Sie einen Browser bereit. Übergeben Sie browserPath im renderOptions-Argument an buildHTML oder setzen Sie die Umgebungsvariable AXE_DEVTOOLS_REPORTER_BROWSER_PATH, die auf eine Chromium-basierte ausführbare Datei verweist. Kein Browser-Treiber oder Automatisierungsbibliothek ist erforderlich.

• Installieren Sie jsdom selbst. Dies behält das Verhalten früherer Versionen bei:

  npm install jsdom

• Verlassen Sie sich auf einen bereits auf dem Rechner installierten Browser. Wenn Sie keinen Browser bereitstellen und jsdom nicht installieren, sucht der Reporter nach einem Chromium-basierten Browser an den üblichen Installationsorten auf diesem Rechner und anschließend auf dem PATH.

Jedes Mal, wenn Sie buildHTML aufrufen, wählt der Reporter eine der folgenden Optionen in dieser Reihenfolge aus:

1. Den Browser, der durch browserPath oder AXE_DEVTOOLS_REPORTER_BROWSER_PATH angegeben ist, sofern dieser Pfad existiert.
2. jsdom, falls er installiert ist.
3. Einen Chromium-basierten Browser, der auf diesem Rechner gefunden wird, es sei denn, Sie setzen autoDetectBrowser auf false.
4. Keine der oben genannten Optionen, in welchem Fall das Vorabrendern übersprungen wird. Der Bericht wird dennoch erstellt und rendert sich, wenn er in einem Browser geöffnet wird.

Wenn ein Browser verwendet wird, läuft er mit aktiviertem Sandbox-Modus und ohne Netzwerkzugang. Berichte enthalten Inhalte von den Seiten, die Sie gescannt haben, daher lassen Sie den Sandbox-Modus aktiviert, es sei denn, Sie befinden sich in einer sicheren, eingeschränkten Umgebung, die dies nicht unterstützt. Sehen Sie RenderOptions für die vollständige Liste der Optionen.

Beispieldatei

Diese Beispieldatei verwendet die gleiche Basis wie das Tests schreiben-Beispiel, integriert jedoch zusätzlich den Reporter. Die gleiche Datei wird in JavaScript und TypeScript gezeigt.

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();
})();

Beispielausgabe

Die nachstehenden Beispiele zeigen, was jeder maschinenlesbare Bericht für einen einzigen fehlgeschlagenen Test enthält. Werte wie die Namen der Suite und des Tests stammen aus den Argumenten, die Sie dem Reporter übergeben; die restlichen Felder werden aus den Ergebnissen von axe-core ausgefüllt. Ein HTML-Bericht ist dazu gedacht, im Browser geöffnet zu werden und nicht als Quellcode gelesen zu werden, daher wird er hier nicht angezeigt.

CSV

buildCSV schreibt pro Ergebnis eine Zeile, vorausgegangen von einer Kopfzeile, die jede Spalte beschreibt. Felder, die Kommas oder Zeilenumbrüche enthalten, wie Remediation, werden in Anführungszeichen gesetzt.

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 gruppiert Ergebnisse in eine testcase pro Regel, mit einem failure-Element für jede Regel, die nicht bestanden hat. Wenn eine Regel bei mehr als einem Element fehlschlägt, werden die Vorkommen innerhalb desselben failure aufgelistet, getrennt durch einen ---------Teiler.

<?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 erzeugt ein W3C EARL- (Evaluation and Report Language) JSON-LD-Dokument für die maschinenlesbare Barrierefreiheitsberichterstattung. Der @context deklariert die verwendeten Vokabulare, und @graph enthält eine Assertion pro Ergebnis.

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

Fehlerbehebung

Eine Meldung sagt, dass das statische HTML-Vorabrendern übersprungen wurde

Wenn bei einem Lauf eine Meldung beginnt mit axe-devtools-reporter: skipping static HTML pre-rendering, hat der Reporter keinen Browser und kein installiertes jsdom gefunden. Der Bericht wird dennoch erstellt und rendert sich, wenn Sie ihn in einem Browser öffnen, daher ist dies eine Warnung und kein Fehler. Um den Bericht erneut vorzurendern, stellen Sie einen Browser bereit oder installieren Sie jsdom wie in HTML-Berichte vorab rendern beschrieben. Die Meldung wird einmal pro Lauf ausgegeben, nicht einmal pro Bericht.

Ein HTML-Bericht wird ohne seinen Inhalt geschrieben

Ein Bericht, der leer öffnet, wenn er vorgerendert wurde, bedeutet normalerweise, dass dem Browser nicht genug Zeit gegeben wurde, um ihn zu erstellen. Erhöhen Sie virtualTimeBudgetMs im renderOptions-Argument von buildHTML. Große Berichte sind die häufigste Ursache.

Ein großer Bericht schlägt mit einem Pufferüberlauf fehl

Erhöhen Sie maxBufferBytes im renderOptions-Argument von buildHTML. Es begrenzt, wie viel gerenderten Output der Reporter vom Browser akzeptiert, und ist standardmäßig auf 64 MB eingestellt.

Mehr Unterstützung erhalten

Wenn Sie Schwierigkeiten haben, Scanergebnisse zu erhalten, wenden Sie sich direkt an Ihren Deque-Ansprechpartner, kontaktieren Sie uns über unser Support-Desk oder senden Sie uns eine E-Mail. Wir helfen Ihnen gerne weiter.

Siehe auch

• Hochladen von JSON-Zugänglichkeitsergebnissen zu den Axe-Berichten beschreibt, wie Sie Ihre Ergebnisse in Axe-Berichte hochladen können.
• Erhalten eines Axe-Berichts-API-Schlüssels erklärt, wie Sie einen API-Schlüssel erhalten, um mit der Verwendung der Axe-Berichte zu beginnen.
• Erstellen und Filtern von Berichten zeigt, wie Sie Barriereberichte in CSV, XML oder HTML aus Ihren JSON-Barrierefreiheitsergebnissen erstellen können. Sie können Ihre Ausgabe auch nach Schweregrad filtern, indem Sie dieses Tool verwenden.
• Wie JSON-Ergebnisse auf der Festplatte gespeichert werden beschreibt die Namenskonventionen für JSON-Barrierefreiheitsergebnisse.
• Verwenden des CLI zum Senden von Zugänglichkeitsergebnissen an die Axe Developer Hub zeigt, wie Sie Ihre .json Ergebnisdateien zu Axe Developer Hub hochladen können.