Générer des rapports à partir des résultats JSON d'Axe DevTools

Utilisez le rapporteur Axe DevTools avec Playwright pour produire des rapports d'accessibilité pour les pages scannées

Générer des rapports est maintenant aussi simple que de lancer des scans. Avec le rapporteur Axe DevTools, vous pouvez générer des rapports HTML immédiatement consultables, des rapports JUnit XML pour une visualisation dans les environnements de tests CI, et des rapports CSV à importer dans une multitude d'autres outils. Ce guide explique comment installer, configurer et utiliser le rapporteur Axe DevTools.

Prérequis

Pour utiliser le rapporteur Axe DevTools, vous avez besoin d'un projet Node.js existant dans lequel intégrer à la fois Axe DevTools et le rapporteur. Cette partie du guide couvre uniquement la configuration du rapporteur ; donc, si vous n'avez pas déjà Axe DevTools effectuant des analyses, lisez ce guide pour savoir comment effectuer des analyses avec Axe DevTools.

Installation du Reporter

Si vous avez déjà configuré votre fichier ~/.npmrc pour télécharger les paquets npm d'Axe DevTools, tout ce que vous avez à faire est d'exécuter la commande :

npm install @axe-devtools/reporter

Si vous n'avez pas encore configuré l'authentification de votre installation, lisez l'un des guides d'installation de base.

Ajout du Reporter à votre Projet

Importez le rapporteur en utilisant la syntaxe qui correspond à votre projet :

JavaScript avec modules CommonJS

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

JavaScript avec modules ES

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

TypeScript

TypeScript utilise la même syntaxe import que les modules ES. @axe-devtools/reporter propose ses propres déclarations de types, donc il n'y a pas de @types/ package séparé à installer :

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

Pour utiliser le rapporteur, votre bibliothèque Axe DevTools et votre webdriver devront également être importés.

Options du Reporter

Il y a trois choix majeurs que vous devez faire lors de l'utilisation du rapporteur Axe DevTools

1. Comment nommer les rapports
2. Où stocker les rapports
3. Quel format utiliser pour générer les rapports

Vous pouvez nommer les rapports comme vous le souhaitez. Lorsque vous initialisez le reporter, vous lui attribuez un nom de suite que tous les rapports générés avec cette instance partageront. Chaque rapport a également un nom assigné pour chaque analyse. L'emplacement, ou le répertoire, où seront stockés les rapports est également entièrement à votre discrétion. Cet emplacement de répertoire est également défini au niveau de l'instance, de sorte que tous les rapports générés sur une instance de reporter partageront un répertoire. Les formats de rapport optionnels sont HTML, recommandé pour une visualisation immédiate par l'utilisateur, JUnit XML, recommandé pour une utilisation dans des environnements CI, CSV, qui permet d'importer les résultats d'analyse dans d'autres outils, et EARL (Evaluation and Report Language), qui produit un document W3C EARL JSON-LD pour un rapport d'accessibilité lisible par machine.

Utilisation du Reporter

Une fois le reporter importé dans votre projet, vous pouvez l'initialiser. Le constructeur prend deux arguments : le nom de la suite de rapports et le répertoire de destination pour les rapports. Votre déclaration d'initialisation devrait ressembler à ceci :

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

Il y a deux étapes pour exécuter le rapporteur une fois qu'un scan Axe DevTools a été effectué. Tout d'abord, les résultats doivent être enregistrés pour que le rapporteur puisse y accéder. Ensuite, le rapporteur traite ces résultats dans le rapport.

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

Pré-rendu des rapports HTML

Un rapport HTML est autonome et se rend lui-même lorsqu'il est ouvert dans un navigateur. Avant d'en rédiger un, le générateur de rapports essaie également de le pré-rendre en balisage statique, de sorte que le contenu du rapport soit présent dans le fichier lui-même et s'affiche dès que le fichier est ouvert.

Le pré-rendu nécessite soit un navigateur, soit jsdom. À partir de la version 4.15.0, jsdom est une dépendance optionnelle et n'est plus installé avec le générateur de rapports, choisissez donc celui qui convient le mieux à votre environnement :

• Fournissez un navigateur. Passez browserPath dans l'argument renderOptions de buildHTML, ou définissez la variable d'environnement AXE_DEVTOOLS_REPORTER_BROWSER_PATH, pointant vers un exécutable basé sur Chromium. Aucun driver de navigateur ou bibliothèque d'automatisation n'est nécessaire.

• Installez jsdom vous-même. Cela maintient le comportement des versions antérieures :

  npm install jsdom

• S'appuyer sur un navigateur déjà installé sur la machine. Si vous ne fournissez aucun navigateur et n'installez pas jsdom, le générateur de rapports recherche un navigateur basé sur Chromium dans les emplacements d'installation standard de cette machine, puis sur le PATH.

Chaque fois que vous appelez buildHTML, le générateur de rapports choisit l'une de ces options dans l'ordre suivant :

1. Le navigateur donné par browserPath ou AXE_DEVTOOLS_REPORTER_BROWSER_PATH, si ce chemin existe.
2. jsdom, s'il est installé.
3. Un navigateur basé sur Chromium trouvé sur cette machine, à moins que vous ne définissiez autoDetectBrowser sur false.
4. Aucun des éléments ci-dessus, auquel cas le pré-rendu est ignoré. Le rapport est toujours écrit et se rend toujours lorsqu'il est ouvert dans un navigateur.

Lorsqu'un navigateur est utilisé, il s'exécute avec son sandbox activé et sans accès au réseau. Les rapports contiennent du contenu extrait des pages que vous avez scannées, laissez donc le sandbox activé sauf si vous êtes dans un environnement de confiance et restreint qui ne peut le supporter. Consultez RenderOptions pour la liste complète des options.

Exemple de fichier

Ce fichier exemple utilise la même base que l'exemple test d'écriture, mais il intègre également le rapporteur. Le même fichier est présenté en JavaScript et 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();
})();

Exemple de sortie

Les exemples ci-dessous montrent ce que chaque rapport lisible par machine contient pour un seul contrôle échoué. Des valeurs telles que les noms de suite et de test proviennent des arguments que vous passez au rapporteur ; les champs restants sont remplis à partir des résultats d'axe-core. Un rapport HTML est destiné à être ouvert dans un navigateur plutôt que lu comme source, il n'est donc pas présenté ici.

CSV

buildCSV écrit une ligne par résultat, précédée d'une ligne d'en-tête décrivant chaque colonne. Les champs contenant des virgules ou des sauts de ligne, comme Remediation, sont entre guillemets.

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 regroupe les résultats dans un testcase par règle, avec un élément failure pour chaque règle qui n'a pas réussi. Lorsqu'une règle échoue sur plus d'un élément, les occurrences sont répertoriées dans le même failure, séparées par un diviseur --------.

<?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 produit un document W3C EARL (Evaluation and Report Language) JSON-LD pour un rapport sur l'accessibilité lisible par machine. Le @context déclare les vocabulaires utilisés, et @graph contient une assertion par résultat.

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

Dépannage

Un message indique que le pré-rendu statique HTML a été ignoré

Si une exécution affiche un message commençant par axe-devtools-reporter: skipping static HTML pre-rendering, le générateur de rapports n'a trouvé aucun navigateur ni aucun jsdom installé. Le rapport est toujours écrit et se rend toujours lorsque vous l'ouvrez dans un navigateur, il s'agit donc d'un avertissement plutôt que d'une erreur. Pour pré-rendre à nouveau le rapport, fournissez un navigateur ou installez jsdom comme décrit dans Pré-rendu des rapports HTML. Le message est imprimé une fois par exécution, et non une fois par rapport.

Un rapport HTML est écrit sans son contenu

Un rapport qui s'ouvre vide lorsqu'il a été pré-rendu signifie généralement que le navigateur n'a pas eu assez de temps pour le construire. Augmentez virtualTimeBudgetMs dans l'argument renderOptions de buildHTML. Les rapports volumineux sont la cause fréquente.

Un rapport volumineux échoue avec un débordement de tampon

Augmentez maxBufferBytes dans l'argument renderOptions de buildHTML. Cela limite la quantité de sortie rendue que le générateur de rapports accepte du navigateur et par défaut à 64 Mo.

Obtenir plus d'aide

Si vous avez des difficultés à obtenir les résultats des scans, contactez directement votre représentant Deque, contactez-nous via notre service d'assistance, ou envoyez-nous un email. Nous serons heureux de vous aider.

Voir aussi

• Télécharger les résultats d'accessibilité JSON vers Axe Reports décrit comment télécharger vos résultats vers Axe Reports.
• Obtenir une clé API pour Axe Reports explique comment obtenir une clé API pour commencer à utiliser Axe Reports.
• Création et filtrage des rapports montre comment vous pouvez créer des rapports d'accessibilité en CSV, XML ou HTML à partir de vos résultats d'accessibilité JSON. Vous pouvez également filtrer votre sortie par gravité à l'aide de cet outil.
• Comment les résultats JSON sont stockés sur le disque décrit les conventions de nommage des fichiers pour les résultats d'accessibilité JSON.
• Utiliser la CLI pour envoyer des résultats d'accessibilité à Axe Developer Hub montre comment vous pouvez télécharger vos fichiers de résultats .json vers Axe Developer Hub.