fugazi/accessibility-selenium-testing
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).
npx skills add https://github.com/fugazi/test-automation-skills-agents --skill accessibility-selenium-testingThis 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.
| 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.
a11y-playwright-testing).webapp-selenium-testing).| 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 |
| 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 |
| 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 |
<dependency>
<groupId>com.deque.html.axe-core</groupId>
<artifactId>selenium</artifactId>
<version>4.10.0</version>
</dependency>
driver.get("https://example.com");
waitForPageReady();
AccessibilityHelper.verifyPageAccessibility(driver);
mvn test -Dtest=A11yTest
Results results = new AxeBuilder()
.withTags(List.of("wcag2a", "wcag2aa", "wcag22aa"))
.include("#login-modal")
.analyze(driver);
element.sendKeys(Keys.TAB);
WebElement focused = driver.switchTo().activeElement();
mvn test -Dheadless=true -Dgroups=a11y
long criticalCount = violations.stream()
.filter(v -> List.of("critical", "serious").contains(v.getImpact()))
.count();
assertThat(criticalCount).isZero();
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();
| 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 |
| 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 |
| 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 |
- 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/
.exclude() with a documented remediation ticket.incomplete rules — those need manual review, not automatic failure.AxeBuilder.analyze(driver) returns zero critical violationsTake fugazi/accessibility-selenium-testing from the repository into ~/.claude/skills for personal
use, or into .claude/skills inside a project.
The agent identifies a skill by the name field in its header. Two skills with the
same name cannot sit side by side — one of them will be ignored.