Accessibility scan with Selenium (Java)

Extend Selenium E2E Tests with Level CI Accessibility Analysis

Level CI integrates accessibility analysis directly into your existing Selenium end-to-end tests through the a11y-selenium-java Maven library (artifact org.levelci:a11y-selenium-java). The library wraps Selenium’s WebDriver, collects accessibility insights during test execution, and saves reports in the level-ci-reports directory.

1. Install a11y-selenium-java

Add the library to your project using Maven or Gradle:

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

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

For more installation details, see the Level CI Selenium (Java) documentation.

2. Configure the Cloudsmith Maven repository

The 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>

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

export CLOUDSMITH_TOKEN=<token>

(Replace the placeholder with your actual token.)

3. Create an AuditConfig

Create a small setup class — for example, LevelSetup.java — that builds an AuditConfig from a WebDriver. Reuse this helper from every test class so all tests share the same configuration.

// 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();
  }
}

For full configuration options, see the Selenium Java API documentation.

4. Invoke AccessibilityAuditor.levelAnalyze

Call AccessibilityAuditor.levelAnalyze(auditConfig) in your tests to perform accessibility analysis at any point. Each invocation generates a JSON report in level-ci-reports/scope-reports/.

// YourSeleniumTest.java
 
import static org.assertj.core.api.Assertions.assertThat;
 
import org.levelci.selenium.AccessibilityAuditor;
import org.levelci.selenium.model.config.AuditConfig;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;
import org.openqa.selenium.chrome.ChromeOptions;
 
ChromeOptions options = new ChromeOptions();
options.addArguments("--headless=new");
 
WebDriver driver = new ChromeDriver(options);
driver.get("http://localhost:8080/terms.html");
assertThat(driver.getTitle()).contains("Terms");
 
AuditConfig auditConfig = LevelSetup.getAuditConfig(driver);
var result = AccessibilityAuditor.levelAnalyze(auditConfig);
assertThat(result.getError()).isNull();

Best Practice: Invoke AccessibilityAuditor.levelAnalyze() at the end of each test case, once the page has reached a stable state.

Note: Each invocation counts toward your project’s Self-Hosted scan quota.

For full configuration options, see the Selenium Java API documentation.

5. Optional Configuration

Git Ignore Reports: Add the report directory to .gitignore to avoid committing generated reports:

level-ci-reports

6. Verify Configuration

Validate your setup before committing:

1. Apply all the steps above.
2. Run your E2E tests locally (e.g. mvn test).
3. Ensure there are no errors and all tests pass.
4. Check level-ci-reports/scope-reports/ for JSON files. The number of reports should match the number of levelAnalyze() invocations. Example file: level-ci-report-lvoeobzh.json.

For troubleshooting, refer to the Level CI troubleshooting documentation.

7. Prerequisites

• Java 17 or higher
• Selenium WebDriver 4.x
• Compatible with Chrome and Chromium only
• Access to the private Level CI Cloudsmith Maven repository (Cloudsmith token)