Skip to content
Tutorials Center
My learning

Topics

Lesson 30 of 38 ยท Testing Tools and Audits

Automated Testing with axe and Lighthouse

Use axe-core, Lighthouse, WAVE and linters to catch accessibility bugs automatically. Learn what automation finds, what it misses, and how to add it to CI.

Automated tools are the fastest way to find accessibility bugs. They run in seconds, never get tired and can guard every pull request. They also have a hard ceiling: studies of real audits suggest that automated rules detect only around 30 to 40 percent of WCAG problems. A page can score 100 and still be unusable by keyboard or screen reader.

Think of automation as a smoke detector. It tells you something is on fire; it cannot tell you the house is safe.

What automation can and cannot find

Usually detected Usually missed
Missing alt, missing form labels Whether alt text is meaningful
Low color contrast (on solid backgrounds) Contrast over images and gradients
Missing document language, empty buttons/links Whether link text makes sense out of context
Invalid ARIA attributes and roles Whether a widget behaves correctly with keyboard
Duplicate ids referenced by labels Logical reading order and focus order
Missing page title, lang Whether captions are accurate

Rule of thumb: tools check presence and syntax; humans check quality and experience.

The main tools

  • axe-core (Deque): an open-source JavaScript rules engine used inside many tools: the axe DevTools browser extension, Lighthouse, Playwright and Cypress plug-ins, Storybook. Its design goal is zero false positives, so "needs review" items are reported separately.
  • Lighthouse: built into Chrome DevTools (Lighthouse tab) and available on the command line. Its accessibility score uses a subset of axe rules, weighted by impact. A score is a guide, not a verdict.
  • WAVE (WebAIM): a browser extension that overlays icons on the page, great for learning because you see where each problem is.
  • Accessibility Insights (Microsoft): includes a guided "FastPass" and an assessment that walks through manual checks too.
  • Linters: eslint-plugin-jsx-a11y for React/JSX, eslint-plugin-vuejs-accessibility, angular-eslint template rules, axe-linter in editors, and pa11y for command-line page checks. These catch issues before the code even runs.
  • Browser DevTools: the Accessibility panel shows the accessibility tree, computed names and roles, and contrast in the color picker.

Run axe on a snippet

axe-core can run on any page with one call. The demo loads a pinned version from a CDN and tests a deliberately broken fragment. (It needs network access the first time you press the button.)

Run axe-core on a broken form

Typical findings are image-alt, label, link-name, button-name and color-contrast. Each result has a rule id, an impact level (minor to critical), a help URL and the failing elements, so you can fix them one by one. The sandboxed preview may skip a rule or two that depend on page context; treat the live site as the reference.

Add it to your workflow

Automate at three points.

  1. While writing code: editor linting and a browser extension.
  2. Component and page tests: run axe in your test runner.
  3. CI on every pull request: fail the build on new serious violations.

A Playwright test with the official package:

JavaScript
import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';

test('home page has no detectable a11y violations', async ({ page }) => {
  await page.goto('https://example.com/');
  const results = await new AxeBuilder({ page })
    .withTags(['wcag2a', 'wcag2aa', 'wcag22aa'])
    .analyze();
  expect(results.violations).toEqual([]);
});

And a Jest component test:

JavaScript
import { axe, toHaveNoViolations } from 'jest-axe';
expect.extend(toHaveNoViolations);

it('renders an accessible form', async () => {
  const { container } = render(<SignupForm />);
  expect(await axe(container)).toHaveNoViolations();
});

(These snippets need a Node project and are read-only here.)

Interpreting results

  • Violations are definite failures. Fix them.
  • Incomplete / needs review items are things axe could not decide (for example, contrast over an image). Check them by hand.
  • Passes list rules that ran successfully; they show what was actually tested.
  • Do not chase the score. A 100 means "no automated rule failed", not "accessible".
  • Test states: open menus, dialogs, error messages, logged-in views. Run axe after each state change.
  • Start with a baseline for old sites: record the current violations, fail only on new ones, then burn down the backlog.

Common false confidence traps

  • Hidden content is skipped by axe: a modal that is display: none is not tested until opened.
  • aria-label on a button satisfies the rule even if the label is wrong ("button1").
  • Passing contrast checks does not mean the focus indicator is visible.
  • Tools test one page at a time; pick a representative set: home, search, article, form, checkout, error page.
flowchart LR
  A["Lint in editor"] --> B["Unit and component tests with axe"]
  B --> C["CI scan on pull request"]
  C --> D["Manual keyboard and screen reader tests"]
  D --> E["Release"]

Automation is the first layer; the manual layer still decides.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Roughly how much of WCAG can automated tools detect?

    Automation finds mostly syntax and presence issues; much of WCAG needs human judgment.
  2. 2. Which of these would automation most likely miss?

    A tool sees that alt exists but cannot judge whether it describes the image.
  3. 3. What are 'incomplete' results in axe?

    axe reports uncertain cases as incomplete rather than guessing, so you check them yourself.
  4. 4. Where should automated checks run to prevent regressions?

    Continuous checks catch new violations as soon as they are introduced.

Summary

  • axe-core, Lighthouse, WAVE, Accessibility Insights and linters each catch a different slice of issues.
  • Automation detects roughly a third to half of problems; do not treat a high score as proof.
  • Run checks in the editor, in tests and in CI; test states, not only first load.
  • Review "incomplete" results by hand, then continue with manual testing.

Next: Manual Testing: Keyboard, Zoom and Inspection