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:
{
"axe-core": "^4.11.0",
"@axe-core/playwright": "^4.10.2"
}
Quick Start#
Component Testing#
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#
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#
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#
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#
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#
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#
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)#
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.
await expect(container).toBeAccessible();
toHaveNoViolations()#
Checks for axe violations.
await expect(container).toHaveNoViolations();
toPassWCAG(criteria)#
Tests specific WCAG success criteria.
await expect(container).toPassWCAG(['1.1.1', '2.1.1', '4.1.2']);
toHaveSufficientColorContrast()#
Checks color contrast ratios.
await expect(container).toHaveSufficientColorContrast();
toHaveValidARIA()#
Validates ARIA attributes and roles.
await expect(container).toHaveValidARIA();
toBeKeyboardAccessible()#
Tests keyboard navigation.
await expect(container).toBeKeyboardAccessible();
toHaveComplianceScore(minScore)#
Checks overall compliance score.
await expect(container).toHaveComplianceScore(90);
toHaveProperHeadingStructure()#
Validates heading hierarchy.
await expect(container).toHaveProperHeadingStructure();
toHaveProperLandmarks()#
Tests landmark regions.
await expect(container).toHaveProperLandmarks();
toMeetTargetSize()#
Checks WCAG 2.2 target size requirements.
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:
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#
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:
# 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:
- Check this documentation
- Review the test examples in
__tests__/*.accessibility.test.tsx - Review the Playwright examples in
playwright/accessibility-tests.spec.ts
Version#
Current version: 1.0.0
Last updated: 2025-10-17