Getting Started

The a11y-selenium-java Maven library (artifact org.levelci:a11y-selenium-java) enables accessibility testing in your Selenium workflow.
It runs static page analysis against a Selenium WebDriver and generates detailed reports of accessibility violations based on WCAG guidelines and ACT rules.


// YourSeleniumTest.java
import org.levelci.selenium.AccessibilityAuditor;
import org.levelci.selenium.model.config.AnalysisConfig;
import org.levelci.selenium.model.config.AuditConfig;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;
import org.openqa.selenium.chrome.ChromeOptions;
 
WebDriver driver = new ChromeDriver(new ChromeOptions().addArguments("--headless=new"));
driver.get("http://localhost:5000");
 
AuditConfig auditConfig = AuditConfig.builder()
    .driver(driver)
    .analysisConfiguration(AnalysisConfig.builder().build())
    .saveReport(true)
    .build();
 
AccessibilityAuditor.levelAnalyze(auditConfig);
driver.quit();

Prerequisites

Java 17 or higher
Selenium WebDriver 4.x
Apache Maven 3.7+ or Gradle
Compatible with Chrome and Chromium only

Installation

1. Configure the Cloudsmith Maven repository

The a11y-selenium-java artifact is published to a private Level CI Maven repository, not Maven Central. Register it in your pom.xml:


<!-- pom.xml -->
<repositories>
  <repository>
    <id>level-access-level-ci</id>
    <url>https://dl.levelaccess.net/${env.CLOUDSMITH_TOKEN}/level-ci/maven/</url>
    <releases>
      <enabled>true</enabled>
      <updatePolicy>always</updatePolicy>
    </releases>
    <snapshots>
      <enabled>true</enabled>
      <updatePolicy>always</updatePolicy>
    </snapshots>
  </repository>
</repositories>

The repository URL embeds the token via ${env.CLOUDSMITH_TOKEN}. If you’d rather use Maven server credentials, add a matching <server> entry in ~/.m2/settings.xml instead.

2. Declare a Cloudsmith token

Export the token in your local shell and add it as a CI secret in your repository settings (e.g. GitHub Actions, GitLab CI, Bitbucket Pipelines):


export CLOUDSMITH_TOKEN=MY_CLOUDSMITH_TOKEN

By using the CLOUDSMITH_TOKEN you’ll be able to download the package.

3. Add the dependency

Maven:


<!-- pom.xml -->
<dependency>
  <groupId>org.levelci</groupId>
  <artifactId>a11y-selenium-java</artifactId>
  <version>{paste-latest-version-here}</version>
  <scope>test</scope>
</dependency>

Gradle:


// build.gradle
testImplementation "org.levelci:a11y-selenium-java:{paste-latest-version-here}"

This adds org.levelci:a11y-selenium-java to the test classpath of your project.

Setup

a11y-selenium-java exposes a single static entry point — AccessibilityAuditor.levelAnalyze(AuditConfig) — and two builder-style configuration classes: AuditConfig (Selenium-side wiring) and AnalysisConfig (analysis options shared with the JS frameworks’ LaunchConfig).

The recommended pattern is a small helper class that builds an AuditConfig from any WebDriver. Your tests then reuse it everywhere:


// LevelSetup.java
 
import org.levelci.selenium.model.config.AnalysisConfig;
import org.levelci.selenium.model.config.AuditConfig;
import org.openqa.selenium.WebDriver;
 
public class LevelSetup {
 
  private static final AnalysisConfig ANALYSIS_CONFIG = AnalysisConfig.builder()
      .reportPath("./level-ci/level-ci-reports")
      .build();
 
  public static AuditConfig getAuditConfig(WebDriver driver) {
    return AuditConfig.builder()
        .driver(driver)
        .analysisConfiguration(ANALYSIS_CONFIG)
        .saveReport(true)
        .build();
  }
}

Use it inside your tests:


// YourSeleniumTest.java
import org.levelci.selenium.AccessibilityAuditor;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;
import org.openqa.selenium.chrome.ChromeOptions;
 
WebDriver driver = new ChromeDriver(new ChromeOptions().addArguments("--headless=new"));
driver.get("https://www.google.com");
 
AccessibilityAuditor.levelAnalyze(LevelSetup.getAuditConfig(driver));
 
driver.quit();

Running AccessibilityAuditor.levelAnalyze creates the report folder configured via reportPath (default ./level-ci/level-ci-reports). The report file structure enables issue deduplication, which helps in achieving faster scans.

Note: For more details and the full configuration surface see the Selenium Java API reference.