Automation of Accessibility Testing in Cucumber BDD Using Axe-Selenium-Java
Automating Accessibility testing uses automated tools and frameworks to test accessibility issues. By automating testing, time is saved and issues are found at an early stage. Automating accessibility testing will follow the accessibility standards like WCAG(Web Content Accessibility Guidelines). Some automated accessibility tools are Axe (axe-selenium-java), Pa11y, and Lighthouse.
Axe-core is an open-source, automated accessibility testing library. It serves as the engine behind the tools created by Deque Systems, which are utilized to test websites and other digital interfaces for accessibility. Axe-core assists developers and testers in identifying and resolving accessibility issues, ensuring that websites are usable by people with disabilities.
We are using Java, Maven, Selenium WebDriver, Axe-core via axe-selenium-java, TestNG, and Cucumber BDD in the DsAlgo project.
Maven: It is a build tool used to handle the dependencies that are needed to process the streamlining and setup of the automation framework.
Selenium WebDriver: Automates browser actions to simulate user interactions with the web application.
TestNG: It runs and structures the test cases and supports validations, parallel testing, and comprehensive reporting.
Cucumber BDD: Enables behavior-driven development with the Gherkin language to bridge the communication gap between developers and business stakeholders.
Steps to perform automating the Accessibility testing using Cucumber BDD with Axe-Selenium Java.
Step 1: We can add the axe-selenium dependency in the pom.xml file.
<dependency>
<groupId>com.deque</groupId>
<artifactId>axe-selenium</artifactId>
<version>3.0</version>
</dependency>
Step 2: Download axe.min.js from the link https://www.cdnpkg.com/axe-core/file/axe.min.js/
Place that under src/test/resources/axe.min.js.
It's a JavaScript file containing the entire Axe-core engine, built by Deque Systems. Axe uses this script to scan the HTML DOM and identify accessibility violations based on WCAG 2.1 and Section 508 standards.
Step 3: Create AccessibilityUtil under the utilities folder, src\test\java\utilities\AccessibilityUtil.java
package utilities;
import java.net.URL;
import org.json.JSONArray;
import org.json.JSONObject; #JSONObject from org.json
import org.openqa.selenium.WebDriver; #WebDriver from org. openqa.selenium
import java.io.ByteArrayInputStream;
import com.deque.axe.AXE;
import io.qameta.allure.Allure;
public class AccessibilityUtil {
private static final URL scriptUrl = AccessibilityUtil.class.getResource("/axe.min.js");
public static void runAxeAudit(WebDriver driver, String pageLabel) {
JSONObject responseJSON = new AXE.Builder(driver, scriptUrl).analyze();
JSONArray violations = responseJSON.getJSONArray("violations");
if (violations.length() == 0) {
System.out.println("✅ No accessibility issues found on: " + pageLabel);
} else {
StringBuilder report = new StringBuilder();
report.append("🔎 Accessibility Violations Found on ").append(pageLabel).append(":\n");
for (int i = 0; i < violations.length(); i++) {
JSONObject violation = violations.getJSONObject(i);
report.append("🔴 ").append(violation.getString("help")).append("\n")
.append("Impact: ").append(violation.getString("impact")).append("\n")
.append("Description: ").append(violation.getString("description")).append("\n")
.append("Tags: ").append(violation.getJSONArray("tags")).append("\n\n");
}
// Log to console and Allure (but DO NOT fail test)
System.out.println(report);
Allure.addAttachment("Accessibility Violations - " + pageLabel,
new ByteArrayInputStream(report.toString().getBytes()));
}
}
}
This class injects axe.min.js into the currently loaded webpage via JavaScript executor. Executes the Axe accessibility scan on the DOM and collects any accessibility violations like missing alt text, Color contrast, and ARIA roles misused.
Returns a structured JSON report with Rule ID, Description, Impact level (minor, moderate, serious, critical), and elements affected.
Step 4: Perform Accessibility audit code in our stepdefinition classes.
@Then("the user is directed to the Graph Data Structure Page")
public void the_user_is_directed_to_the_graph_data_structure_page() {
// ✅ Run accessibility audit here
AccessibilityUtil.runAxeAudit(DriverManager.getDriver(), "graph-page-accessibility");
Assert.assertTrue(graphpage.isGraphPageDisplayed(), "Graph Data Structure Page is not displayed");
LoggerLoad.info("Ridirecting toGraph Data Structure Page ");
}
Step 5: Run the testrunner class. It audits the above Graph page and provides the output on the console with any violations found.
Allure Reports:
Allure Report is a widely used open-source tool designed to visualize test run results. It integrates seamlessly into your testing workflow with minimal configuration. The reports generated by Allure are accessible from any location and are easy to understand, even for those without deep technical knowledge.
Step 6:
We can integrate the allure reports, and will see the Accessibility violations file attachment with all details which was found on that particular website when we did an audit. To see the attachment, go to the allure report under suites and click on any test case, and then see the attachment at the then statement. We will see the attachments containing audit results.
To perform allure integration with Selenium Cucumber, we can add allure dependencies in the pom.xml
<dependency>
<groupId>io.qameta.allure</groupId>
<artifactId>allure-cucumber7-jvm</artifactId>
<version>2.29.0</version>
</dependency>
<dependency>
<groupId>io.qameta.allure</groupId>
<artifactId>allure-testng</artifactId>
<version>2.29.0</version>
</dependency>
Step 7: In AccessibilityUtil. Java class, we can attach the accessibility violations report to the Allure report as
Allure.addAttachment("Accessibility Violations - " + pageLabel,
new ByteArrayInputStream(report.toString().getBytes()));
Allure report:
Allure reports advantages: It supports attachments like screenshots, logs, JSON reports (like Axe accessibility results), console outputs, and more, directly to each test step or scenario.
Allure can be integrated with Jenkins, GitHub Actions, GitLab CI, Azure DevOps, etc.
Conclusion:
Testing for accessibility goes beyond merely meeting standards — it focuses on making everything inclusive.
By combining tools such as Axe with Selenium, teams can automate checks for accessibility, identify problems early, and provide a superior user experience for all.
Automation of Accessibility gives you speed and repeatability and is perfect for catching obvious or rule-based accessibility issues at scale.
Use Manual Accessibility when you need to cover 100%, including context-based checks.
A combination of automation and manual Accessibility testing gives comprehensive coverage.
