# Accessibility Testing & Compliance Framework

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

- [WCAG 2.2 Guidelines](https://www.w3.org/TR/WCAG22/)
- [axe-core Rules](https://github.com/dequelabs/axe-core/blob/develop/doc/rule-descriptions.md)
- [WAI-ARIA Practices](https://www.w3.org/WAI/ARIA/apg/)
- [WebAIM Resources](https://webaim.org/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
