accessibility-selenium-testing

What this skill does

# 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.1 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.

---

## WCAG Compliance Levels

| Level | Requirement | Legal Status | Axe Tags |
|-------|-------------|--------------|----------|
| **Level A** | Basic accessibility (must have) | Minimum legal requirement | `wcag2a`, `wcag21a` |
| **Level AA** | Intermediate (should have) | Legal requirement in most jurisdictions | `wcag2aa`, `wcag21aa` |
| **Level AAA** | Advanced (nice to have) | Not typically required | `wcag2aaa`, `wcag21aaa` |
| **Best Practice** | Industry recommendations | Not WCAG but improves UX | `best-practice` |

---

## 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` |
| `.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 |

---

## Core Capabilities

### 1. Axe Builder Analysis
- **Full Page Scan**: `new AxeBuilder().analyze(driver)`
- **Component Scan**: `new AxeBuilder().include("#my-component").analyze(driver)`
- **Rule Configuration**: `.withTags(List.of("wcag2a", "wcag2aa"))`
- **Exclusions**: `.exclude(".legacy-footer")` (use carefully, document reason)

### 2. Validation & Assertion
- Analyze `Results.getViolations()` - should be empty
- Filter by impact level (Critical, Serious, Moderate, Minor)
- Use AssertJ Soft Assertions to report all violations before failing

### 3. Reporting
- Log: Rule ID + Help URL + Selector for each violation
- Serialize `Results` to JSON for dashboards
- Attach to Allure reports

---

## Your Role

As an Accessibility Automation Specialist:

1. **Integration**: Configure axe-core with Selenium WebDriver
2. **Configuration**: Set up `AxeBuilder` with appropriate WCAG tags
3. **Analysis**: Parse results to identify violations by impact
4. **Assertion**: Fail on Critical/Serious, warn on Moderate/Minor
5. **Reporting**: Log Help URLs and selectors for remediation

---

## Step-by-Step Workflows

### Workflow 1: Add A11y Scan to Existing Test

1. **Add dependency to pom.xml**
   ```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 Guide](references/axe_patterns.md)

3. **Add scan after page loads**
   ```java
   driver.get("https://example.com");
   waitForPageReady();
   AccessibilityHelper.verifyPageAccessibility(driver);
   ```

4. **Run and review violations**
   ```bash
   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**
   ```java
   Results results = new AxeBuilder()
       .withTags(List.of("wcag2a", "wcag2aa"))
       .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**
   ```java
   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**
   ```bash
   mvn test -Dheadless=true -Dgroups=a11y
   ```

2. **Set zero-tolerance for Critical/Serious**
   ```java
   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

### Basic Full-Page Scan

```java
@Step("Verify page accessibility - WCAG 2.1 AA")
public void verifyPageAccessibility(WebDriver driver) {
    Results results = new AxeBuilder()
        .withTags(List.of("wcag2a", "wcag2aa", "wcag21a", "wcag21aa"))
        .analyze(driver);

    logViolations(results.getViolations());

    assertThat(results.violationFree())
        .as("Accessibility violations found on: %s", driver.getCurrentUrl())
        .isTrue();
}
```

### Component-Specific Scan

```java
@Step("Verify component accessibility: {selectors}")
public void verifyComponentAccessibility(WebDriver driver, String... selectors) {
    AxeBuilder builder = new AxeBuilder()
        .withTags(List.of("wcag2a", "wcag2aa"));

    for (String selector : selectors) {
        builder.include(selector);
    }

    Results results = builder.analyze(driver);
    logViolations(results.getViolations());

    assertThat(results.violationFree())
        .as("Component accessibility check failed")
        .isTrue();
}
```

### Filter by Impact Level

```java
@Step("Verify no critical accessibility violations")
public void verifyCriticalViolations(WebDriver driver) {
    Results results = new AxeBuilder()
        .withTags(List.of("wcag2a", "wcag2aa"))
        .analyze(driver);

    List<Rule> criticalViolations = results.getViolations().stream()
        .filter(v -> List.of("critical", "serious").contains(v.getImpact()))
        .toList();

    if (!criticalViolations.isEmpty()) {
        logViolations(criticalViolations);
    }

    assertThat(criticalViolations)
        .as("Critical/Serious accessibility violations found")
        .isEmpty();
}
```

### With Documented Exclusions

```java
/**
 * Scan with exclusions for known issues.
 * Exclusions must be documented with ticket reference.
 */
@Step("Verify accessibi