ada tools update
This commit is contained in:
Josh at WLTechBlog
535
docs/ADA_TESTING_GUIDE.md
Normal file
535
docs/ADA_TESTING_GUIDE.md
Normal file
@@ -0,0 +1,535 @@
|
||||
# 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
|
||||
|
||||
Reference in New Issue
Block a user