Extend Selenium e2e tests with UserWay accessibility analysis

UserWay CI/CD injects accessibility analysis into existing end-to-end tests through the a11y-selenium-java maven library. This library works with Selenium's WebDriver instance, collects accessibility insights during e2e test executions, and saves reports in the uw-a11y-reports directory.

1. Install a11y-selenium-java maven library

Install the a11y-selenium-java package at the root of your Selenium e2e testing project using Maven or Gradle. Alternartively, download the latest version from https://mvnrepository.com/artifact/org.userway/a11y-selenium-java (opens in a new tab)

<dependency>
    <groupId>org.userway</groupId>
    <artifactId>a11y-selenium-java</artifactId>
    <version>${USERWAY_SELENIUM_VERSION}</version>
</dependency>

For more information about installation of a11y-selenium-java library refer to the documentation

2. Create AuditConfig for your selenium e2e tests

Import the AuditConfig class and create an instance of AuditConfig in your Selenium test classes in order to initialize and configure accessibility analysis. It is recommended to create a setup class, e.g., SetupUserWay.java, and implement a static function that creates AuditConfig, e.g., createAuditConfig(). Then, invoke SetupUserWay.createAuditConfig() in all your tests.

import org.openqa.selenium.WebDriver;
import org.userway.selenium.model.config.AnalysisConfig;
import org.userway.selenium.model.config.AuditConfig;
 
public class SetupUserWay {
 
private static AnalysisConfig ANALYSIS_CONFIG = AnalysisConfig.builder()
  .switchOff(false)
  .build();
 
public static AuditConfig getAuditConfig(WebDriver driver) {
  return AuditConfig.builder()
  .driver(driver)
  .analysisConfiguration(ANALYSIS_CONFIG)
  .saveReport(true)
  .reportPath('./uw-a11-reports')
  .elementScreenshots(false)
  .build();
  }
}

For more information about configuration of @userway/a11y-cypress package refer to the documentation To see more examples of a11y-selenium-java library usage, visit sample project repository

3. Invoke userwayAnalysis() in your selenium e2e tests

Adding the AccessibilityAuditor.userwayAnalysis() static function call to your existing end-to-end tests allows you to perform static page analysis at any point during test execution. With each such invocation, a report of accessibility violations will be saved in the uw-a11y-reports directory. Pass the AuditConfig instance created in the previous step as a function call argument.

cy.userwayAnalysis()

Note: cy.userwayAnalysis() accepts an argument and can be parametrized in order to meet your specific conditions and requirements. Here is more advanced usage:

// YourSeleniumTest.java
 
import org.userway.selenium.AccessibilityAuditor;
 
ChromeOptions options = new ChromeOptions();
options.addArguments("--headless");
 
WebDriver driver = new ChromeDriver();
driver.get('http://localhost:8080/terms.html');
assertThat(driver.getTitle()).contains('Terms');
 
AuditConfig auditConfig = SetupUserWay.getAuditConfig(driver);
AccessibilityAuditor.userwayAnalysis(auditConfig);

As a rule of thumb, you should invoke AccessibilityAuditor.userwayAnalysis() at the end of every e2e test case.

Note: Every AccessibilityAuditor.userwayAnalysis() function invocation counts towards consuming project Self-Hosted scans.

4. Optional configuration

• Update .gitignore. Ignore reports generated by the userwayAnalysis function in your git commits by adding the report directory to the .gitignore file.

uw-a11y-reports

5. Verify configuration

It is always a good idea to validate changes in the steps above before committing them to the repository. To verify if your Selenium configuration is correct - there are a few steps that can be performed on the local developer environment:

• Make all necessary changes described above
• Run your e2e tests locally
• Make sure there are no errors and tests pass successfully
• Check the directory uw-a11y-reports/reports for JSON files. The number of report files should be equal to the number of AccessibilityAuditor.userwayAnalysis() invocations in your e2e tests. An example of an expected report file name is uw-a11y-report-lvoeobzh.json.

For more information about troubleshooting of a11y-selenium-java library refer to the documentation

Prerequisites

• a11y-selenium-java compatible with Chrome and Chromium only
• Selenium version 4.20.0 or higher is required
• java 17 or higher is required