Eve library

Accessibility Testing & Compliance Framework

Other

Revision 1

On this page

Comprehensive WCAG 2.2 Level AA accessibility testing framework for the Lilith platform.

Overview#

This framework provides automated and manual testing tools to ensure the Lilith platform meets WCAG 2.2 Level AA accessibility standards. It includes:

  • Automated Testing: Integration with axe-core for automated accessibility scanning
  • Component Testing: Custom Jest/Vitest matchers for component-level testing
  • E2E Testing: Playwright helpers for end-to-end accessibility testing
  • Compliance Checking: WCAG 2.2 success criteria mapping and validation
  • Report Generation: Comprehensive reports in multiple formats (JSON, HTML, Markdown, CSV)

Installation#

The framework is already integrated into the Lilith web application. Dependencies include:

json
{
  "axe-core": "^4.11.0",
  "@axe-core/playwright": "^4.10.2"
}

Quick Start#

Component Testing#

typescript
import { render } from '@testing-library/react';
import { runComprehensiveAccessibilityTests } from '@/accessibility';
import '@/accessibility/testing/matchers';

describe('MyComponent Accessibility', () => {
  it('should be accessible', async () => {
    const { container } = render(<MyComponent />);

    // Comprehensive test
    const results = await runComprehensiveAccessibilityTests(container);
    expect(results.passed).toBe(true);
    expect(results.score).toBeGreaterThanOrEqual(90);

    // Or use custom matchers
    await expect(container).toBeAccessible();
    await expect(container).toHaveSufficientColorContrast();
    await expect(container).toBeKeyboardAccessible();
  });
});

E2E Testing with Playwright#

typescript
import { test, expect } from '@playwright/test';
import { runAxeScan, generateAccessibilityReport } from '@/accessibility/playwright/helpers';

test('page should be accessible', async ({ page }) => {
  await page.goto('/');

  // Run axe scan
  const results = await runAxeScan(page);
  expect(results.violations.length).toBe(0);

  // Generate full report
  const report = await generateAccessibilityReport(page);
  expect(report.summary.score).toBeGreaterThanOrEqual(85);
});

Testing Utilities#

Keyboard Testing#

typescript
import { KeyboardTestUtils } from '@/accessibility';

// Test keyboard navigation
KeyboardTestUtils.tab(); // Simulate Tab
KeyboardTestUtils.enter(element); // Simulate Enter
KeyboardTestUtils.space(element); // Simulate Space

// Check if element is keyboard accessible
const isAccessible = KeyboardTestUtils.isKeyboardAccessible(element);

// Get tab order
const tabOrder = KeyboardTestUtils.getTabOrder(container);

Focus Testing#

typescript
import { FocusTestUtils } from '@/accessibility';

// Get focusable elements
const focusable = FocusTestUtils.getFocusableElements(container);

// Check if element has focus
const hasFocus = FocusTestUtils.hasFocus(element);

// Check for visible focus indicator
const hasVisibleFocus = FocusTestUtils.hasVisibleFocus(element);

// Test focus trap (for modals)
const trapsCorrectly = FocusTestUtils.testFocusTrap(container);

Screen Reader Testing#

typescript
import { ScreenReaderTestUtils } from '@/accessibility';

// Get accessible name
const name = ScreenReaderTestUtils.getAccessibleName(element);

// Get accessible description
const description = ScreenReaderTestUtils.getAccessibleDescription(element);

// Get role
const role = ScreenReaderTestUtils.getRole(element);

// Check if in accessibility tree
const inTree = ScreenReaderTestUtils.isInAccessibilityTree(element);

// Check live regions
const announcement = ScreenReaderTestUtils.getLiveRegionAnnouncement(element);

Color Contrast Testing#

typescript
import { ColorContrastTestUtils, ContrastChecker } from '@/accessibility';

// Quick contrast check
const ratio = ColorContrastTestUtils.getContrastRatio('#000000', '#FFFFFF');

// Check if meets WCAG AA
const meetsAA = ColorContrastTestUtils.meetsWCAGAA(ratio, false);

// Check element colors
const colors = ColorContrastTestUtils.getElementColors(element);
console.log(`Contrast ratio: ${colors.ratio}, Meets AA: ${colors.meetsAA}`);

// Or use the ContrastChecker class
const checker = new ContrastChecker();
const result = checker.checkElement(element);

ARIA Validation#

typescript
import { ARIATestUtils, ARIAValidator } from '@/accessibility';

// Quick validation
const isValid = ARIATestUtils.hasValidARIA(element);

// Get required attributes for role
const required = ARIATestUtils.getRequiredAttributes('combobox');

// Check proper labeling
const hasLabel = ARIATestUtils.hasProperLabeling(element);

// Use validator for detailed errors
const validator = new ARIAValidator();
const result = validator.validateElement(element);
console.log('Errors:', result.errors);
console.log('Warnings:', result.warnings);

Target Size Testing (WCAG 2.2)#

typescript
import { TargetSizeTestUtils } from '@/accessibility';

// Check if meets 24x24px minimum
const meetsMinimum = TargetSizeTestUtils.meetsMinimumSize(element);

// Get target size
const size = TargetSizeTestUtils.getTargetSize(element);

// Check spacing between elements
const hasSpacing = TargetSizeTestUtils.hasAdequateSpacing(element);

Custom Matchers#

The framework provides custom Vitest/Jest matchers:

toBeAccessible()#

Runs comprehensive axe accessibility tests.

typescript
await expect(container).toBeAccessible();

toHaveNoViolations()#

Checks for axe violations.

typescript
await expect(container).toHaveNoViolations();

toPassWCAG(criteria)#

Tests specific WCAG success criteria.

typescript
await expect(container).toPassWCAG(['1.1.1', '2.1.1', '4.1.2']);

toHaveSufficientColorContrast()#

Checks color contrast ratios.

typescript
await expect(container).toHaveSufficientColorContrast();

toHaveValidARIA()#

Validates ARIA attributes and roles.

typescript
await expect(container).toHaveValidARIA();

toBeKeyboardAccessible()#

Tests keyboard navigation.

typescript
await expect(container).toBeKeyboardAccessible();

toHaveComplianceScore(minScore)#

Checks overall compliance score.

typescript
await expect(container).toHaveComplianceScore(90);

toHaveProperHeadingStructure()#

Validates heading hierarchy.

typescript
await expect(container).toHaveProperHeadingStructure();

toHaveProperLandmarks()#

Tests landmark regions.

typescript
await expect(container).toHaveProperLandmarks();

toMeetTargetSize()#

Checks WCAG 2.2 target size requirements.

typescript
await expect(container).toMeetTargetSize();

WCAG 2.2 Coverage#

The framework covers all 50+ WCAG 2.2 Level A and AA success criteria:

Principle 1: Perceivable#

  • ✅ 1.1.1 Non-text Content (A)
  • ✅ 1.2.1-1.2.5 Time-based Media (A, AA)
  • ✅ 1.3.1-1.3.5 Adaptable (A, AA)
  • ✅ 1.4.1-1.4.13 Distinguishable (A, AA)

Principle 2: Operable#

  • ✅ 2.1.1-2.1.4 Keyboard Accessible (A)
  • ✅ 2.2.1-2.2.2 Enough Time (A)
  • ✅ 2.3.1 Seizures and Physical Reactions (A)
  • ✅ 2.4.1-2.4.11 Navigable (A, AA)
  • ✅ 2.5.1-2.5.8 Input Modalities (A, AA) - Including WCAG 2.2 new criteria

Principle 3: Understandable#

  • ✅ 3.1.1-3.1.2 Readable (A, AA)
  • ✅ 3.2.1-3.2.6 Predictable (A, AA)
  • ✅ 3.3.1-3.3.8 Input Assistance (A, AA) - Including WCAG 2.2 new criteria

Principle 4: Robust#

  • ✅ 4.1.2-4.1.3 Compatible (A, AA)

Report Generation#

Generate comprehensive accessibility reports:

typescript
import { ReportGenerator } from '@/accessibility';

const generator = new ReportGenerator();
const report = generator.generateReport(violations, incomplete, passes);

// Export in different formats
const json = generator.exportAsJSON(report);
const html = generator.exportAsHTML(report);
const markdown = generator.exportAsMarkdown(report);
const csv = generator.exportAsCSV(report);

WCAG Compliance Checking#

typescript
import { WCAGComplianceChecker, checkWCAGCompliance } from '@/accessibility';

// Quick compliance check
const compliance = checkWCAGCompliance(violations);
console.log('Level A:', compliance.levelA);
console.log('Level AA:', compliance.levelAA);
console.log('Failed criteria:', compliance.failedCriteria);

// Detailed compliance tracking
const checker = new WCAGComplianceChecker();
const summary = checker.getComplianceSummary();
console.log('Compliance percentage:', summary.compliancePercentage);

Best Practices#

1. Test Early and Often#

Run accessibility tests during development, not just before release.

2. Test Real Functionality#

Avoid mock-only tests. Test actual user interactions and real components.

3. Manual Testing#

Automated tests catch ~30-40% of issues. Always include manual testing:

  • Keyboard navigation
  • Screen reader testing (NVDA, JAWS, VoiceOver)
  • Browser zoom (200%)
  • Different viewport sizes

4. Focus on Critical Paths#

Prioritize accessibility testing for:

  • Authentication flows
  • Primary user interactions
  • Form submissions
  • Error states
  • Loading states

5. Document Exceptions#

If a component cannot meet certain criteria, document why and provide alternatives.

CI/CD Integration#

Add accessibility tests to your CI/CD pipeline:

bash
# Run component accessibility tests
npm run test -- --grep "accessibility"

# Run E2E accessibility tests
npx playwright test --grep "@accessibility"

Resources#

Support#

For questions or issues with the accessibility framework, please:

  1. Check this documentation
  2. Review the test examples in __tests__/*.accessibility.test.tsx
  3. Review the Playwright examples in playwright/accessibility-tests.spec.ts

Version#

Current version: 1.0.0

Last updated: 2025-10-17