feat: Integrate @axe-core/playwright for automated accessibility testing in CI

[Wikid82]

Summary

Add automated accessibility (a11y) testing to the existing Playwright E2E test suite using @axe-core/playwright.

Motivation

The project has comprehensive a11y guidelines (.github/instructions/a11y.instructions.md) but no automated enforcement in CI. Integrating axe-core into the existing Playwright tests catches WCAG 2.2 Level AA violations automatically across all three browser engines (Chromium, Firefox, WebKit) with minimal additional infrastructure.

Proposed Approach

1. Install @axe-core/playwright as a dev dependency
2. Create a shared accessibility test helper/fixture that runs axe scans
3. Add accessibility checks to existing E2E tests (or create dedicated a11y spec files) for key pages
4. Configure axe rules to target WCAG 2.2 Level AA conformance
5. Fail CI on critical/serious violations

Example Usage

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

test('homepage should have no critical a11y violations', async ({ page }) => {
  await page.goto('/');
  const results = await new AxeBuilder({ page })
    .withTags(['wcag2a', 'wcag2aa', 'wcag22aa'])
    .analyze();
  expect(results.violations.filter(v => 
    ['critical', 'serious'].includes(v.impact)
  )).toEqual([]);
});

Acceptance Criteria

• @axe-core/playwright installed and configured
• Accessibility scans run on key application pages (dashboard, settings, login, etc.)
• CI fails on critical/serious WCAG 2.2 AA violations
• Results are available in Playwright HTML report
• Works across all three browser projects (Chromium, Firefox, WebKit)

References

• axe-core/playwright docs
• WCAG 2.2
• Existing a11y instructions: .github/instructions/a11y.instructions.md

[m13v]

we integrated axe-core into our Playwright E2E suite and the biggest lesson was scoping the rules properly from the start. running the full WCAG 2.2 ruleset on every page produces so many violations that teams stop looking at the results. we started with just color-contrast and aria-roles on the 3 most visited pages, fixed those, then expanded scope.

the other gotcha is dynamic content. axe scans the DOM at a point in time, so if you have modals, dropdowns, or tabs, you need separate scans after opening each one. we missed a bunch of violations hidden behind click interactions until we added post-interaction scans to the test fixture. a helper that opens each interactive element and re-scans saved us from shipping inaccessible modals that looked fine in the static scan.

[m13v]

our element interaction layer that handles accessibility tree traversal and element targeting for automated testing across macOS and Windows: https://github.com/mediar-ai/terminator/blob/main/crates/terminator/src/element.rs

it shows how we resolve elements by role and attributes, which is the same pattern axe-core uses internally to identify interactive elements for WCAG checks.