cremote/docs/ADA_TESTING_GUIDE.md

# Cremote ADA/WCAG Accessibility Testing Guide

## Overview

Cremote provides comprehensive automated accessibility testing tools that cover approximately **70% of WCAG 2.1 Level AA criteria**. This guide documents all accessibility testing capabilities, their usage, and best practices for conducting ADA compliance audits.

## Table of Contents

1. [Quick Start](#quick-start)
2. [Available Tools](#available-tools)
3. [WCAG Coverage](#wcag-coverage)
4. [Testing Workflows](#testing-workflows)
5. [Tool Reference](#tool-reference)
6. [Best Practices](#best-practices)
7. [Limitations](#limitations)

---

## Quick Start

### Basic Accessibility Audit

```bash
# 1. Navigate to page
cremote navigate --url https://example.com

# 2. Run axe-core automated tests (covers ~57% of WCAG 2.1 AA)
cremote inject-axe
cremote run-axe --run-only wcag2a,wcag2aa

# 3. Check color contrast (WCAG 1.4.3, 1.4.6)
cremote contrast-check

# 4. Test keyboard navigation (WCAG 2.1.1, 2.4.7)
cremote keyboard-test

# 5. Test zoom functionality (WCAG 1.4.4)
cremote zoom-test --zoom-levels 1.0,2.0,4.0

# 6. Test responsive reflow (WCAG 1.4.10)
cremote reflow-test --widths 320,1280
```

---

## Available Tools

### 1. **web_inject_axe_cremotemcp** - Axe-Core Integration
Injects the industry-standard axe-core accessibility testing library.

**WCAG Coverage:** ~57% of WCAG 2.1 Level AA criteria

**Usage:**
```json
{
  "tool": "web_inject_axe_cremotemcp",
  "arguments": {
    "tab": "optional-tab-id",
    "axe_version": "4.8.0",
    "timeout": 30
  }
}
```

### 2. **web_run_axe_cremotemcp** - Run Axe Tests
Executes axe-core accessibility tests with configurable options.

**WCAG Coverage:** Comprehensive automated testing including:
- 1.1.1 Non-text Content
- 1.3.1 Info and Relationships
- 1.4.1 Use of Color
- 2.1.1 Keyboard
- 2.4.1 Bypass Blocks
- 3.1.1 Language of Page
- 4.1.1 Parsing
- 4.1.2 Name, Role, Value

**Usage:**
```json
{
  "tool": "web_run_axe_cremotemcp",
  "arguments": {
    "tab": "optional-tab-id",
    "run_only": ["wcag2a", "wcag2aa", "wcag21aa"],
    "rules": {
      "color-contrast": {"enabled": true}
    },
    "timeout": 30
  }
}
```

**Output:**
- Violations with severity, impact, and remediation guidance
- Passes (successful checks)
- Incomplete (manual review needed)
- Inapplicable rules

### 3. **web_contrast_check_cremotemcp** - Color Contrast Testing
Calculates WCAG-compliant contrast ratios for all text elements.

**WCAG Coverage:**
- 1.4.3 Contrast (Minimum) - Level AA
- 1.4.6 Contrast (Enhanced) - Level AAA

**Usage:**
```json
{
  "tool": "web_contrast_check_cremotemcp",
  "arguments": {
    "tab": "optional-tab-id",
    "selector": "body",
    "timeout": 10
  }
}
```

**Features:**
- Uses official WCAG 2.1 relative luminance formula
- Traverses parent elements to find effective backgrounds
- Detects large text (18pt+ or 14pt bold+) for different thresholds
- Returns AA (4.5:1 normal, 3:1 large) and AAA (7:1 normal, 4.5:1 large) compliance

**Output Example:**
```
Color Contrast Check Results:

Summary:
  Total Elements Checked: 45
  WCAG AA Compliance:
    Passed: 38
    Failed: 7
  WCAG AAA Compliance:
    Passed: 25
    Failed: 20

WCAG AA Violations:
  - p:nth-of-type(3): 3.2:1 (required: 4.5:1)
    Text: This text has insufficient contrast
    Colors: rgb(128, 128, 128) on rgb(255, 255, 255)
```

### 4. **web_keyboard_test_cremotemcp** - Keyboard Navigation Testing
Tests keyboard accessibility and focus management.

**WCAG Coverage:**
- 2.1.1 Keyboard - Level A
- 2.4.7 Focus Visible - Level AA

**Usage:**
```json
{
  "tool": "web_keyboard_test_cremotemcp",
  "arguments": {
    "tab": "optional-tab-id",
    "timeout": 10
  }
}
```

**Features:**
- Identifies 11 types of interactive elements (links, buttons, inputs, ARIA roles)
- Tests focusability of each element
- Validates visible focus indicators by comparing focused/blurred styles
- Detects keyboard traps
- Returns detailed tab order

**Output Example:**
```
Keyboard Navigation Test Results:

Summary:
  Total Interactive Elements: 38
  Focusable: 32
  Not Focusable: 4
  Missing Focus Indicator: 6
  Keyboard Traps Detected: 0

High Severity Issues (10):
  - no_focus_indicator: Interactive element lacks visible focus indicator
    Element: button.submit-btn
  - not_focusable: Interactive element is not keyboard focusable
    Element: div[role="button"]

Tab Order (first 5 elements):
  1. a.logo [a] Home - Focus: ✓
  2. a.nav-link [a] About - Focus: ✓
  3. button.menu [button] Menu - Focus: ✗
```

### 5. **web_zoom_test_cremotemcp** - Zoom Testing
Tests page functionality at different zoom levels.

**WCAG Coverage:**
- 1.4.4 Resize Text - Level AA

**Usage:**
```json
{
  "tool": "web_zoom_test_cremotemcp",
  "arguments": {
    "tab": "optional-tab-id",
    "zoom_levels": [1.0, 2.0, 4.0],
    "timeout": 10
  }
}
```

**Features:**
- Uses Chrome DevTools Protocol Emulation.setDeviceMetricsOverride
- Tests at configurable zoom levels (defaults: 100%, 200%, 400%)
- Checks for horizontal scrolling (WCAG 1.4.10 violation)
- Validates text readability (minimum 9px font size)
- Counts overflowing elements
- Automatically resets viewport after testing

**Output Example:**
```
Zoom 200% ✓ PASS:
  Viewport: 1280x720
  Content: 1280x1450
  Horizontal Scroll: false
  Overflowing Elements: 0
  Text Readable: true

Zoom 400% ✗ FAIL:
  Viewport: 1280x720
  Content: 1350x2100
  Horizontal Scroll: true
  Overflowing Elements: 3
  Text Readable: true
```

### 6. **web_reflow_test_cremotemcp** - Responsive Reflow Testing
Tests responsive design at WCAG breakpoints.

**WCAG Coverage:**
- 1.4.10 Reflow - Level AA

**Usage:**
```json
{
  "tool": "web_reflow_test_cremotemcp",
  "arguments": {
    "tab": "optional-tab-id",
    "widths": [320, 1280],
    "timeout": 10
  }
}
```

**Features:**
- Tests at WCAG 1.4.10 breakpoints (defaults: 320px, 1280px)
- Resizes viewport using Emulation.setDeviceMetricsOverride
- Detects horizontal scrolling violations
- Verifies responsive layout (content width ≤ viewport width)
- Counts overflowing elements
- Automatically resets viewport after testing

**Output Example:**
```
320px Width ✓ PASS:
  Viewport: 320x568
  Content: 320x1200
  Horizontal Scroll: false
  Responsive Layout: true
  Overflowing Elements: 0

1280px Width ✓ PASS:
  Viewport: 1280x720
  Content: 1280x900
  Horizontal Scroll: false
  Responsive Layout: true
  Overflowing Elements: 0
```

### 7. **console_command_cremotemcp** (Enhanced) - Library Injection
Execute JavaScript with optional library injection.

**Usage:**
```json
{
  "tool": "console_command_cremotemcp",
  "arguments": {
    "command": "axe.run()",
    "inject_library": "axe",
    "tab": "optional-tab-id",
    "timeout": 5
  }
}
```

**Supported Libraries:**
- `axe` / `axe-core` - Axe-core accessibility testing
- `jquery` - jQuery library
- `lodash` - Lodash utility library
- `moment` - Moment.js date library
- `underscore` - Underscore.js utility library
- Or any custom URL

### 8. **web_screenshot_cremotemcp** (Enhanced) - Accessibility Screenshots
Capture screenshots with zoom and viewport control.

**Usage:**
```json
{
  "tool": "web_screenshot_cremotemcp",
  "arguments": {
    "output": "/path/to/screenshot.png",
    "zoom_level": 2.0,
    "width": 320,
    "height": 568,
    "full_page": false,
    "timeout": 5
  }
}
```

**Use Cases:**
- Document zoom level issues
- Capture responsive breakpoint layouts
- Visual regression testing for accessibility fixes

### 9. **get_accessibility_tree_cremotemcp** (Enhanced) - Accessibility Tree with Contrast
Retrieve accessibility tree with optional contrast annotations.

**Usage:**
```json
{
  "tool": "get_accessibility_tree_cremotemcp",
  "arguments": {
    "tab": "optional-tab-id",
    "depth": 5,
    "include_contrast": true,
    "timeout": 5
  }
}
```

**Features:**
- Full Chrome accessibility tree
- Optional contrast check availability annotation
- Depth limiting for large pages
- Includes roles, names, descriptions, properties

---

## WCAG Coverage

### Automated Testing Coverage (~70% of WCAG 2.1 Level AA)

| WCAG Criterion | Level | Tool(s) | Coverage |
|----------------|-------|---------|----------|
| 1.1.1 Non-text Content | A | axe-core | Partial |
| 1.3.1 Info and Relationships | A | axe-core | Partial |
| 1.4.1 Use of Color | A | axe-core | Partial |
| 1.4.3 Contrast (Minimum) | AA | contrast-check, axe-core | Full |
| 1.4.4 Resize Text | AA | zoom-test | Full |
| 1.4.6 Contrast (Enhanced) | AAA | contrast-check | Full |
| 1.4.10 Reflow | AA | reflow-test | Full |
| 2.1.1 Keyboard | A | keyboard-test, axe-core | Partial |
| 2.4.1 Bypass Blocks | A | axe-core | Full |
| 2.4.7 Focus Visible | AA | keyboard-test | Full |
| 3.1.1 Language of Page | A | axe-core | Full |
| 4.1.1 Parsing | A | axe-core | Full |
| 4.1.2 Name, Role, Value | A | axe-core, a11y-tree | Partial |

### Manual Testing Required (~30%)

- 1.2.x Audio/Video (captions, audio descriptions)
- 1.4.2 Audio Control
- 2.2.x Timing (pause, stop, hide)
- 2.3.x Seizures (flashing content)
- 2.4.x Navigation (page titles, link purpose, headings)
- 3.2.x Predictable (on focus, on input)
- 3.3.x Input Assistance (error identification, labels)

---

## Testing Workflows

### Complete ADA Audit Workflow

```bash
# 1. Initial Setup
cremote navigate --url https://example.com
cremote screenshot --output baseline.png

# 2. Automated Testing (Axe-Core)
cremote inject-axe
cremote run-axe --run-only wcag2a,wcag2aa,wcag21aa > axe-results.json

# 3. Specialized Tests
cremote contrast-check > contrast-results.txt
cremote keyboard-test > keyboard-results.txt
cremote zoom-test --zoom-levels 1.0,2.0,4.0 > zoom-results.txt
cremote reflow-test --widths 320,1280 > reflow-results.txt

# 4. Visual Documentation
cremote screenshot --output zoom-200.png --zoom-level 2.0
cremote screenshot --output mobile-320.png --width 320 --height 568
cremote screenshot --output desktop-1280.png --width 1280 --height 720

# 5. Accessibility Tree Analysis
cremote get-accessibility-tree --include-contrast true > a11y-tree.json
```

### Quick Compliance Check

```bash
# Run all core tests in sequence
cremote inject-axe && \
cremote run-axe && \
cremote contrast-check && \
cremote keyboard-test && \
cremote zoom-test && \
cremote reflow-test
```

---

## Best Practices

### 1. Test Early and Often
- Run automated tests during development
- Integrate into CI/CD pipelines
- Test on every significant UI change

### 2. Combine Automated and Manual Testing
- Use automated tools for ~70% coverage
- Manually verify complex interactions
- Test with actual assistive technologies

### 3. Test Multiple Breakpoints
```bash
# Test common device sizes
cremote reflow-test --widths 320,375,768,1024,1280,1920
```

### 4. Document Visual Issues
```bash
# Capture evidence of issues
cremote screenshot --output issue-contrast.png
cremote screenshot --output issue-zoom-400.png --zoom-level 4.0
```

### 5. Prioritize Violations
- **Critical:** Axe violations with "critical" or "serious" impact
- **High:** Contrast failures, keyboard traps, missing focus indicators
- **Medium:** Zoom/reflow issues, incomplete axe checks
- **Low:** Best practice recommendations

---

## Limitations

### What These Tools Cannot Test

1. **Semantic Meaning** - Tools can detect missing alt text but not if it's meaningful
2. **Cognitive Load** - Cannot assess if content is easy to understand
3. **Timing** - Cannot fully test time-based media or auto-updating content
4. **Context** - Cannot determine if link text makes sense out of context
5. **User Experience** - Cannot replace testing with real users and assistive technologies

### Known Issues

- **Contrast Detection:** May not accurately detect contrast on complex backgrounds (gradients, images)
- **Keyboard Traps:** Detection is heuristic-based and may miss complex traps
- **Dynamic Content:** Tests are point-in-time; may miss issues in SPAs or dynamic updates
- **Shadow DOM:** Limited support for components using Shadow DOM

---

## Integration Examples

### CI/CD Integration

```yaml
# .github/workflows/accessibility.yml
name: Accessibility Tests
on: [push, pull_request]
jobs:
  a11y-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Start cremote daemon
        run: cremote-daemon &
      - name: Run accessibility tests
        run: |
          cremote navigate --url http://localhost:3000
          cremote inject-axe
          cremote run-axe --run-only wcag2aa > axe-results.json
          cremote contrast-check > contrast-results.txt
      - name: Upload results
        uses: actions/upload-artifact@v2
        with:
          name: accessibility-results
          path: |
            axe-results.json
            contrast-results.txt
```

### Programmatic Usage (Go)

```go
import "git.teamworkapps.com/shortcut/cremote/client"

client := client.NewClient("localhost:9223")

// Run axe tests
client.InjectAxeCore("", "4.8.0", 30)
results, _ := client.RunAxeCore("", nil, nil, 30)

// Check contrast
contrastResults, _ := client.CheckContrast("", "body", 10)

// Test keyboard navigation
keyboardResults, _ := client.TestKeyboard("", 10)
```

---

## Support and Resources

- **WCAG 2.1 Guidelines:** https://www.w3.org/WAI/WCAG21/quickref/
- **Axe-Core Documentation:** https://github.com/dequelabs/axe-core
- **Cremote Repository:** git.teamworkapps.com/shortcut/cremote
- **Issue Tracker:** git.teamworkapps.com/shortcut/cremote/issues

---

**Last Updated:** 2025-10-02
**Version:** 1.0.0