Accessibility Testing Workflow

Overview

Accessibility testing uses @axe-core/playwright integrated with the existing Playwright E2E test suite. Tests run as part of the Playwright test suite alongside visual regression and smoke tests.

Test Files

File	Coverage
test/e2e/accessibility-keyboard.spec.ts	Keyboard navigation, focus visibility, Tab sequence
test/e2e/accessibility-focus-management.spec.ts	Modal focus traps, dropdown navigation, Escape key
test/e2e/accessibility-live-regions.spec.ts	Live region announcements for loading/empty/error states
test/e2e/accessibility-contrast.spec.ts	WCAG AA color contrast (light + dark mode)
test/e2e/accessibility-responsive.spec.ts	Responsive layout, touch targets, mobile/tablet scroll
test/e2e/accessibility-audit-all-screens.spec.ts	Comprehensive axe-core audit across all 16 screens

Running Tests

# Run all accessibility tests
pnpm playwright test test/e2e/accessibility-*.spec.ts

# Run a specific test file
pnpm playwright test test/e2e/accessibility-keyboard.spec.ts

# Run with desktop project only
pnpm playwright test --project=desktop test/e2e/accessibility-keyboard.spec.ts

# Run with mobile project only
pnpm playwright test --project=mobile test/e2e/accessibility-responsive.spec.ts

Test Outputs

Axe-core scan results are exported to test/e2e/__accessibility-reports__/:

• axe-results.json — raw axe-core output per screen
• axe-results-summary.csv — per-screen violation counts
• axe-results-summary.md — formatted summary table

Helper Utilities

Located in test/e2e/helpers/accessibility.ts:

• runAxeAudit(page, options?) — wrapper around @axe-core/playwright AxeBuilder
• captureAccessibilityScreenshot(page, name) — take screenshot for accessibility review
• runAxeAuditOnAllScreens(page, screens) — batch audit across multiple screens
• formatViolationsSummary(results) — format violations as human-readable text
• SCREENS_16 — constant with all 16 primary screen paths

Interpreting Results

Impact	Severity	Action
critical	Release Blocker	Must fix before release
serious	High	Fix or defer with documented justification
moderate	Medium	Fix or log in deferred-work.md
minor	Low	Accept or schedule for polish pass

Updating Baselines

Accessibility tests use the same screenshot baseline infrastructure as visual regression tests. To update baselines:

pnpm playwright test --update-snapshots test/e2e/accessibility-*.spec.ts

Manual Testing

In addition to automated tests, manual testing is documented in:

• test/e2e/__accessibility-reports__/keyboard-audit-checklist.md — keyboard walkthrough template
• _bmad-output/implementation-artifacts/7-3-accessibility-audit-report.md — full audit report

Manual screen-reader testing (NVDA/VoiceOver) is recommended when changing form interactions or dynamic content patterns.