Accessibility Testing (WCAG 2.1 AA+)
Run 40 accessibility test cases across 4 parallel agents covering document structure, keyboard navigation, content accessibility, and dynamic content.
Setup
URL="${ARGUMENTS:-http://localhost:3000}"
TIMESTAMP=$(date +%Y%m%d-%H%M%S)
OUTDIR="test-results/test-a11y/$TIMESTAMP"
mkdir -p "$OUTDIR/screenshots" "$OUTDIR/snapshots" "$OUTDIR/traces"
Before running, verify prerequisites per references/prerequisites.md.
Parallel Execution — 4 Subagents
Launch 4 subagents in parallel. Each opens its own browser session and runs its test cases independently.
Agent 1: Structure (-s=a11y-structure)
Tests document structure and semantic HTML.
playwright-cli -s=a11y-structure open "$URL"
playwright-cli -s=a11y-structure tracing-start
playwright-cli -s=a11y-structure snapshot --filename="$OUTDIR/snapshots/structure-initial.yaml"
Test Cases:
| TC |
Test |
How to Check |
| TC-A1 |
ARIA labels on all interactive elements |
run-code to find interactive elements (button, a, input, select, textarea) without aria-label, aria-labelledby, or visible label |
| TC-A2 |
ARIA roles correct (not generic) |
run-code to find elements with role="generic" or missing roles on custom widgets |
| TC-A3 |
Heading hierarchy (single h1, no skipped levels) |
run-code to get all heading levels, verify single h1 and no gaps (h1→h3 without h2) |
| TC-A4 |
Landmark regions (main, nav, aside, header, footer) |
run-code to check for presence of landmark roles/elements |
| TC-A5 |
Skip navigation link |
run-code to find first focusable element, check if it's a skip-nav link targeting #main or similar |
| TC-A6 |
Page <title> present and descriptive |
eval "document.title" — verify non-empty, not generic ("Untitled", "Home") |
| TC-A7 |
<html lang> attribute set |
eval "document.documentElement.lang" — verify present and valid BCP 47 |
| TC-A8 |
Lists use <ul>/<ol> not styled <div> |
run-code to find div elements styled as lists (list-style, bullet-like content) |
| TC-A9 |
Tables have <th> headers + scope/caption |
run-code to find tables, check for th elements, scope attributes, caption |
| TC-A10 |
No duplicate IDs |
run-code to collect all element IDs, find duplicates |
playwright-cli -s=a11y-structure screenshot --filename="$OUTDIR/screenshots/structure-final.png"
playwright-cli -s=a11y-structure tracing-stop
playwright-cli -s=a11y-structure close
Agent 2: Keyboard (-s=a11y-keyboard)
Tests keyboard navigation and focus management.
playwright-cli -s=a11y-keyboard open "$URL"
playwright-cli -s=a11y-keyboard tracing-start
Test Cases:
| TC |
Test |
How to Check |
| TC-A11 |
All interactive elements reachable via Tab |
run-code to count interactive elements, then Tab through page counting focused elements |
| TC-A12 |
Tab order follows visual/logical order |
Tab through elements, record positions via run-code, verify order matches visual layout |
| TC-A13 |
Focus visible indicator on all focusable elements |
Tab to each element, run-code to check computed outline/box-shadow style isn't none |
| TC-A14 |
Modal focus trapping (Tab cycles within) |
If modal exists: open it, Tab repeatedly, verify focus stays within modal container |
| TC-A15 |
Focus returns to trigger on modal close |
Open modal, close it (Escape), verify document.activeElement is the trigger button |
| TC-A16 |
Dropdown keyboard navigation (Arrow keys, Enter, Escape) |
Find dropdown, press Enter to open, ArrowDown to navigate, Enter to select, Escape to close |
| TC-A17 |
No keyboard traps (can always Tab out) |
Tab through entire page, verify focus eventually returns to browser chrome or loops to start |
| TC-A18 |
Escape closes overlays/menus |
Open any overlay/menu, press Escape, verify it closes |
| TC-A19 |
Enter/Space activate buttons and links |
Focus each button/link, press Enter and Space, verify activation |
| TC-A20 |
Custom widgets have keyboard support |
Find elements with ARIA widget roles, verify keyboard interaction works |
playwright-cli -s=a11y-keyboard screenshot --filename="$OUTDIR/screenshots/keyboard-final.png"
playwright-cli -s=a11y-keyboard tracing-stop
playwright-cli -s=a11y-keyboard close
Agent 3: Content (-s=a11y-content)
Tests text, images, and media accessibility.
playwright-cli -s=a11y-content open "$URL"
playwright-cli -s=a11y-content tracing-start
Test Cases:
| TC |
Test |
How to Check |
| TC-A21 |
All <img> have alt text (or alt="" for decorative) |
run-code to find img elements without alt attribute |
| TC-A22 |
Color contrast ≥4.5:1 normal text, ≥3:1 large (AA) |
run-code to sample text elements, get computed color + background-color, calculate ratio |
| TC-A23 |
Color contrast ≥7:1 / ≥4.5:1 (AAA) |
Same as TC-A22 but with AAA thresholds |
| TC-A24 |
Information not conveyed by color alone |
run-code to find elements relying solely on color (error fields with only red border, no icon/text) |
| TC-A25 |
Form inputs have visible labels |
run-code to find inputs, check for associated visible label element or aria-label |
| TC-A26 |
Form <label for> correctly associated |
run-code to find labels with for attribute, verify matching input ID exists |
| TC-A27 |
Error messages programmatically associated |
run-code to find error messages, check aria-describedby or aria-errormessage on associated input |
| TC-A28 |
Required fields indicated in accessible way |
run-code to find required inputs, verify aria-required="true" or required attribute + visible indicator |
| TC-A29 |
Links have descriptive text (no "click here") |
run-code to find links with generic text: "click here", "read more", "here", "link" |
| TC-A30 |
Text resizable to 200% without loss |
run-code to set document.documentElement.style.fontSize='200%', check for overflow |
playwright-cli -s=a11y-content screenshot --filename="$OUTDIR/screenshots/content-final.png"
playwright-cli -s=a11y-content tracing-stop
playwright-cli -s=a11y-content close
Agent 4: Dynamic (-s=a11y-dynamic)
Tests dynamic content, live regions, and state changes.
playwright-cli -s=a11y-dynamic open "$URL"
playwright-cli -s=a11y-dynamic tracing-start
Test Cases:
| TC |
Test |
How to Check |
| TC-A31 |
ARIA live regions for dynamic updates |
run-code to find elements with aria-live attribute or role="alert/status/log" |
| TC-A32 |
Loading states announced to screen readers |
Trigger loading state, check for aria-busy="true" or aria-live region with loading text |
| TC-A33 |
Error messages announced via aria-live |
Trigger form error, verify error container has aria-live="assertive" or role="alert" |
| TC-A34 |
Accordion/disclosure uses aria-expanded |
Find accordion/disclosure patterns, verify aria-expanded toggles on open/close |
| TC-A35 |
Tabs use proper tablist/tab/tabpanel roles |
Find tab components, verify role="tablist", role="tab", role="tabpanel", aria-selected |
| TC-A36 |
Carousel/slider keyboard accessible |
If carousel exists: verify Arrow key navigation, pause button, focus management |
| TC-A37 |
Tooltips accessible via keyboard + screen reader |
Find tooltips, verify they show on focus (not just hover), have role="tooltip" |
| TC-A38 |
prefers-reduced-motion respected |
run-code to emulate reduced motion, check if animations are disabled |
| TC-A39 |
Autocomplete/combobox uses aria-activedescendant |
Find combobox patterns, verify aria-activedescendant updates on selection |
| TC-A40 |
Progress indicators have accessible labels |
Find progress bars/spinners, verify aria-label, aria-valuenow, role="progressbar" |
playwright-cli -s=a11y-dynamic screenshot --filename="$OUTDIR/screenshots/dynamic-final.png"
playwright-cli -s=a11y-dynamic tracing-stop
playwright-cli -s=a11y-dynamic close
Fix Loop
After execution, if any tests failed, follow the fix loop process in references/fix-loop.md.
Max 3 attempts. Only re-run failed test cases.
Include fix attempt history in the report.
Report Generation
After all 4 agents complete, merge results into $OUTDIR/report.md following the standard report format (see references/report-format.md).
Group results by agent category:
- Structure (TC-A1 through TC-A10)
- Keyboard (TC-A11 through TC-A20)
- Content (TC-A21 through TC-A30)
- Dynamic (TC-A31 through TC-A40)
Cleanup
playwright-cli -s=a11y-structure close 2>/dev/null
playwright-cli -s=a11y-keyboard close 2>/dev/null
playwright-cli -s=a11y-content close 2>/dev/null
playwright-cli -s=a11y-dynamic close 2>/dev/null
1---2name: test-a11y3description: Run comprehensive WCAG 2.1 AA+ accessibility tests on a URL. Use when user wants to test accessibility, a11y compliance, screen reader support, or keyboard navigation.4---56# Accessibility Testing (WCAG 2.1 AA+)78Run 40 accessibility test cases across 4 parallel agents covering document structure, keyboard navigation, content accessibility, and dynamic content.910## Setup1112```bash13URL="${ARGUMENTS:-http://localhost:3000}"14TIMESTAMP=$(date +%Y%m%d-%H%M%S)15OUTDIR="test-results/test-a11y/$TIMESTAMP"16mkdir -p "$OUTDIR/screenshots" "$OUTDIR/snapshots" "$OUTDIR/traces"17```1819Before running, verify prerequisites per `references/prerequisites.md`.2021## Parallel Execution — 4 Subagents2223Launch 4 subagents in parallel. Each opens its own browser session and runs its test cases independently.2425### Agent 1: Structure (`-s=a11y-structure`)2627Tests document structure and semantic HTML.2829```bash30playwright-cli -s=a11y-structure open "$URL"31playwright-cli -s=a11y-structure tracing-start32playwright-cli -s=a11y-structure snapshot --filename="$OUTDIR/snapshots/structure-initial.yaml"33```3435**Test Cases:**3637| TC | Test | How to Check |38|----|------|-------------|39| TC-A1 | ARIA labels on all interactive elements | `run-code` to find interactive elements (button, a, input, select, textarea) without aria-label, aria-labelledby, or visible label |40| TC-A2 | ARIA roles correct (not generic) | `run-code` to find elements with `role="generic"` or missing roles on custom widgets |41| TC-A3 | Heading hierarchy (single h1, no skipped levels) | `run-code` to get all heading levels, verify single h1 and no gaps (h1→h3 without h2) |42| TC-A4 | Landmark regions (main, nav, aside, header, footer) | `run-code` to check for presence of landmark roles/elements |43| TC-A5 | Skip navigation link | `run-code` to find first focusable element, check if it's a skip-nav link targeting #main or similar |44| TC-A6 | Page `<title>` present and descriptive | `eval "document.title"` — verify non-empty, not generic ("Untitled", "Home") |45| TC-A7 | `<html lang>` attribute set | `eval "document.documentElement.lang"` — verify present and valid BCP 47 |46| TC-A8 | Lists use `<ul>`/`<ol>` not styled `<div>` | `run-code` to find div elements styled as lists (list-style, bullet-like content) |47| TC-A9 | Tables have `<th>` headers + scope/caption | `run-code` to find tables, check for th elements, scope attributes, caption |48| TC-A10 | No duplicate IDs | `run-code` to collect all element IDs, find duplicates |4950```bash51playwright-cli -s=a11y-structure screenshot --filename="$OUTDIR/screenshots/structure-final.png"52playwright-cli -s=a11y-structure tracing-stop53playwright-cli -s=a11y-structure close54```5556### Agent 2: Keyboard (`-s=a11y-keyboard`)5758Tests keyboard navigation and focus management.5960```bash61playwright-cli -s=a11y-keyboard open "$URL"62playwright-cli -s=a11y-keyboard tracing-start63```6465**Test Cases:**6667| TC | Test | How to Check |68|----|------|-------------|69| TC-A11 | All interactive elements reachable via Tab | `run-code` to count interactive elements, then Tab through page counting focused elements |70| TC-A12 | Tab order follows visual/logical order | Tab through elements, record positions via `run-code`, verify order matches visual layout |71| TC-A13 | Focus visible indicator on all focusable elements | Tab to each element, `run-code` to check computed outline/box-shadow style isn't `none` |72| TC-A14 | Modal focus trapping (Tab cycles within) | If modal exists: open it, Tab repeatedly, verify focus stays within modal container |73| TC-A15 | Focus returns to trigger on modal close | Open modal, close it (Escape), verify `document.activeElement` is the trigger button |74| TC-A16 | Dropdown keyboard navigation (Arrow keys, Enter, Escape) | Find dropdown, press Enter to open, ArrowDown to navigate, Enter to select, Escape to close |75| TC-A17 | No keyboard traps (can always Tab out) | Tab through entire page, verify focus eventually returns to browser chrome or loops to start |76| TC-A18 | Escape closes overlays/menus | Open any overlay/menu, press Escape, verify it closes |77| TC-A19 | Enter/Space activate buttons and links | Focus each button/link, press Enter and Space, verify activation |78| TC-A20 | Custom widgets have keyboard support | Find elements with ARIA widget roles, verify keyboard interaction works |7980```bash81playwright-cli -s=a11y-keyboard screenshot --filename="$OUTDIR/screenshots/keyboard-final.png"82playwright-cli -s=a11y-keyboard tracing-stop83playwright-cli -s=a11y-keyboard close84```8586### Agent 3: Content (`-s=a11y-content`)8788Tests text, images, and media accessibility.8990```bash91playwright-cli -s=a11y-content open "$URL"92playwright-cli -s=a11y-content tracing-start93```9495**Test Cases:**9697| TC | Test | How to Check |98|----|------|-------------|99| TC-A21 | All `<img>` have alt text (or alt="" for decorative) | `run-code` to find img elements without alt attribute |100| TC-A22 | Color contrast ≥4.5:1 normal text, ≥3:1 large (AA) | `run-code` to sample text elements, get computed color + background-color, calculate ratio |101| TC-A23 | Color contrast ≥7:1 / ≥4.5:1 (AAA) | Same as TC-A22 but with AAA thresholds |102| TC-A24 | Information not conveyed by color alone | `run-code` to find elements relying solely on color (error fields with only red border, no icon/text) |103| TC-A25 | Form inputs have visible labels | `run-code` to find inputs, check for associated visible label element or aria-label |104| TC-A26 | Form `<label for>` correctly associated | `run-code` to find labels with `for` attribute, verify matching input ID exists |105| TC-A27 | Error messages programmatically associated | `run-code` to find error messages, check aria-describedby or aria-errormessage on associated input |106| TC-A28 | Required fields indicated in accessible way | `run-code` to find required inputs, verify aria-required="true" or required attribute + visible indicator |107| TC-A29 | Links have descriptive text (no "click here") | `run-code` to find links with generic text: "click here", "read more", "here", "link" |108| TC-A30 | Text resizable to 200% without loss | `run-code` to set `document.documentElement.style.fontSize='200%'`, check for overflow |109110```bash111playwright-cli -s=a11y-content screenshot --filename="$OUTDIR/screenshots/content-final.png"112playwright-cli -s=a11y-content tracing-stop113playwright-cli -s=a11y-content close114```115116### Agent 4: Dynamic (`-s=a11y-dynamic`)117118Tests dynamic content, live regions, and state changes.119120```bash121playwright-cli -s=a11y-dynamic open "$URL"122playwright-cli -s=a11y-dynamic tracing-start123```124125**Test Cases:**126127| TC | Test | How to Check |128|----|------|-------------|129| TC-A31 | ARIA live regions for dynamic updates | `run-code` to find elements with aria-live attribute or role="alert/status/log" |130| TC-A32 | Loading states announced to screen readers | Trigger loading state, check for aria-busy="true" or aria-live region with loading text |131| TC-A33 | Error messages announced via aria-live | Trigger form error, verify error container has aria-live="assertive" or role="alert" |132| TC-A34 | Accordion/disclosure uses aria-expanded | Find accordion/disclosure patterns, verify aria-expanded toggles on open/close |133| TC-A35 | Tabs use proper tablist/tab/tabpanel roles | Find tab components, verify role="tablist", role="tab", role="tabpanel", aria-selected |134| TC-A36 | Carousel/slider keyboard accessible | If carousel exists: verify Arrow key navigation, pause button, focus management |135| TC-A37 | Tooltips accessible via keyboard + screen reader | Find tooltips, verify they show on focus (not just hover), have role="tooltip" |136| TC-A38 | `prefers-reduced-motion` respected | `run-code` to emulate reduced motion, check if animations are disabled |137| TC-A39 | Autocomplete/combobox uses aria-activedescendant | Find combobox patterns, verify aria-activedescendant updates on selection |138| TC-A40 | Progress indicators have accessible labels | Find progress bars/spinners, verify aria-label, aria-valuenow, role="progressbar" |139140```bash141playwright-cli -s=a11y-dynamic screenshot --filename="$OUTDIR/screenshots/dynamic-final.png"142playwright-cli -s=a11y-dynamic tracing-stop143playwright-cli -s=a11y-dynamic close144```145146## Fix Loop147148After execution, if any tests failed, follow the fix loop process in `references/fix-loop.md`.149Max 3 attempts. Only re-run failed test cases.150151Include fix attempt history in the report.152153## Report Generation154155After all 4 agents complete, merge results into `$OUTDIR/report.md` following the standard report format (see references/report-format.md).156157Group results by agent category:1581. Structure (TC-A1 through TC-A10)1592. Keyboard (TC-A11 through TC-A20)1603. Content (TC-A21 through TC-A30)1614. Dynamic (TC-A31 through TC-A40)162163## Cleanup164165```bash166playwright-cli -s=a11y-structure close 2>/dev/null167playwright-cli -s=a11y-keyboard close 2>/dev/null168playwright-cli -s=a11y-content close 2>/dev/null169playwright-cli -s=a11y-dynamic close 2>/dev/null170```
az9713