This project includes comprehensive accessibility testing using @axe-core/playwright to ensure WCAG 2.2 and WCAG 2.1 AA compliance across multiple test suites.

Overview

Accessibility testing is integrated into the E2E test suite using:

  • @axe-core/playwright: Automated accessibility testing
  • WCAG 2.1 AA Standards: Web Content Accessibility Guidelines Level AA
  • Keyboard Navigation Testing: Manual keyboard accessibility tests
  • Mobile Accessibility: Touch target and navigation testing

Table of Contents

Test Categories

1. WCAG 2.2 Responsive Accessibility Tests (@a11y-wcag2.2 tag)

File: tests/e2e/accessibility.spec.ts

Complete WCAG 2.2 compliance testing across all viewports (Desktop, Tablet, Mobile) organized by the four accessibility principles:

  • Principle 1: Perceivable - Information and interface components must be presentable to users
    • 1.1.1 Non-text Content
    • 1.3.1 Info and Relationships (heading hierarchy, landmarks)
    • 1.4.3 Color Contrast (AA level)
  • Principle 2: Operable - Interface components and navigation must be operable
    • 2.1.1 Keyboard Navigation (all functionality available via keyboard)
    • 2.4.4 Link Purpose (descriptive link text)
  • Principle 3: Understandable - Information and interface operation must be understandable
    • Text clarity and language identification
  • Principle 4: Robust - Content must work with assistive technologies
    • Proper semantic HTML and ARIA implementation

Run comprehensive WCAG 2.2 tests:

npm run test:a11y                       # Run all accessibility tests
npm run test:a11y:headed                # Run with browser UI
npx playwright test --grep @a11y-wcag2.2  # Run only WCAG 2.2 specific tests

WCAG 2.2 Compliance Framework

This project implements testing for WCAG 2.2 Level AA compliance with strong emphasis on accessibility principles.

WCAG 2.2 Key Success Criteria Tested

Principle 1: Perceivable

  • 1.1.1 Non-text Content - All images and graphics have meaningful alt text
  • 1.3.1 Info and Relationships - Proper heading hierarchy (h1→h2→h3), semantic landmarks, form label associations
  • 1.4.3 Color Contrast - 4.5:1 contrast for normal text, 3:1 for large text (AA level)

Principle 2: Operable

  • 2.1.1 Keyboard - All functionality available via keyboard navigation
  • 2.1.2 No Keyboard Trap - Users can navigate away from any component using only keyboard
  • 2.4.4 Link Purpose - Link purpose visible from link text alone or context
  • 2.5.5 Target Size - Touch targets minimum 44×44 CSS pixels (mobile)

Principle 3: Understandable

  • 3.1.1 Language of Page - Page language identified with lang attribute
  • 3.2.4 Consistent Identification - UI components with same function consistently labeled
  • 3.3.2 Labels or Instructions - Form inputs properly associated with labels or aria-labels

Principle 4: Robust

  • 4.1.2 Name, Role, Value - All UI components expose accessible name, role, value via DOM or ARIA
  • 4.1.3 Status Messages - Status messages announced to assistive technology

Tested WCAG 2.1 Level AA Features

The project also validates WCAG 2.1 AA requirements which are largely compatible with WCAG 2.2:

  • ✅ Color contrast ratios (4.5:1 normal, 3:1 large text)
  • ✅ Keyboard accessibility and focus management
  • ✅ Semantic structure and heading hierarchy
  • ✅ Form label associations
  • ✅ Link purpose from context
  • ✅ Focus visibility indicator

2. Responsive Viewport Testing

File: tests/e2e/accessibility.spec.ts (parameterized suite)

Accessibility validation across multiple viewports:

  • Desktop: 1280×720px - Standard desktop layout
  • Tablet: 768×1024px - Responsive tablet breakpoint
  • Mobile: 375×667px - Mobile viewport with additional tests:
    • Touch target sizing (minimum 44×44px - WCAG 2.5.5)
    • Mobile form accessibility
    • Responsive viewport and meta tag validation
    • Browser-optimized accessibility checks (Chromium, Firefox, WebKit)

WCAG 2.1 Compliance

Level A Requirements

  • ✅ Non-text content has alternatives
  • ✅ Captions for multimedia content
  • ✅ Content is adaptable
  • ✅ Color is not the only visual means of conveying information
  • ✅ Audio control available
  • ✅ Keyboard accessible
  • ✅ No seizure-inducing content
  • ✅ Bypass blocks mechanism
  • ✅ Page titles
  • ✅ Focus order
  • ✅ Link purpose
  • ✅ Language of page

Level AA Requirements

  • ✅ Captions for live content
  • ✅ Audio descriptions
  • ✅ Color contrast (4.5:1 normal text, 3:1 large text)
  • ✅ Visual presentation controls
  • ✅ Keyboard accessible (no keyboard traps)
  • ✅ Timing adjustable
  • ✅ Pause, stop, hide
  • ✅ Three flashes or below threshold
  • ✅ Navigation mechanisms
  • ✅ Headings and labels
  • ✅ Focus visible
  • ✅ Primary Accessibility Test Files
tests/e2e/
├── accessibility.spec.ts                   # WCAG 2.2 responsive suite (563 lines)
│   ├── Parameterized across Desktop (1280×720), Tablet (768×1024), Mobile (375×667)
│   ├── WCAG Principle 1: Perceivable (alt text, heading hierarchy, color contrast)
│   ├── WCAG Principle 2: Operable (keyboard nav, link purpose, touch targets)
│   ├── WCAG Principle 3: Understandable (language, labels)
│   ├── WCAG Principle 4: Robust (HTML parsing, ARIA)
│   └── Mobile-specific: Touch targets, forms, responsive viewport
├── code-block-accessibility.spec.ts        # Code block specific tests (453 lines)
│   ├── WCAG 1.3.1 - ARIA Attributes & Tabindex
│   ├── WCAG 2.1.1 - Keyboard Navigation
│   ├── axe-core Validation
│   └── Multi-page testing (20 documentation pages)

Test Patterns

WCAG 2.2 Comprehensive Audit

test("1.3.1 Info and Relationships - Heading hierarchy and landmarks", async ({ page }) => {
  // Check heading hierarchy (WCAG 1.3.1)
  await checkHeadingHierarchy(page);

  // Check for proper landmarks (WCAG 1.3.1)
  await checkLandmarks(page);

  // Check document structure and language (WCAG 3.1.1)
  await checkDocumentStructure(page);
});

Code Block Accessibility Testing

test("WCAG 1.3.1 - code blocks have proper ARIA attributes and role", async ({ browserName }) => {
  const codeBlocks = globalPage.locator('.highlight[role="img"]');
  const ariaLabel = await codeBlocks.first().getAttribute("aria-label");
  expect(ariaLabel).toMatch(/[Cc]ode/i);
});

test("WCAG 2.1.1 - code blocks are keyboard accessible and focusable", async ({ browserName }) => {
  // Tab to code block
  await globalPage.keyboard.press("Tab");
  const focused = await globalPage.evaluate(() => document.activeElement?.getAttribute("role"));
  expect(focused).toBe("img");
});

Axe-core Accessibility Audit

test("code blocks pass axe accessibility validation", async ({ browserName }) => {
  const results = await new AxeBuilder({ page }).withTags(["wcag2a", "wcag2aa", "wcag21aa"]).analyze();

  expect(results.violations).toEqual([]);
});

Mobile Accessibility Testing

test("Mobile elements have adequate touch targets (WCAG 2.5.5)", async ({ page }) => {
  await page.setViewportSize({ width: 375, height: 667 }); // iPhone SE

  const buttons = await page.locator("button");
  for (let i = 0; i < (await buttons.count()); i++) {
    const box = await buttons.nth(i).boundingBox();
    expect(box?.width).toBeGreaterThanOrEqual(44);
    expect(box?.height).toBeGreaterThanOrEqual(44);
  }

  const accessibilityScanResults = await new AxeBuilder({ page }).withRules(["color-contrast"]).analyze();

  expect(accessibilityScanResults.violations).toEqual([]);
});

Configuration

Package.json Scripts

{
  "test:a11y": "playwright test --grep @a11y",
  "test:a11y:headed": "playwright test --grep @a11y --headed"
}

Playwright Configuration

The accessibility tests use the same Playwright configuration with additional axe-core integration.

Best Practices

1. Semantic HTML

  • Use proper HTML5 semantic elements (<main>, <nav>, <header>, <footer>)
  • Ensure proper heading hierarchy (h1 → h2 → h3)
  • Use lists (<ul>, <ol>) for grouped content

2. ARIA Attributes

  • Add aria-label for elements without visible text
  • Use aria-describedby for additional descriptions
  • Implement aria-expanded for collapsible content
  • Use role attributes where semantic HTML is insufficient

3. Keyboard Navigation

  • Ensure all interactive elements are focusable
  • Provide visible focus indicators
  • Implement logical tab order
  • Add skip links for main content

4. Images and Media

  • Provide meaningful alt text for images
  • Use empty alt="" for decorative images
  • Add captions for videos
  • Provide transcripts for audio content

5. Forms

  • Associate labels with form controls
  • Provide clear error messages
  • Group related form fields with <fieldset> and <legend>
  • Indicate required fields clearly

Common Issues and Solutions

1. Color Contrast

Running Accessibility Tests

Quick Start Commands

# Run all accessibility tests (WCAG 2.2 + code blocks + mobile)
npm run test:a11y                   # All @a11y tagged tests

# Run specific test suites
npx playwright test --grep @WCAG22-a11y                          # WCAG 2.2 comprehensive
npx playwright test --grep @a11y-code-blocks                      # Code block specific
npx playwright test --grep @WCAG22-a11y-mobile                    # Mobile accessibility

# Code block testing
npx playwright test code-block-accessibility.spec.ts --project=chromium
TEST_ALL_CODE_PAGES=true npx playwright test code-block-accessibility.spec.ts  # All 20 pages

# With visual browser
npm run test:a11y:headed            # Open browser UI for debugging

Test Execution and Performance

  • WCAG 2.2 Comprehensive (~5-10 seconds): 4 browser contexts, 15+ specific criteria
  • Code Block Tests (~2-3 seconds default): Default page only
  • Code Block All Pages (~16-32 seconds): 20 documentation pages (sequential per browser)
  • Mobile Accessibility (~8-15 seconds): Multiple viewport sizes and touch target validation

Tools and Resources

Testing Tools

Browser Extensions

  • axe DevTools: Browser extension for accessibility testing
  • WAVE: Web accessibility evaluation tool
  • Lighthouse: Includes WCAG 2.1 AA accessibility audits

Test Coverage Summary

Automated Testing Coverage

Test Suite File WCAG Criteria Browser Support Viewports Tested
WCAG 2.2 Responsive accessibility.spec.ts 1.1.1, 1.3.1, 1.4.3, 2.1.1, 2.4.4, 2.5.5, 3.1.1, 4.1.1 All (Chromium, Firefox, WebKit) Desktop, Tablet, Mobile (3 sizes)
Code Block Accessibility code-block-accessibility.spec.ts 1.3.1, 2.1.1, axe-core audit All (Chromium, Firefox) Desktop (multi-page optional)

Known Limitations

  • WebKit on Linux WSL2: Known platform limitation with page content rendering - WebKit tests are skipped on Linux; fully functional on macOS
  • WCAG 2.1 vs 2.2: Project implements both WCAG 2.2 (latest) and WCAG 2.1 AA (compatible) criteria for broader compatibility

Last Updated: December 18, 2025 WCAG Versions Supported: 2.2 Level AA (primary), 2.1 Level AA (compatible) Testing Framework: Playwright 1.47+ with @axe-core/playwright Node.js: 22.8+ LTS Test Files: 4 main suites, 1000+ lines of accessibility testing code Performance: Full suite runs in ~30-60 seconds across all supported browsers”external noopener noreferrer” target=”_blank”>Section 508</a>: US federal accessibility standards

Accessibility Learning Resources

5. Form Labels

Issue: Form inputs without associated labels Solution: Use <label for="input-id"> or aria-label attributes

Integration with CI/CD

Accessibility tests can be integrated into continuous integration:

# .github/workflows/accessibility.yml
- name: Run Accessibility Tests
  run: |
    npm install
    npm run test:a11y

Tools and Resources

Testing Tools

Browser Extensions

  • axe DevTools: Browser extension for accessibility testing
  • WAVE: Web accessibility evaluation tool
  • Lighthouse: Includes accessibility audits

Guidelines and Standards

Reporting and Monitoring

Test Reports

Accessibility test results are included in standard Playwright reports:

  • HTML report: playwright-report/index.html
  • JSON report: test-results/results.json
  • JUnit report: test-results/junit.xml

Continuous Monitoring

Consider implementing:

  • Regular accessibility audits in CI/CD pipeline
  • Accessibility monitoring in production
  • User testing with assistive technologies
  • Periodic manual accessibility reviews

Last Updated: July 29, 2025 WCAG Version: 2.1 Level AA Testing Framework: Playwright + axe-core