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
2. Available Tools
3. WCAG Coverage
4. Testing Workflows
5. Tool Reference
6. Best Practices
7. Limitations

---

Quick Start

Basic Accessibility Audit

# 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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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

# 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

# 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

# Test common device sizes
cremote reflow-test --widths 320,375,768,1024,1280,1920

4. Document Visual Issues

# 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

# .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)

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