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

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

Results Object

Violation Impact Levels

Step-by-Step Workflows

Workflow 1: Add A11y Scan to Existing Test

1. Add dependency to pom.xml

   <dependency>
       <groupId>com.deque.html.axe-core</groupId>
       <artifactId>selenium</artifactId>
       <version>4.10.0</version>
   </dependency>
   

2. Create AccessibilityHelper utility

   • See Axe Patterns: Helper Scanning

3. Add scan after page loads

   driver.get("https://example.com");
   waitForPageReady();
   AccessibilityHelper.verifyPageAccessibility(driver);
   

4. Run and review violations

   mvn test -Dtest=A11yTest
   

Workflow 2: Test Specific Component

1. Navigate to page with component visible

2. Trigger component state (open modal, show dropdown)

3. Scan only the component

   Results results = new AxeBuilder()
       .withTags(List.of("wcag2a", "wcag2aa", "wcag22aa"))
       .include("#login-modal")
       .analyze(driver);
   

4. Assert and log

Workflow 3: Keyboard Navigation Audit

1. Identify all interactive elements
2. Tab through the page programmatically

   element.sendKeys(Keys.TAB);
   WebElement focused = driver.switchTo().activeElement();
   

3. Verify focus order is logical
4. Test Escape closes modals
5. Verify no keyboard traps

Workflow 4: CI Integration

1. Configure headless browser

   mvn test -Dheadless=true -Dgroups=a11y
   

2. Set zero-tolerance for Critical/Serious

   long criticalCount = violations.stream()
       .filter(v -> List.of("critical", "serious").contains(v.getImpact()))
       .count();
   assertThat(criticalCount).isZero();
   

3. 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

Triage by POUR Principles

Running Tests

Maven Commands

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

• Axe WebDriver audit passes — AxeBuilder.analyze(driver) returns zero critical violations
• Keyboard accessibility verified — Tab navigation reaches all interactive elements
• WCAG 2.2 AA compliance — All rules for AA level pass (includes WCAG 2.2 additions: focus-not-obscured, dragging movements, target-size minimum)