Run accessibility scans with Selenium Java

Level CI integrates accessibility analysis into your existing Selenium Java tests through the a11y-selenium-java library. The library uses your existing Selenium WebDriver instance to perform accessibility analysis, generate reports, and save results for processing by Level CI.
Accessibility analysis can be executed at any point during a test flow, allowing you to identify accessibility issues alongside functional test results.

Prerequisites

Before you begin, ensure you have:

Java 17 or later
Selenium WebDriver 4.x
A Level CI organization
A Level CI project
A Cloudsmith token with access to the Level CI Maven repository
An existing Selenium E2E test suite

Install the a11y-selenium-java Maven library

Install the a11y-selenium-java package in your Selenium project using Maven.

<dependency>
<groupId>org.levelci</groupId>
<artifactId>a11y-selenium-java</artifactId>
<version>0.2.1</version>
<scope>test</scope>
</dependency>

Configure the Maven repository

The a11y-selenium-java artifact is hosted in the private Level CI Maven repository and is not available through Maven Central.

Add the following repository configuration to your pom.xml file:

<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 the CLOUDSMITH_TOKEN environment variable locally and configure it as a secret within your CI/CD platform.

export CLOUDSMITH_TOKEN=<your-token>

Examples include:

GitHub Actions Secrets
GitLab CI/CD Variables
Jenkins Credentials
Azure DevOps Variable Groups

Create an AuditConfig instance

Create a reusable AuditConfig configuration that associates accessibility analysis with your Selenium WebDriver instance.

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

This configuration:

Associates the Selenium WebDriver instance with accessibility analysis.
Defines the report output location.
Enables report generation after analysis execution.

Run accessibility analysis

After creating the AuditConfig instance, invoke AccessibilityAuditor.levelAnalyze() within your Selenium tests.

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

Each invocation of levelAnalyze() performs a static accessibility analysis of the current page state and generates a report in the configured report directory.

Best practice

Run AccessibilityAuditor.levelAnalyze() only after the page reaches a stable state. In most cases, this should occur near the end of the test flow after:

Page navigation completes.
Dynamic content has loaded.
User interactions have finished.
Assertions validating expected functionality have passed.

Configure report storage

Create a level-ci directory at the root of your repository.

mkdir level-ci

This directory is used to store configuration files and generated artifacts required by the Level CI CLI during local execution and CI/CD workflows.

Update .gitignore

Accessibility reports generated during test execution should not typically be committed to source control.
Add the report directory to your .gitignore file:

# Level CI accessibility reports
level-ci-reports

If reports are generated under the level-ci directory, adjust the path accordingly.

Verify your configuration

Before committing changes, validate that the accessibility integration is functioning correctly.

Complete all installation and configuration steps.
Run your Selenium E2E test suite locally.

mvn test

Verify that:

Tests execute successfully.
Accessibility analysis runs without errors.
Accessibility reports are generated in the configured report directory.
No Level CI configuration or repository authentication errors occur.

Troubleshooting

If you encounter issues during installation, authentication, report generation, or test execution:

Verify that CLOUDSMITH_TOKEN is configured correctly.
Confirm access to the Level CI Maven repository.
Verify Selenium WebDriver compatibility.
Verify Java version requirements.
Confirm that the report output directory exists.

Next steps

After successfully integrating accessibility analysis into your Selenium tests:

Configure the Level CI CLI.
Upload generated accessibility reports to your Level CI project.
Integrate accessibility analysis into your CI/CD pipeline.
Monitor and remediate accessibility issues through the Level CI platform.

On this page: