sawrus/accessibility-testing

Accessibility Testing Skill

Expertise: axe-core automation, WCAG 2.1 AA, keyboard testing, screen reader testing (NVDA/VoiceOver), CI gates.

Automated Testing (Playwright + axe-core)

// tests/a11y/checkout.a11y.spec.ts
import AxeBuilder from '@axe-core/playwright';

test.describe('Checkout a11y', () => {
  test('step 1 address form has no WCAG AA violations', async ({ page }) => {
    await page.goto('/checkout/address');
    await page.waitForLoadState('networkidle');  // Wait for dynamic content

    const results = await new AxeBuilder({ page })
      .withTags(['wcag2a', 'wcag2aa', 'wcag21aa'])
      .exclude('#third-party-widget')  // Exclude known third-party violations
      .analyze();

    // Report violations with full context for easier debugging
    if (results.violations.length > 0) {
      const report = results.violations.map(v => ({
        id: v.id,
        impact: v.impact,
        description: v.description,
        elements: v.nodes.map(n => n.html).slice(0, 3),
      }));
      console.log(JSON.stringify(report, null, 2));
    }

    // Block on critical/serious only; log moderate/minor as warnings
    const blocking = results.violations.filter(
      v => v.impact === 'critical' || v.impact === 'serious'
    );
    expect(blocking).toHaveLength(0);
  });

  test('form inputs all have associated labels', async ({ page }) => {
    await page.goto('/checkout/address');
    const results = await new AxeBuilder({ page })
      .withRules(['label', 'label-content-name-mismatch'])
      .analyze();
    expect(results.violations).toHaveLength(0);
  });
});

Keyboard Navigation Checklist (Manual)

Run this checklist on every new feature with interactive elements:

Tab order:
[ ] Tab key moves focus through all interactive elements in visual order
[ ] Focus never gets trapped (except modals — see below)
[ ] Focus is always visible (never hidden by CSS outline: none)

Activation:
[ ] Buttons activate with Enter and Space
[ ] Links activate with Enter only
[ ] Select/dropdown navigates with Arrow keys

Modal dialogs:
[ ] Focus moves to modal when it opens
[ ] Tab is trapped inside modal while open
[ ] Escape key closes modal
[ ] Focus returns to the trigger element when modal closes

Forms:
[ ] Each input has a visible label (not just placeholder)
[ ] Error messages are associated with their input (aria-describedby)
[ ] Required fields marked with aria-required="true"
[ ] Submit activates with Enter from any field

Screen Reader Testing (Quick Reference)

VoiceOver (macOS/iOS)

Enable:  Cmd + F5
Navigate: VO + Right (next element), VO + Left (previous)
Forms:   VO + Shift + Down (enter form mode)
Tables:  VO + Shift + Right/Left (navigate columns)

NVDA (Windows — free)

Download: nvaccess.org/download
Navigate: Tab (interactive), H (headings), F (forms), L (lists)
Test:     Browse mode (default) vs. Forms mode (Enter to switch)

Things to verify with screen reader:

• [ ] Page title is descriptive and unique
• [ ] Headings form a logical hierarchy (h1 → h2 → h3)
• [ ] Images have meaningful alt text (or alt="" for decorative)
• [ ] Error messages read aloud when form submitted with errors
• [ ] Dynamic content changes (toast notifications) announced via aria-live
• [ ] Form field labels and error messages read together

CI Integration

# .github/workflows/a11y.yml
a11y:
  steps:
    - name: Run accessibility audit
      run: npx playwright test tests/a11y/ --reporter=html
    - name: Upload report
      uses: actions/upload-artifact@v4
      with:
        name: a11y-report
        path: playwright-report/

WCAG 2.1 AA Quick Reference

| Criterion | Level | What it means | |---|---|---| | 1.1.1 Non-text content | A | Images need alt text | | 1.3.1 Info & Relationships | A | Structure conveyed programmatically | | 1.4.3 Contrast (Minimum) | AA | 4.5:1 normal text, 3:1 large text | | 2.1.1 Keyboard | A | All functionality keyboard accessible | | 2.4.3 Focus Order | A | Focus order preserves meaning | | 2.4.7 Focus Visible | AA | Keyboard focus always visible | | 3.3.1 Error Identification | A | Errors described in text | | 3.3.2 Labels or Instructions | A | Form inputs have labels | | 4.1.2 Name, Role, Value | A | UI components have accessible names |