a11y-axe-playwright

Skill: Axe Scans with Playwright

Setup

Install the dependency:

yarn add -D @axe-core/playwright

Import in test files:

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

Tag Selection

Never omit tags — an untagged scan runs all rules including experimental ones and produces noise.

Scoping

Always scope scans to the component under test using .include(). Avoid scanning the full page when testing a single component.

const results = await new AxeBuilder({ page })
  .include('#my-component-selector')
  .withTags(['wcag2a', 'wcag2aa', 'wcag21aa'])
  .analyze();

For full page audits, omit .include():

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

When to Run Axe Scans

Run an axe scan at each significant page state transition:

• Initial page load
• After form submission
• After navigation to a new page/view
• After modal/dialog opens
• After dynamic content loads (search results, filtered lists)

Test Pattern

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

test.describe('MyComponent accessibility @a11y', () => {
  test('should have no WCAG 2.1 AA violations', async ({ page }) => {
    await page.goto('/my-component-route');

    const results = await new AxeBuilder({ page })
      .include('#my-component-selector')
      .withTags(['wcag2a', 'wcag2aa', 'wcag21aa'])
      .analyze();

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

Interpreting Violations

Each violation in results.violations contains:

• id — axe rule id (e.g. color-contrast, label, aria-required-attr)
• impact — critical, serious, moderate, or minor
• description — what the rule checks
• nodes — list of affected elements with html snippet and failureSummary