How to analyze the axe core accessibility report

When you run axe-core (a popular accessibility testing tool), it generates a violations report showing exactly which accessibility rules were broken, why, and where. Let me break it down.

---

1️⃣ Typical Structure of an axe-core Violations Report

A single violation entry usually contains the following information:

Field	Description
id	The unique identifier of the violated rule (e.g., color-contrast, image-alt).
impact	Severity level: critical, serious, moderate, or minor.
description	Short explanation of the rule and why it matters.
help	A human-readable message describing the issue.
helpUrl	Link to detailed documentation about the rule.
nodes	List of HTML elements that fail this rule. Each node contains:
html	The actual HTML snippet that caused the violation.
target	CSS selector(s) to locate the element on the page.
failureSummary	Summary of why the element failed the test.

---

2️⃣ Sample JSON Report (Simplified)

{
  "violations": [
    {
      "id": "color-contrast",
      "impact": "serious",
      "description": "Ensures the contrast between foreground and background colors meets WCAG 2 AA contrast ratio thresholds",
      "help": "Elements must have sufficient color contrast",
      "helpUrl": "https://dequeuniversity.com/rules/axe/4.7/color-contrast",
      "nodes": [
        {
          "html": "<p style='color: #888888;'>Welcome</p>",
          "target": ["p.welcome-message"],
          "failureSummary": "Fix any of the following:\n  Element has insufficient color contrast of 2.5 (foreground #888888, background #ffffff, ratio 2.55:1)."
        }
      ]
    },
    {
      "id": "image-alt",
      "impact": "critical",
      "description": "Ensures <img> elements have alternate text or a role of none/presentation",
      "help": "Images must have alternate text",
      "helpUrl": "https://dequeuniversity.com/rules/axe/4.7/image-alt",
      "nodes": [
        {
          "html": "<img src='logo.png'>",
          "target": ["img#logo"],
          "failureSummary": "Image element does not have an alt attribute"
        }
      ]
    }
  ]
}

---

3️⃣ What You Can Do With This Report

1. Identify high-impact issues

   • Look at impact: critical or serious first.

2. Locate problems on the page

   • target gives the CSS selector.
   • html shows the offending element.

3. Understand why it failed

   • failureSummary tells you exactly what needs fixing.

4. Provide guidance to developers

   • Use helpUrl to link to official documentation.

---

4️⃣ Example Usage in Automation

import AxeBuilder from '@axe-core/playwright';

const results = await new AxeBuilder({ page }).analyze();

results.violations.forEach(violation => {
    console.log(`${violation.impact.toUpperCase()} - ${violation.help}`);
    violation.nodes.forEach(node => {
        console.log(`  Element: ${node.target}`);
        console.log(`  Issue: ${node.failureSummary}`);
    });
});

✅ Output:

SERIOUS - Elements must have sufficient color contrast
  Element: p.welcome-message
  Issue: Element has insufficient color contrast of 2.5 (foreground #888888, background #ffffff)

CRITICAL - Images must have alternate text
  Element: img#logo
  Issue: Image element does not have an alt attribute