# QA Accessibility Test Writer

> Generate accessibility tests for WCAG 2.2 compliance using axe-core, Pa11y, and Lighthouse with automated checks for ARIA patterns, keyboard navigation, color contrast, and screen reader support.

- Skill: `azanir/qa-accessibility-test-writer` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add azanir/qa-accessibility-test-writer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/azanir/qa-accessibility-test-writer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: azanir (https://skillmd.com/u/azanir)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/azanir/qa-accessibility-test-writer

---


# QA Accessibility Test Writer

## Purpose

Write accessibility tests ensuring WCAG 2.2 compliance. Transform NFR accessibility criteria (from qa-nfr-analyst) and application context into executable accessibility test scripts using axe-core, Pa11y, and Lighthouse. Support automated checks for ARIA patterns, keyboard navigation, focus management, color contrast, text alternatives, semantic HTML, form labels, skip links, responsive text sizing, and screen reader compatibility.

## Trigger Phrases

- "Write accessibility tests for [app/page]"
- "Generate WCAG 2.2 compliance tests"
- "Create axe-core tests for [framework]"
- "Accessibility tests for keyboard navigation"
- "ARIA and color contrast tests"
- "Pa11y/Lighthouse accessibility audit setup"
- "Screen reader compatibility tests"
- "Accessibility test scripts from NFR analysis"

## WCAG 2.2 Levels

| Level | Description | Typical Use |
|-------|--------------|-------------|
| **A** | Minimum; required for basic accessibility | Legal baseline |
| **AA** | Standard target; addresses major barriers | Most projects |
| **AAA** | Enhanced; highest conformance | Specialized contexts |

See `references/wcag-tests.md` for test scenarios per success criteria with code examples.

## Tools

| Tool | Purpose |
|------|---------|
| **axe-core** | Programmatic WCAG checks; integrates with Playwright, Cypress, Jest |
| **Pa11y** | CLI + Node API; batch page audits, CI integration |
| **Lighthouse** | Chrome DevTools Protocol; full accessibility audit with scores |

## Test Categories

| Category | Techniques | Tools |
|----------|-------------|-------|
| **ARIA patterns** | Roles, states, properties, live regions | axe-core |
| **Keyboard navigation** | Tab order, focus traps, shortcuts | Playwright/Cypress |
| **Focus management** | Visible focus, focus order, skip links | axe-core, custom |
| **Color contrast** | 4.5:1 (normal), 3:1 (large) | axe-core, Lighthouse |
| **Text alternatives** | Alt text, aria-label, captions | axe-core |
| **Semantic HTML** | Headings, landmarks, lists | axe-core |
| **Form labels** | Labels, error identification, autocomplete | axe-core, custom |
| **Skip links** | Bypass blocks (2.4.1) | axe-core, custom |
| **Responsive text sizing** | 200% resize, reflow | Lighthouse, custom |
| **Screen reader compatibility** | Name, role, value (4.1.2) | axe-core, manual |

## Workflow

1. **Read NFR analysis** — From qa-nfr-analyst; extract WCAG criteria and target level (A/AA/AAA)
2. **Map WCAG success criteria** — Align requirements to testable checkpoints (see `references/wcag-tests.md`)
3. **Generate accessibility test scripts** — Playwright + @axe-core/playwright, Cypress + cypress-axe, Jest + jest-axe
4. **Configure tools** — axe-core rules, Pa11y config, Lighthouse thresholds
5. **Run audits** — Execute tests; produce audit reports and WCAG compliance matrix

## Integration

| Framework | Package | Usage |
|-----------|---------|-------|
| **Playwright** | @axe-core/playwright | `await expect(page).toPassAxe()` or `axe.run(page)` |
| **Cypress** | cypress-axe | `cy.injectAxe(); cy.checkA11y()` |
| **Jest** | jest-axe | `expect(container).toHaveNoViolations()` (React Testing Library) |

See `references/axe-core-patterns.md` for integration patterns and examples.

## Output

- **Accessibility test scripts** — `tests/accessibility/` or `e2e/a11y/` with TS/JS files
- **Audit reports** — JSON/HTML summaries of violations, impact, remediation
- **WCAG compliance matrix** — Mapping of success criteria to pass/fail status

## References

- `references/wcag-tests.md` — WCAG 2.2 test scenarios per success criteria with code examples
- `references/axe-core-patterns.md` — axe-core integration patterns for Playwright, Cypress, Jest
- `references/best-practices.md` — Automated vs manual, screen reader testing, keyboard testing

## Scope

**Can do (autonomous):**
- Generate accessibility test scripts from NFR analysis or WCAG criteria
- Create axe-core/Pa11y/Lighthouse configurations
- Write Playwright, Cypress, or Jest accessibility tests
- Map WCAG 2.2 success criteria to test cases
- Call qa-nfr-analyst for WCAG criteria when needed
- Use qa-diagram-generator for accessibility flow diagrams

**Cannot do (requires confirmation):**
- Add dependencies not in package.json
- Override project accessibility target level (A/AA/AAA)
- Change WCAG conformance scope without approval

**Will not do (out of scope):**
- Execute tests (user runs them)
- Perform manual screen reader testing (provide guidance only)
- Implement accessibility fixes in application code

## Quality Checklist

- [ ] Tests cover WCAG 2.2 criteria relevant to the application
- [ ] Target level (A/AA/AAA) specified and rules configured accordingly
- [ ] axe-core rules/tags aligned with WCAG level (wcag2a, wcag2aa, wcag2aaa)
- [ ] Keyboard navigation tests for interactive components
- [ ] Focus visible and focus order verified where applicable
- [ ] File naming follows `*.a11y.spec.ts` or `test_*_accessibility.ts`
- [ ] References to WCAG success criterion IDs where applicable
- [ ] Audit report includes impact, description, and remediation guidance

## Troubleshooting

| Symptom | Likely Cause | Fix |
|---------|--------------|-----|
| axe-core reports no violations but page is inaccessible | Dynamic content not loaded, shadow DOM | Wait for content; use `include` for shadow roots |
| False positives (decorative images) | axe flags alt="" on img | Use `aria-hidden="true"` or `role="presentation"` for decorative |
| Pa11y timeout | Slow page load, SPA | Increase timeout; wait for network idle |
| Lighthouse score inconsistent | Network variance, animations | Run multiple times; use median; disable animations |
| Keyboard test fails (focus not visible) | Custom focus styles missing | Add `:focus-visible` styles; verify in test |
| cypress-axe "injectAxe" fails | Page not ready | Call `cy.injectAxe()` after `cy.visit` and content load |