Accessibility Testing with Selenium WebDriver & Axe Core
This skill enables automated accessibility analysis within the Selenium WebDriver framework using the axe-core engine to detect WCAG violations and best practice issues directly in the browser.
Activation: This skill is triggered when you need to validate WCAG compliance, scan for accessibility violations, test keyboard navigation, audit ARIA semantics, or generate a11y reports.
First Questions to Ask
- What app URL(s) or user flows are in scope (and what is explicitly out of scope)?
- Is there an existing Selenium setup and how is CI run?
- Which standard is the target (WCAG 2.2 AA by default), and are there org-specific policies?
- Which pages/components are highest risk (auth, checkout, forms, modals, navigation)?
- Are there known constraints (legacy markup, third-party widgets) that require exceptions?
Prerequisites
| Component |
Version |
Purpose |
| Java JDK |
21+ |
Runtime with modern features |
| Maven |
3.9+ |
Dependency management |
| Selenium WebDriver |
4.x |
Browser automation |
| axe-core-selenium |
4.10+ |
Deque axe-core integration |
| JUnit 5 |
5.10+ |
Test framework |
| AssertJ |
3.x |
Fluent assertions for readable failures |
| Allure |
2.x |
Reporting with a11y violation attachments |
Note: Use com.deque.html.axe-core:selenium Maven dependency for axe integration.
Target: WCAG 2.2 AA (wcag2a, wcag2aa, wcag21a, wcag21aa, wcag22a, wcag22aa). See WCAG 2.2 spec.
Do NOT Use For
- Playwright/TypeScript accessibility testing (use
a11y-playwright-testing).
- Authoring Selenium functional UI tests (use
webapp-selenium-testing).
- Full conformance sign-off — automated axe scans catch ~30-50% of issues; manual audit + assistive-tech testing is still required.
Axe-Core Tools Reference
AxeBuilder Configuration
| Method |
Purpose |
Example |
new AxeBuilder() |
Create scanner instance |
Entry point |
.withTags(List<String>) |
Filter by WCAG tags |
wcag2aa, wcag21aa, wcag22aa |
.include(String) |
Scan specific selector |
#main-content |
.exclude(String) |
Skip selector from scan |
.third-party-widget |
.disableRules(List<String>) |
Disable specific rules |
color-contrast |
.withRules(List<String>) |
Run only specific rules |
label, button-name |
.analyze(WebDriver) |
Execute the scan |
Returns Results |
Results Object
| Method |
Returns |
Purpose |
getViolations() |
List<Rule> |
Rules that failed |
getPasses() |
List<Rule> |
Rules that passed |
getIncomplete() |
List<Rule> |
Rules needing manual review |
getInapplicable() |
List<Rule> |
Rules not applicable to page |
violationFree() |
boolean |
True if no violations |
Violation Impact Levels
| Impact |
Severity |
CI Action |
| Critical |
Blocks users completely |
Always fail build |
| Serious |
Significant barrier |
Always fail build |
| Moderate |
Some difficulty |
Warn or fail |
| Minor |
Inconvenience |
Log for review |
Step-by-Step Workflows
Workflow 1: Add A11y Scan to Existing Test
Add dependency to pom.xml
<dependency>
<groupId>com.deque.html.axe-core</groupId>
<artifactId>selenium</artifactId>
<version>4.10.0</version>
</dependency>
Create AccessibilityHelper utility
- See Axe Patterns: Helper Scanning
Add scan after page loads
driver.get("https://example.com");
waitForPageReady();
AccessibilityHelper.verifyPageAccessibility(driver);
Run and review violations
mvn test -Dtest=A11yTest
Workflow 2: Test Specific Component
Navigate to page with component visible
Trigger component state (open modal, show dropdown)
Scan only the component
Results results = new AxeBuilder()
.withTags(List.of("wcag2a", "wcag2aa", "wcag22aa"))
.include("#login-modal")
.analyze(driver);
Assert and log
Workflow 3: Keyboard Navigation Audit
- Identify all interactive elements
- Tab through the page programmatically
element.sendKeys(Keys.TAB);
WebElement focused = driver.switchTo().activeElement();
- Verify focus order is logical
- Test Escape closes modals
- Verify no keyboard traps
Workflow 4: CI Integration
Configure headless browser
mvn test -Dheadless=true -Dgroups=a11y
Set zero-tolerance for Critical/Serious
long criticalCount = violations.stream()
.filter(v -> List.of("critical", "serious").contains(v.getImpact()))
.count();
assertThat(criticalCount).isZero();
Generate JSON report for tracking
Code Patterns
See references/code-patterns.md for full AxeBuilder scan patterns, violation logging, JUnit 5 integration, and CI/CD YAML.
Key snippet:
Results results = new AxeBuilder()
.withTags(List.of("wcag2a", "wcag2aa", "wcag21a", "wcag21aa", "wcag22a", "wcag22aa"))
.analyze(driver);
assertThat(results.violationFree()).as("A11y violations").isTrue();
Troubleshooting
| Problem |
Cause |
Solution |
| Axe returns empty results |
Page not fully loaded |
Add explicit wait for page ready state |
| False positives on contrast |
Dynamic themes |
Test both light and dark modes |
| Violations in third-party widgets |
Cannot modify vendor code |
Use .exclude() with documented ticket |
| Incomplete rules |
Requires manual review |
Log for manual audit, don't auto-fail |
| Different results between runs |
Async content loading |
Ensure deterministic page state before scan |
| CI fails but local passes |
Different viewport/browser |
Use same headless config as CI |
Triage by POUR Principles
| Principle |
Focus Areas |
Common Violations |
| Perceivable |
Text alternatives, captions, contrast, structure |
Missing alt text, low contrast, missing labels |
| Operable |
Keyboard access, focus order, bypass blocks |
Keyboard traps, no skip link, focus not visible |
| Understandable |
Labels, predictable behavior, error handling |
Unclear instructions, unexpected changes |
| Robust |
Valid HTML, ARIA, name/role/value |
Invalid ARIA, duplicate IDs, missing roles |
Running Tests
Maven Commands
| Command |
Purpose |
mvn test -Dgroups=a11y |
Run all accessibility tests |
mvn test -Dtest=A11yTest |
Run specific test class |
mvn test -Dheadless=true |
Run headless (CI mode) |
mvn allure:serve |
View Allure report with violations |
CI/CD Integration
- name: Run Accessibility Tests
run: mvn test -Dgroups=a11y -Dheadless=true
- name: Upload A11y Report
uses: actions/upload-artifact@v3
with:
name: a11y-report
path: target/a11y-results/
Red Flags
- Treating a clean axe scan as full WCAG conformance — automation covers only ~30-50% of criteria.
- Globally disabling rules instead of scoped
.exclude() with a documented remediation ticket.
- Scanning before the page is fully loaded — async content yields false "0 violations".
- Failing the build on
incomplete rules — those need manual review, not automatic failure.
References
- Axe Patterns: Helper Scanning - Maven setup and AccessibilityHelper scanning methods
- Axe Patterns: Helper Processing - AccessibilityHelper results, filtering, logging, and reporting
- Axe Patterns: Tags & Tests - Common axe tags reference and test patterns
- Axe Patterns: Keyboard & CI/CD - Keyboard navigation testing and CI/CD integration
- Axe-Core API Reference - Full AxeBuilder config, Results object, and impact levels
- WCAG 2.2 AA Checklist: Perceivable & Operable - Manual audit checklist, POUR principles 1-2
- WCAG 2.2 AA Checklist: Understandable & Robust - Manual audit checklist, POUR principles 3-4 and assistive tech
- WCAG 2.2 AA Checklist: Additions & Exceptions - WCAG 2.2 additions, exception template, W3C references
- Deque Axe Rules - Rule descriptions
- W3C WCAG 2.2 - Official specification
- WAI-ARIA Practices - Widget patterns
Verification
1---
2name: accessibility-selenium-testing
3description: 'Accessibility testing toolkit using Selenium WebDriver 4+ with Java 21+ and axe-core engine. Use when asked to validate WCAG 2.2 AA compliance, scan pages or components for a11y violations, test keyboard navigation, audit color contrast, check ARIA semantics, generate accessibility reports, filter axe rules, debug screen reader issues, or implement POUR principles (perceivable, operable, understandable, robust).'
4license: 'Complete terms in LICENSE.txt'
5metadata:
6 source: https://skillmd.com/skills/gabrielmoreira/accessibility-selenium-testing
7---
8
9# Accessibility Testing with Selenium WebDriver & Axe Core
10
11This skill enables automated accessibility analysis within the Selenium WebDriver framework using the **axe-core** engine to detect WCAG violations and best practice issues directly in the browser.
12
13> **Activation:** This skill is triggered when you need to validate WCAG compliance, scan for accessibility violations, test keyboard navigation, audit ARIA semantics, or generate a11y reports.
14
15## First Questions to Ask
16
17- What app URL(s) or user flows are in scope (and what is explicitly out of scope)?
18- Is there an existing Selenium setup and how is CI run?
19- Which standard is the target (WCAG 2.2 AA by default), and are there org-specific policies?
20- Which pages/components are highest risk (auth, checkout, forms, modals, navigation)?
21- Are there known constraints (legacy markup, third-party widgets) that require exceptions?
22
23## Prerequisites
24
25| Component | Version | Purpose |
26|-----------|---------|---------|
27| Java JDK | 21+ | Runtime with modern features |
28| Maven | 3.9+ | Dependency management |
29| Selenium WebDriver | 4.x | Browser automation |
30| axe-core-selenium | 4.10+ | Deque axe-core integration |
31| JUnit 5 | 5.10+ | Test framework |
32| AssertJ | 3.x | Fluent assertions for readable failures |
33| Allure | 2.x | Reporting with a11y violation attachments |
34
35> **Note:** Use `com.deque.html.axe-core:selenium` Maven dependency for axe integration.
36
37---
38
39> **Target:** WCAG 2.2 AA (`wcag2a`, `wcag2aa`, `wcag21a`, `wcag21aa`, `wcag22a`, `wcag22aa`). See [WCAG 2.2 spec](https://www.w3.org/TR/WCAG22/).
40
41### Do NOT Use For
42
43- Playwright/TypeScript accessibility testing (use `a11y-playwright-testing`).
44- Authoring Selenium functional UI tests (use `webapp-selenium-testing`).
45- Full conformance sign-off — automated axe scans catch ~30-50% of issues; manual audit + assistive-tech testing is still required.
46
47## Axe-Core Tools Reference
48
49### AxeBuilder Configuration
50
51| Method | Purpose | Example |
52|--------|---------|---------|
53| `new AxeBuilder()` | Create scanner instance | Entry point |
54| `.withTags(List<String>)` | Filter by WCAG tags | `wcag2aa`, `wcag21aa`, `wcag22aa` |
55| `.include(String)` | Scan specific selector | `#main-content` |
56| `.exclude(String)` | Skip selector from scan | `.third-party-widget` |
57| `.disableRules(List<String>)` | Disable specific rules | `color-contrast` |
58| `.withRules(List<String>)` | Run only specific rules | `label`, `button-name` |
59| `.analyze(WebDriver)` | Execute the scan | Returns `Results` |
60
61### Results Object
62
63| Method | Returns | Purpose |
64|--------|---------|---------|
65| `getViolations()` | `List<Rule>` | Rules that failed |
66| `getPasses()` | `List<Rule>` | Rules that passed |
67| `getIncomplete()` | `List<Rule>` | Rules needing manual review |
68| `getInapplicable()` | `List<Rule>` | Rules not applicable to page |
69| `violationFree()` | `boolean` | True if no violations |
70
71### Violation Impact Levels
72
73| Impact | Severity | CI Action |
74|--------|----------|-----------|
75| **Critical** | Blocks users completely | Always fail build |
76| **Serious** | Significant barrier | Always fail build |
77| **Moderate** | Some difficulty | Warn or fail |
78| **Minor** | Inconvenience | Log for review |
79
80---
81
82## Step-by-Step Workflows
83
84### Workflow 1: Add A11y Scan to Existing Test
85
861. **Add dependency to pom.xml**
87 ```xml
88 <dependency>
89 <groupId>com.deque.html.axe-core</groupId>
90 <artifactId>selenium</artifactId>
91 <version>4.10.0</version>
92 </dependency>
93 ```
94
952. **Create AccessibilityHelper utility**
96 - See [Axe Patterns: Helper Scanning](references/axe-patterns-helper-scanning.md)
97
983. **Add scan after page loads**
99 ```java
100 driver.get("https://example.com");
101 waitForPageReady();
102 AccessibilityHelper.verifyPageAccessibility(driver);
103 ```
104
1054. **Run and review violations**
106 ```bash
107 mvn test -Dtest=A11yTest
108 ```
109
110### Workflow 2: Test Specific Component
111
1121. **Navigate to page with component visible**
1132. **Trigger component state** (open modal, show dropdown)
1143. **Scan only the component**
115 ```java
116 Results results = new AxeBuilder()
117 .withTags(List.of("wcag2a", "wcag2aa", "wcag22aa"))
118 .include("#login-modal")
119 .analyze(driver);
120 ```
121
1224. **Assert and log**
123
124### Workflow 3: Keyboard Navigation Audit
125
1261. **Identify all interactive elements**
1272. **Tab through the page programmatically**
128 ```java
129 element.sendKeys(Keys.TAB);
130 WebElement focused = driver.switchTo().activeElement();
131 ```
1323. **Verify focus order is logical**
1334. **Test Escape closes modals**
1345. **Verify no keyboard traps**
135
136### Workflow 4: CI Integration
137
1381. **Configure headless browser**
139 ```bash
140 mvn test -Dheadless=true -Dgroups=a11y
141 ```
142
1432. **Set zero-tolerance for Critical/Serious**
144 ```java
145 long criticalCount = violations.stream()
146 .filter(v -> List.of("critical", "serious").contains(v.getImpact()))
147 .count();
148 assertThat(criticalCount).isZero();
149 ```
150
1513. **Generate JSON report for tracking**
152
153---
154
155## Code Patterns
156
157See [`references/code-patterns.md`](references/code-patterns.md) for full AxeBuilder scan patterns, violation logging, JUnit 5 integration, and CI/CD YAML.
158
159Key snippet:
160
161```java
162Results results = new AxeBuilder()
163 .withTags(List.of("wcag2a", "wcag2aa", "wcag21a", "wcag21aa", "wcag22a", "wcag22aa"))
164 .analyze(driver);
165assertThat(results.violationFree()).as("A11y violations").isTrue();
166```
167
168## Troubleshooting
169
170| Problem | Cause | Solution |
171|---------|-------|----------|
172| Axe returns empty results | Page not fully loaded | Add explicit wait for page ready state |
173| False positives on contrast | Dynamic themes | Test both light and dark modes |
174| Violations in third-party widgets | Cannot modify vendor code | Use `.exclude()` with documented ticket |
175| Incomplete rules | Requires manual review | Log for manual audit, don't auto-fail |
176| Different results between runs | Async content loading | Ensure deterministic page state before scan |
177| CI fails but local passes | Different viewport/browser | Use same headless config as CI |
178
179---
180
181## Triage by POUR Principles
182
183| Principle | Focus Areas | Common Violations |
184|-----------|-------------|-------------------|
185| **Perceivable** | Text alternatives, captions, contrast, structure | Missing alt text, low contrast, missing labels |
186| **Operable** | Keyboard access, focus order, bypass blocks | Keyboard traps, no skip link, focus not visible |
187| **Understandable** | Labels, predictable behavior, error handling | Unclear instructions, unexpected changes |
188| **Robust** | Valid HTML, ARIA, name/role/value | Invalid ARIA, duplicate IDs, missing roles |
189
190---
191
192## Running Tests
193
194### Maven Commands
195
196| Command | Purpose |
197|---------|---------|
198| `mvn test -Dgroups=a11y` | Run all accessibility tests |
199| `mvn test -Dtest=A11yTest` | Run specific test class |
200| `mvn test -Dheadless=true` | Run headless (CI mode) |
201| `mvn allure:serve` | View Allure report with violations |
202
203### CI/CD Integration
204
205```yaml
206- name: Run Accessibility Tests
207 run: mvn test -Dgroups=a11y -Dheadless=true
208
209- name: Upload A11y Report
210 uses: actions/upload-artifact@v3
211 with:
212 name: a11y-report
213 path: target/a11y-results/
214```
215
216---
217
218## Red Flags
219
220- Treating a clean axe scan as full WCAG conformance — automation covers only ~30-50% of criteria.
221- Globally disabling rules instead of scoped `.exclude()` with a documented remediation ticket.
222- Scanning before the page is fully loaded — async content yields false "0 violations".
223- Failing the build on `incomplete` rules — those need manual review, not automatic failure.
224
225---
226
227## References
228
229- [Axe Patterns: Helper Scanning](references/axe-patterns-helper-scanning.md) - Maven setup and AccessibilityHelper scanning methods
230- [Axe Patterns: Helper Processing](references/axe-patterns-helper-processing.md) - AccessibilityHelper results, filtering, logging, and reporting
231- [Axe Patterns: Tags & Tests](references/axe-patterns-tags-and-tests.md) - Common axe tags reference and test patterns
232- [Axe Patterns: Keyboard & CI/CD](references/axe-patterns-keyboard-and-cicd.md) - Keyboard navigation testing and CI/CD integration
233- [Axe-Core API Reference](references/axe-api-reference.md) - Full AxeBuilder config, Results object, and impact levels
234- [WCAG 2.2 AA Checklist: Perceivable & Operable](references/wcag21aa-checklist-perceivable-operable.md) - Manual audit checklist, POUR principles 1-2
235- [WCAG 2.2 AA Checklist: Understandable & Robust](references/wcag21aa-checklist-understandable-robust.md) - Manual audit checklist, POUR principles 3-4 and assistive tech
236- [WCAG 2.2 AA Checklist: Additions & Exceptions](references/wcag21aa-checklist-additions-exceptions.md) - WCAG 2.2 additions, exception template, W3C references
237- [Deque Axe Rules](https://dequeuniversity.com/rules/axe/4.10) - Rule descriptions
238- [W3C WCAG 2.2](https://www.w3.org/TR/WCAG22/) - Official specification
239- [WAI-ARIA Practices](https://www.w3.org/WAI/ARIA/apg/) - Widget patterns
240
241---
242
243## Verification
244
245- [ ] **Axe WebDriver audit passes** — `AxeBuilder.analyze(driver)` returns zero critical violations
246- [ ] **Keyboard accessibility verified** — Tab navigation reaches all interactive elements
247- [ ] **WCAG 2.2 AA compliance** — All rules for AA level pass (includes WCAG 2.2 additions: focus-not-obscured, dragging movements, target-size minimum)