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
|
||||
|
||||
442
docs/llm_ada_testing.md
Normal file
442
docs/llm_ada_testing.md
Normal file
@@ -0,0 +1,442 @@
|
||||
# LLM Agent Guide: ADA/WCAG Accessibility Testing with Cremote
|
||||
|
||||
## Purpose
|
||||
This document provides LLM coding agents with concrete, actionable guidance for using Cremote's accessibility testing tools to conduct ADA/WCAG compliance audits.
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Tool Selection Matrix
|
||||
|
||||
| Testing Need | Primary Tool | Secondary Tool | WCAG Criteria |
|
||||
|--------------|--------------|----------------|---------------|
|
||||
| Comprehensive automated audit | `web_run_axe_cremotemcp` | - | ~57% of WCAG 2.1 AA |
|
||||
| Color contrast issues | `web_contrast_check_cremotemcp` | `web_run_axe_cremotemcp` | 1.4.3, 1.4.6 |
|
||||
| Keyboard accessibility | `web_keyboard_test_cremotemcp` | `web_run_axe_cremotemcp` | 2.1.1, 2.4.7 |
|
||||
| Zoom/resize functionality | `web_zoom_test_cremotemcp` | - | 1.4.4 |
|
||||
| Responsive design | `web_reflow_test_cremotemcp` | - | 1.4.10 |
|
||||
| Visual documentation | `web_screenshot_cremotemcp` | - | Evidence capture |
|
||||
| Custom JavaScript testing | `console_command_cremotemcp` | - | Advanced scenarios |
|
||||
|
||||
### Standard Testing Sequence
|
||||
|
||||
```
|
||||
1. web_inject_axe_cremotemcp # Inject axe-core library
|
||||
2. web_run_axe_cremotemcp # Run comprehensive automated tests
|
||||
3. web_contrast_check_cremotemcp # Detailed contrast analysis
|
||||
4. web_keyboard_test_cremotemcp # Keyboard navigation testing
|
||||
5. web_zoom_test_cremotemcp # Zoom functionality testing
|
||||
6. web_reflow_test_cremotemcp # Responsive design testing
|
||||
```
|
||||
|
||||
## Tool Usage Patterns
|
||||
|
||||
### Pattern 1: Initial Audit
|
||||
|
||||
```json
|
||||
// Step 1: Inject axe-core
|
||||
{
|
||||
"tool": "web_inject_axe_cremotemcp",
|
||||
"arguments": {
|
||||
"timeout": 30
|
||||
}
|
||||
}
|
||||
|
||||
// Step 2: Run comprehensive tests
|
||||
{
|
||||
"tool": "web_run_axe_cremotemcp",
|
||||
"arguments": {
|
||||
"run_only": ["wcag2a", "wcag2aa", "wcag21aa"],
|
||||
"timeout": 30
|
||||
}
|
||||
}
|
||||
|
||||
// Step 3: Analyze results and run specialized tests based on findings
|
||||
```
|
||||
|
||||
### Pattern 2: Contrast-Specific Testing
|
||||
|
||||
```json
|
||||
// For pages with known or suspected contrast issues
|
||||
{
|
||||
"tool": "web_contrast_check_cremotemcp",
|
||||
"arguments": {
|
||||
"selector": "body", // Test entire page
|
||||
"timeout": 10
|
||||
}
|
||||
}
|
||||
|
||||
// For specific sections
|
||||
{
|
||||
"tool": "web_contrast_check_cremotemcp",
|
||||
"arguments": {
|
||||
"selector": ".main-content", // Test specific area
|
||||
"timeout": 10
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Pattern 3: Keyboard Navigation Testing
|
||||
|
||||
```json
|
||||
{
|
||||
"tool": "web_keyboard_test_cremotemcp",
|
||||
"arguments": {
|
||||
"timeout": 10
|
||||
}
|
||||
}
|
||||
|
||||
// Analyze output for:
|
||||
// - not_focusable: Elements that should be keyboard accessible but aren't
|
||||
// - no_focus_indicator: Elements missing visible focus indicators
|
||||
// - keyboard_trap: Elements that trap keyboard focus
|
||||
```
|
||||
|
||||
### Pattern 4: Zoom and Responsive Testing
|
||||
|
||||
```json
|
||||
// Test zoom levels (WCAG 1.4.4)
|
||||
{
|
||||
"tool": "web_zoom_test_cremotemcp",
|
||||
"arguments": {
|
||||
"zoom_levels": [1.0, 2.0, 4.0],
|
||||
"timeout": 10
|
||||
}
|
||||
}
|
||||
|
||||
// Test responsive breakpoints (WCAG 1.4.10)
|
||||
{
|
||||
"tool": "web_reflow_test_cremotemcp",
|
||||
"arguments": {
|
||||
"widths": [320, 768, 1280],
|
||||
"timeout": 10
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Pattern 5: Visual Documentation
|
||||
|
||||
```json
|
||||
// Capture baseline
|
||||
{
|
||||
"tool": "web_screenshot_cremotemcp",
|
||||
"arguments": {
|
||||
"output": "/tmp/baseline.png",
|
||||
"timeout": 5
|
||||
}
|
||||
}
|
||||
|
||||
// Capture at 200% zoom
|
||||
{
|
||||
"tool": "web_screenshot_cremotemcp",
|
||||
"arguments": {
|
||||
"output": "/tmp/zoom-200.png",
|
||||
"zoom_level": 2.0,
|
||||
"timeout": 5
|
||||
}
|
||||
}
|
||||
|
||||
// Capture mobile view
|
||||
{
|
||||
"tool": "web_screenshot_cremotemcp",
|
||||
"arguments": {
|
||||
"output": "/tmp/mobile-320.png",
|
||||
"width": 320,
|
||||
"height": 568,
|
||||
"timeout": 5
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Interpreting Results
|
||||
|
||||
### Axe-Core Results
|
||||
|
||||
```json
|
||||
{
|
||||
"violations": [
|
||||
{
|
||||
"id": "color-contrast",
|
||||
"impact": "serious", // critical, serious, moderate, minor
|
||||
"description": "Elements must have sufficient color contrast",
|
||||
"nodes": [
|
||||
{
|
||||
"html": "<p class=\"text-gray\">Low contrast text</p>",
|
||||
"target": [".text-gray"],
|
||||
"failureSummary": "Fix any of the following:\n Element has insufficient color contrast of 3.2:1 (foreground color: #808080, background color: #ffffff, font size: 12.0pt (16px), font weight: normal). Expected contrast ratio of 4.5:1"
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"passes": [...], // Tests that passed
|
||||
"incomplete": [...], // Tests requiring manual review
|
||||
"inapplicable": [...] // Tests not applicable to this page
|
||||
}
|
||||
```
|
||||
|
||||
**Action Priority:**
|
||||
1. **Critical/Serious violations** - Fix immediately
|
||||
2. **Moderate violations** - Fix in current sprint
|
||||
3. **Minor violations** - Fix when convenient
|
||||
4. **Incomplete** - Manually review and test
|
||||
5. **Passes** - Document for compliance
|
||||
|
||||
### Contrast Check Results
|
||||
|
||||
```
|
||||
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)
|
||||
```
|
||||
|
||||
**Remediation:**
|
||||
- Darken foreground color or lighten background
|
||||
- Use contrast ratio calculator to find compliant colors
|
||||
- Test with `web_contrast_check_cremotemcp` after fixes
|
||||
|
||||
### Keyboard Test Results
|
||||
|
||||
```
|
||||
High Severity Issues:
|
||||
- not_focusable: Interactive element is not keyboard focusable
|
||||
Element: div[role="button"]
|
||||
- no_focus_indicator: Interactive element lacks visible focus indicator
|
||||
Element: button.submit-btn
|
||||
```
|
||||
|
||||
**Remediation:**
|
||||
- `not_focusable`: Add `tabindex="0"` or use semantic HTML (`<button>` instead of `<div>`)
|
||||
- `no_focus_indicator`: Add CSS `:focus` styles with visible outline/border
|
||||
- `keyboard_trap`: Review JavaScript event handlers and focus management
|
||||
|
||||
### Zoom Test Results
|
||||
|
||||
```
|
||||
Zoom 400% ✗ FAIL:
|
||||
Horizontal Scroll: true
|
||||
Overflowing Elements: 3
|
||||
Text Readable: true
|
||||
```
|
||||
|
||||
**Remediation:**
|
||||
- Use responsive units (rem, em, %) instead of fixed pixels
|
||||
- Implement CSS media queries for zoom levels
|
||||
- Test with `max-width: 100%` on images and containers
|
||||
|
||||
### Reflow Test Results
|
||||
|
||||
```
|
||||
320px Width ✗ FAIL:
|
||||
Horizontal Scroll: true
|
||||
Responsive Layout: false
|
||||
Overflowing Elements: 5
|
||||
```
|
||||
|
||||
**Remediation:**
|
||||
- Implement mobile-first responsive design
|
||||
- Use CSS Grid or Flexbox with `flex-wrap`
|
||||
- Test with `overflow-x: hidden` cautiously (may hide content)
|
||||
|
||||
## Common Workflows
|
||||
|
||||
### Workflow 1: New Page Audit
|
||||
|
||||
```
|
||||
1. Navigate to page
|
||||
2. Run web_inject_axe_cremotemcp
|
||||
3. Run web_run_axe_cremotemcp with wcag2aa tags
|
||||
4. If violations found:
|
||||
a. Run web_contrast_check_cremotemcp for contrast issues
|
||||
b. Run web_keyboard_test_cremotemcp for keyboard issues
|
||||
5. Run web_zoom_test_cremotemcp
|
||||
6. Run web_reflow_test_cremotemcp
|
||||
7. Capture screenshots for documentation
|
||||
8. Generate report with all findings
|
||||
```
|
||||
|
||||
### Workflow 2: Regression Testing
|
||||
|
||||
```
|
||||
1. Navigate to page
|
||||
2. Run web_run_axe_cremotemcp
|
||||
3. Compare results with baseline
|
||||
4. If new violations:
|
||||
a. Run specialized tests for affected areas
|
||||
b. Capture screenshots showing issues
|
||||
5. Report regressions
|
||||
```
|
||||
|
||||
### Workflow 3: Contrast-Focused Audit
|
||||
|
||||
```
|
||||
1. Navigate to page
|
||||
2. Run web_contrast_check_cremotemcp on entire page
|
||||
3. For each violation:
|
||||
a. Capture screenshot of affected element
|
||||
b. Document current and required contrast ratios
|
||||
c. Suggest color adjustments
|
||||
4. After fixes, re-run web_contrast_check_cremotemcp
|
||||
5. Verify all violations resolved
|
||||
```
|
||||
|
||||
### Workflow 4: Keyboard Accessibility Audit
|
||||
|
||||
```
|
||||
1. Navigate to page
|
||||
2. Run web_keyboard_test_cremotemcp
|
||||
3. Analyze tab order for logical sequence
|
||||
4. For each issue:
|
||||
a. Document element and issue type
|
||||
b. Suggest remediation (tabindex, semantic HTML, focus styles)
|
||||
5. After fixes, re-run web_keyboard_test_cremotemcp
|
||||
6. Manually verify complex interactions
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Common Errors and Solutions
|
||||
|
||||
**Error:** "Failed to inject library"
|
||||
```
|
||||
Solution: Check network connectivity, try alternative CDN, or increase timeout
|
||||
```
|
||||
|
||||
**Error:** "Evaluation timed out"
|
||||
```
|
||||
Solution: Increase timeout parameter, test on smaller page sections
|
||||
```
|
||||
|
||||
**Error:** "No tab available"
|
||||
```
|
||||
Solution: Navigate to a page first using web_navigate_cremotemcp
|
||||
```
|
||||
|
||||
**Error:** "Failed to get page"
|
||||
```
|
||||
Solution: Verify tab ID is valid, check if page is still loaded
|
||||
```
|
||||
|
||||
## Best Practices for LLM Agents
|
||||
|
||||
### 1. Always Start with Axe-Core
|
||||
Axe-core provides the broadest coverage (~57% of WCAG 2.1 AA). Use it as the foundation, then run specialized tests based on findings.
|
||||
|
||||
### 2. Test in Logical Order
|
||||
```
|
||||
Automated (axe) → Specialized (contrast, keyboard) → Visual (zoom, reflow) → Documentation (screenshots)
|
||||
```
|
||||
|
||||
### 3. Provide Context in Reports
|
||||
When reporting issues, include:
|
||||
- WCAG criterion violated
|
||||
- Severity/impact level
|
||||
- Specific element(s) affected
|
||||
- Current state (e.g., contrast ratio 3.2:1)
|
||||
- Required state (e.g., contrast ratio 4.5:1)
|
||||
- Suggested remediation
|
||||
|
||||
### 4. Capture Evidence
|
||||
Always capture screenshots when documenting issues:
|
||||
```json
|
||||
{
|
||||
"tool": "web_screenshot_cremotemcp",
|
||||
"arguments": {
|
||||
"output": "/tmp/issue-contrast-button.png"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 5. Verify Fixes
|
||||
After suggesting fixes, re-run the relevant tests to verify resolution:
|
||||
```
|
||||
1. Suggest fix
|
||||
2. Wait for implementation
|
||||
3. Re-run specific test
|
||||
4. Confirm issue resolved
|
||||
```
|
||||
|
||||
### 6. Know the Limitations
|
||||
These tools cannot test:
|
||||
- Semantic meaning of content
|
||||
- Cognitive load
|
||||
- Time-based media (captions, audio descriptions)
|
||||
- Complex user interactions
|
||||
- Context-dependent issues
|
||||
|
||||
Always recommend manual testing with assistive technologies for comprehensive audits.
|
||||
|
||||
## Integration with Development Workflow
|
||||
|
||||
### Pre-Commit Testing
|
||||
```bash
|
||||
# Run quick accessibility check before commit
|
||||
cremote inject-axe && cremote run-axe --run-only wcag2aa
|
||||
```
|
||||
|
||||
### CI/CD Integration
|
||||
```yaml
|
||||
# Run full accessibility suite in CI
|
||||
- cremote inject-axe
|
||||
- cremote run-axe > axe-results.json
|
||||
- cremote contrast-check > contrast-results.txt
|
||||
- cremote keyboard-test > keyboard-results.txt
|
||||
- cremote zoom-test > zoom-results.txt
|
||||
- cremote reflow-test > reflow-results.txt
|
||||
```
|
||||
|
||||
### Pull Request Reviews
|
||||
```
|
||||
1. Run accessibility tests on PR branch
|
||||
2. Compare with main branch baseline
|
||||
3. Report new violations in PR comments
|
||||
4. Block merge if critical violations found
|
||||
```
|
||||
|
||||
## Quick Command Reference
|
||||
|
||||
```bash
|
||||
# Inject axe-core
|
||||
cremote inject-axe
|
||||
|
||||
# Run comprehensive tests
|
||||
cremote run-axe --run-only wcag2a,wcag2aa,wcag21aa
|
||||
|
||||
# Check contrast
|
||||
cremote contrast-check --selector body
|
||||
|
||||
# Test keyboard navigation
|
||||
cremote keyboard-test
|
||||
|
||||
# Test zoom levels
|
||||
cremote zoom-test --zoom-levels 1.0,2.0,4.0
|
||||
|
||||
# Test responsive design
|
||||
cremote reflow-test --widths 320,768,1280
|
||||
|
||||
# Capture screenshot
|
||||
cremote screenshot --output /tmp/screenshot.png
|
||||
|
||||
# Capture screenshot at zoom level
|
||||
cremote screenshot --output /tmp/zoom-200.png --zoom-level 2.0
|
||||
|
||||
# Capture screenshot at specific viewport
|
||||
cremote screenshot --output /tmp/mobile.png --width 320 --height 568
|
||||
|
||||
# Get accessibility tree
|
||||
cremote get-accessibility-tree --include-contrast true
|
||||
|
||||
# Execute custom JavaScript with library injection
|
||||
cremote console-command --command "axe.run()" --inject-library axe
|
||||
```
|
||||
|
||||
## Resources
|
||||
|
||||
- **WCAG 2.1 Quick Reference:** https://www.w3.org/WAI/WCAG21/quickref/
|
||||
- **Axe-Core Rules:** https://github.com/dequelabs/axe-core/blob/develop/doc/rule-descriptions.md
|
||||
- **Contrast Ratio Calculator:** https://contrast-ratio.com/
|
||||
- **WebAIM Resources:** https://webaim.org/resources/
|
||||
|
||||
---
|
||||
|
||||
**For LLM Agents:** This guide is designed for programmatic use. Always provide specific, actionable recommendations based on test results. Include WCAG criterion numbers, severity levels, and concrete remediation steps in your reports.
|
||||
|
||||
Reference in New Issue
Block a user