Playwright Accessibility Testing
Reusable knowledge module for browser-based accessibility testing using Playwright and @axe-core/playwright.
MCP Tools Available
Each tool the MCP server registers (mcp-server/tools/playwright-tools.js), with its purpose and whether it needs @axe-core/playwright. All of them need Playwright with Chromium. There is no state-scan tool: to scan content revealed by an interaction, script the interaction and run AxeBuilder yourself (see Scan After Interaction).
| Tool | Purpose | Requires @axe-core/playwright |
|---|---|---|
run_axe_scan |
axe-core scan of a URL; default tags wcag2a, wcag2aa, wcag21a, wcag21aa, wcag22aa |
Yes |
run_playwright_keyboard_scan |
Tab-order traversal, focus visibility, keyboard trap detection | No |
run_playwright_viewport_scan |
Horizontal scrolling at 320, 768, 1024 and 1280 CSS px (1.4.10 Reflow only; no zoom, text resize or target-size check) | No |
run_playwright_contrast_scan |
Computed-style text contrast against the AA thresholds (4.5:1, or 3:1 for large text) | No |
run_playwright_a11y_tree |
Browser accessibility tree snapshot (ariaSnapshot) |
No |
If the scanner tools are not available, ask for the results from axe or Accessibility Insights, use only what you are given, and never say you scanned, ran or opened anything you did not.
@axe-core/playwright Patterns
Full Page Scan
import AxeBuilder from '@axe-core/playwright';
const results = await new AxeBuilder({ page })
.withTags(['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22aa'])
.analyze();
In axe-core 4.14 the only wcag22aa rule is target-size, which runs only when that tag is listed. Most WCAG 2.2 criteria (2.4.11, 2.5.7, 3.2.6, 3.3.7, 3.3.8) have no axe rule and need manual or scripted checks. AxeBuilder needs a page opened from a browser context; the Playwright Test page fixture is one, browser.newPage() is not.
Scoped Element Scan
const results = await new AxeBuilder({ page })
.include('.modal-content')
.withTags(['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22aa'])
.analyze();
Single Rule Verification
const results = await new AxeBuilder({ page })
.include('#hero-image')
.withRules(['image-alt'])
.analyze();
expect(results.violations).toEqual([]);
Scan After Interaction
await page.locator('[aria-expanded="false"]').first().click();
await page.locator('.accordion-content').first().waitFor({ state: 'visible' });
const results = await new AxeBuilder({ page })
.include('.accordion-content')
.withTags(['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22aa'])
.analyze();
Keyboard Traversal Patterns
Record Tab Sequence
const tabStops = [];
for (let i = 0; i < maxTabs; i++) {
await page.keyboard.press('Tab');
const info = await page.evaluate(() => {
const el = document.activeElement;
return {
tagName: el?.tagName,
role: el?.getAttribute('role'),
name: el?.getAttribute('aria-label') || el?.textContent?.trim().slice(0, 50),
id: el?.id,
tabIndex: el?.tabIndex
};
});
tabStops.push(info);
}
Detect Keyboard Traps
A keyboard trap is detected when the same element receives focus after consecutive Tab presses:
let trapCount = 0;
let lastSelector = '';
for (const stop of tabStops) {
const currentSelector = `${stop.tagName}#${stop.id}`;
if (currentSelector === lastSelector) {
trapCount++;
if (trapCount >= 3) { /* TRAP DETECTED */ }
} else {
trapCount = 0;
}
lastSelector = currentSelector;
}
Focus Management After Modal Open
await page.locator('[data-modal-trigger]').click();
await page.getByRole('dialog').waitFor({ state: 'visible' });
const focusedRole = await page.evaluate(() =>
document.activeElement?.closest('[role="dialog"]') ? 'inside-dialog' : 'outside-dialog'
);
// focusedRole should be 'inside-dialog'
Focus Management Test Templates
Modal Focus Trap Test
test('modal traps focus correctly', async ({ page }) => {
await page.goto(url);
await page.locator('[data-open-modal]').click();
await expect(page.getByRole('dialog')).toBeVisible();
// Focus should be inside the dialog
const inDialog = await page.evaluate(() =>
document.activeElement?.closest('[role="dialog"]') !== null
);
expect(inDialog).toBe(true);
// Tab through dialog - should not escape
for (let i = 0; i < 20; i++) {
await page.keyboard.press('Tab');
const stillInDialog = await page.evaluate(() =>
document.activeElement?.closest('[role="dialog"]') !== null
);
expect(stillInDialog).toBe(true);
}
// Escape should close and return focus to trigger
await page.keyboard.press('Escape');
const focusedId = await page.evaluate(() => document.activeElement?.id);
expect(focusedId).toBe('modal-trigger-id');
});
Skip Link Test
test('skip link moves focus to main content', async ({ page }) => {
await page.goto(url);
await page.keyboard.press('Tab'); // Focus skip link
await page.keyboard.press('Enter'); // Activate it
const focusedId = await page.evaluate(() => document.activeElement?.id);
expect(focusedId).toBe('main-content');
});
CI Integration
GitHub Actions with Playwright
name: Accessibility Tests
on: [push, pull_request]
jobs:
a11y:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
with:
node-version: 24
- run: npm ci
- run: npx playwright install --with-deps chromium
- name: Start dev server
run: npm run dev &
env:
CI: true
- name: Wait for server
run: npx wait-on http://localhost:3000 --timeout 30000
- name: Run accessibility tests
run: npx playwright test tests/a11y/
- uses: actions/upload-artifact@v7
if: failure()
with:
name: a11y-test-results
path: test-results/
Playwright Config for Accessibility Tests
// playwright.config.js (a11y section)
export default {
testDir: './tests/a11y',
use: {
baseURL: process.env.BASE_URL || 'http://localhost:3000',
// Chromium matches the browser the MCP tools use, so results are comparable
browserName: 'chromium',
},
webServer: {
command: 'npm run dev',
url: 'http://localhost:3000',
reuseExistingServer: !process.env.CI,
},
};
Graceful Degradation
Detection Pattern
let _playwrightAvailable = null;
async function isPlaywrightAvailable() {
if (_playwrightAvailable !== null) return _playwrightAvailable;
try {
await import('playwright');
_playwrightAvailable = true;
} catch {
_playwrightAvailable = false;
}
return _playwrightAvailable;
}
Degradation Matrix
Each playwright, with its @axe-core or playwright and available scans.
| Playwright | @axe-core/playwright | Available Scans |
|---|---|---|
| Yes | Yes | All 5 tools (axe, keyboard, viewport, contrast, tree) |
| Yes | No | 4 tools (keyboard, viewport, contrast, tree); no run_axe_scan |
| No | n/a | None - fall back to code review + axe-core CLI |
User-Facing Messages
When unavailable:
Playwright not installed. Behavioral testing (keyboard traversal, dynamic states,
responsive viewport, rendered contrast) is unavailable.
Install: npm install -D playwright @axe-core/playwright && npx playwright install chromium
When partially available:
@axe-core/playwright not installed. The axe-core scan is unavailable.
Keyboard, viewport, contrast, and accessibility tree scans will proceed.
Install: npm install -D @axe-core/playwright
WCAG Coverage Map
Each WCAG SC, with its description and playwright tool.
| WCAG SC | Description | Playwright Tool |
|---|---|---|
| 1.3.1 | Info and Relationships | a11y tree, axe scan |
| 1.4.3 | Contrast (Minimum) | contrast scan, axe scan |
| 1.4.10 | Reflow | viewport scan (horizontal scroll only) |
| 2.1.1 | Keyboard | keyboard scan |
| 2.1.2 | No Keyboard Trap | keyboard scan |
| 2.4.3 | Focus Order | keyboard scan |
| 2.4.7 | Focus Visible | keyboard scan |
| 2.5.8 | Target Size (Minimum) | axe scan (target-size, needs the wcag22aa tag) |
| 4.1.2 | Name, Role, Value | a11y tree, axe scan |
Not covered by any tool: 1.4.6 Contrast (Enhanced), 2.5.5 Target Size (Enhanced), 1.4.4 Resize Text, and most WCAG 2.2 additions (2.4.11, 2.5.7, 3.2.6, 3.3.7, 3.3.8).