Accessibility Testing with Playwright and axe-core

Most automated accessibility testing scans pages in their initial, static state — a crawler loads a URL and checks what renders. That misses an entire category of problems, because a huge share of accessibility bugs live in the states a page reaches after the user interacts: an open dialog that does not trap focus, a menu that never announces itself, a form that shows an error with no programmatic association.

Playwright already drives those interactions in your end-to-end tests. Adding the official axe-core Playwright integration (@axe-core/playwright) lets you run the axe-core engine at any point in a test — after a click, after a route change, after validation fires — so you assert accessibility on the real, interactive page. It is the depth layer that complements a crawler's breadth.

Install the official Deque integration alongside your existing Playwright setup. It brings its own copy of axe-core, so there is nothing else to configure.

# Install as a dev dependency
npm install --save-dev @axe-core/playwright

The pattern is: navigate, construct an AxeBuilder around the page, call .analyze(), and assert that the violations array is empty. An empty array means axe found no automatically detectable issues.

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

test('home page has no automatically detectable a11y violations', async ({ page }) => {
  await page.goto('/');

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

  expect(results.violations).toEqual([]);
});

When this fails, Playwright prints the diff of the violations array — but the raw output is dense. Two things make failures readable: scoping the scan (next section) and attaching the full results as a test artifact (later section). For now, know that each violation object carries the axe rule id, an impact level, a help URL, and the exact nodes (with CSS selectors) that failed.

A raw .analyze() runs every axe rule against the whole page. In real projects you usually want to constrain it — to a specific WCAG conformance level, to one region of the page, or away from a third-party widget you cannot fix. AxeBuilder is chainable, so these compose.

Constrain to a WCAG level with .withTags()

Pin the scan to the success criteria you are targeting so results stay stable across axe-core upgrades and match the standard you are conforming to:

const results = await new AxeBuilder({ page })
  .withTags(['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22aa'])
  .analyze();

Focus or exclude regions with .include() / .exclude()

.include() restricts the scan to a selector and its descendants; .exclude() removes a region from an otherwise full-page scan — the standard escape hatch for a third-party embed:

const results = await new AxeBuilder({ page })
  .include('#main-content')
  .exclude('#third-party-chat-widget')
  .analyze();

This is the reason to test accessibility in Playwright rather than a crawler. Because axe runs against the live DOM, you drive the component into the state you care about — then scan. A dialog is the classic example: closed, it is invisible to a crawler; open, it is where focus traps, labelling, and escape handling actually matter.

test('the edit-address dialog is accessible when open', async ({ page }) => {
  await page.goto('/checkout');

  // Drive the UI into the state we want to test
  await page.getByRole('button', { name: 'Edit address' }).click();
  await expect(page.getByRole('dialog')).toBeVisible();

  // Scan just the open dialog
  const results = await new AxeBuilder({ page })
    .include('[role="dialog"]')
    .analyze();

  expect(results.violations).toEqual([]);
});

The same approach covers every post-interaction state: expand a menu then scan it, submit a form with bad input then scan the error summary, load a data table then open its filter panel. Each is a state a sitemap crawler would score as "clean" simply because it never got there. For the accessibility requirements these components must meet in the first place, cross-reference the modal / dialog pattern and the rest of the pattern library.

Repeating the same .withTags([...]) chain in every test invites drift — one test scans against WCAG 2.2, another forgets and scans everything. Playwright fixtures solve this: define the configured builder once and inject it everywhere, so every test starts from the same baseline.

import { test as base } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';

type AxeFixture = {
  makeAxeBuilder: () => AxeBuilder;
};

// Extend the base test with a pre-configured AxeBuilder factory
export const test = base.extend<AxeFixture>({
  makeAxeBuilder: async ({ page }, use) => {
    const makeAxeBuilder = () =>
      new AxeBuilder({ page }).withTags([
        'wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22aa',
      ]);
    await use(makeAxeBuilder);
  },
});

export { expect } from '@playwright/test';

Import test and expect from the fixture instead of from Playwright directly, and every test gets the same WCAG-scoped scanner for free:

import { test, expect } from './axe-fixture';

test('pricing page is accessible', async ({ page, makeAxeBuilder }) => {
  await page.goto('/pricing');

  const results = await makeAxeBuilder().analyze();

  expect(results.violations).toEqual([]);
});

When a scan fails in CI, you want the full violation report in the test artifacts — not just the truncated console diff. Playwright's testInfo.attach() writes the complete axe results into the HTML report, where you can read every rule, impact, and failing selector:

test('checkout is accessible', async ({ page, makeAxeBuilder }, testInfo) => {
  await page.goto('/checkout');

  const results = await makeAxeBuilder().analyze();

  // Attach the full JSON to the Playwright report for debugging
  await testInfo.attach('accessibility-scan-results', {
    body: JSON.stringify(results, null, 2),
    contentType: 'application/json',
  });

  expect(results.violations).toEqual([]);
});

When you hit a known violation you cannot fix immediately — usually a third-party widget — disable the specific rule narrowly and leave a tracking comment. Never blanket-ignore:

// TODO(A11Y-142): vendor widget fails color-contrast; remove when fixed upstream
const results = await new AxeBuilder({ page })
  .disableRules(['color-contrast'])
  .analyze();

The best part of testing accessibility this way is that it needs no separate pipeline. These are ordinary Playwright tests, so they run in your existing Playwright CI job — the accessibility assertions fail the same build as a broken checkout flow, and the HTML report already carries the attached results.

If you keep accessibility specs in their own folder, you can run just them, or run them as part of the full suite:

# Run the whole Playwright suite (a11y specs included)
npx playwright test

# Or just the accessibility specs
npx playwright test tests/a11y