axe-core — Automated Accessibility Testing Engine

Introduction

axe-core is an open-source JavaScript library that programmatically tests web pages for accessibility violations. It checks rendered DOM against WCAG 2.0, 2.1, 2.2, and best-practice rules, returning structured results with impact severity and remediation guidance. It is the engine behind the axe browser extension, axe Linter, and numerous testing framework integrations.

What axe-core Does

• Scans rendered HTML for WCAG A, AA, and AAA conformance violations
• Reports each violation with severity level (critical, serious, moderate, minor)
• Provides remediation guidance with links to relevant WCAG success criteria
• Runs in any JavaScript environment including browsers, Puppeteer, Playwright, and jsdom
• Supports custom rules and checks for project-specific accessibility requirements

Architecture Overview

axe-core operates on the live DOM rather than static HTML source. When axe.run() is called, it traverses the DOM tree, applies a rule-check pipeline to each node, and aggregates results. Each rule maps to one or more checks (evaluate functions) that inspect element attributes, ARIA roles, color contrast, focus order, and semantic structure. Rules can target specific selectors or run globally. Results are grouped by rule ID with arrays of affected nodes and their HTML context for debugging.

Self-Hosting & Configuration

• Import as an npm package or load via a script tag in the browser
• Use axe.configure() to enable or disable specific rules
• Scope scans to a container element by passing a CSS selector or DOM node to axe.run()
• Integrate with Playwright via @axe-core/playwright or Cypress via cypress-axe
• Add to CI by running axe in a headless browser and failing the build on violations

Key Features

• Zero false positives by design: only reports issues it can verify against the rendered DOM
• Framework integrations: official packages for React, Playwright, Puppeteer, Cypress, and WebdriverIO
• Localization: rule descriptions available in multiple languages
• Shadow DOM support: traverses open shadow roots to test web components
• Performance: typical page scans complete in under one second

Comparison with Similar Tools

• Lighthouse accessibility audit — Uses axe-core internally for its accessibility checks
• Pa11y — CLI wrapper around HTML_CodeSniffer; axe-core has broader rule coverage and integration options
• WAVE — Visual overlay tool; axe-core is a programmatic engine suited for CI and automated testing
• HTML_CodeSniffer — Standards-based checker; axe-core provides richer remediation guidance and fewer false positives

FAQ

Q: Does axe-core catch all accessibility issues? A: No automated tool can catch everything. axe-core reliably detects about 30-40% of WCAG issues. Manual testing and screen reader evaluation are still necessary.

Q: Can I run it in CI without a browser? A: You need a DOM environment. Use Puppeteer, Playwright, or jsdom to render pages headlessly in CI.

Q: Does it support single-page applications? A: Yes. Call axe.run() after route transitions to scan dynamically rendered content.

Q: How do I ignore known issues? A: Use axe.configure() to disable specific rules, or filter results by rule ID in your test assertions.

Sources

• https://github.com/dequelabs/axe-core
• https://www.deque.com/axe