Understanding axe accessibility
The audit that catches 30 % of accessibility bugs automatically.
What axe checks, what WCAG levels mean, and why the other 70 % still needs human testing.
What axe is.
axe-core (Deque Systems) is the de facto standard automated accessibility audit library. It runs on a rendered page (browser, jsdom, or Playwright/Cypress) and reports violations against WCAG rules — missing alt text, low colour contrast, improper heading order, ARIA misuse, form labels without associated controls. It powers Lighthouse's a11y audit, Chrome DevTools' issues panel, Storybook's accessibility addon, and most paid scanners.
WCAG levels.
WCAG 2.2 (2023) has three conformance levels. A: bare minimum (alt text on images, keyboard accessible, no flashing more than 3×/sec). AA: industry standard (4.5:1 colour contrast on body text, visible focus indicators, descriptive link text). AAA: stretch goal (7:1 contrast, sign-language for video, no time limits). Public-sector procurement in most countries mandates AA. Aim for AA; AAA is exceptional.
What axe catches.
Mechanical rule violations. Missing alt: <img> withoutalt attribute. Empty label: <input> with no associated<label>. Insufficient contrast: white text on light grey at WCAG AA threshold (4.5:1) fails. ARIA misuse: aria-labelledby pointing at a non-existent ID. Skipped heading levels: h1 → h3 (skipping h2). Each violation is reported with the failing element, the rule violated, and a "how to fix" link.
What axe misses.
Whether the alt text is actually meaningful ("image" passes the check). Whether the focus order makes sense (mechanically correct, semantically a mess). Whether a screen reader announces a state change. Whether dynamic content updates reach assistive tech. The Deque team estimates axe catches ~30-40 % of WCAG issues. The rest needs human testing — keyboard-only navigation, screen reader walkthrough (NVDA on Windows, VoiceOver on Mac), real users with disabilities.
A worked run.
On a typical landing page, a fresh axe run reports ~5-15 violations: a missing alt on a hero image, two contrast failures on muted body text, a navigation link with no accessible name (icon-only), a form field whose label is a sibling divinstead of a proper label. All five fixable in under an hour, after which the page passes the automated audit. The screen-reader walkthrough afterwards surfaces another 3-5 issues that no scanner caught.
Landing page audit
axe + manual SR test
Automated → manual, in that order.
axe: 5-15 violations ; SR walk: another 3-5
= Catch both kinds
Wire it into CI.
axe-core in CI doesn't replace manual testing; it prevents regressions. Run@axe-core/playwright against each route in your E2E suite; fail the build on any violation. The audit is fast (seconds per page) and gives a stable baseline. Manual testing then becomes about behaviour changes, not catching the obvious. The hard part is fixing the existing violations once; after that, the ratchet keeps them gone.