Exit course
Chapter 4 of 10 Intermediate 7 min read 2 quick checks Updated

axe-core with Selenium in Java

On this page
  1. The Maven project
  2. One driver, local or remote
  3. The scans
  4. Run it
  5. Run the same tests on a remote browser
  6. Python and other languages

Many teams that need accessibility checks already have a Selenium suite in Java, and rewriting it in Playwright just to get axe is not a good trade. Deque publishes com.deque.html.axe-core:selenium, a Java wrapper that injects the same axe-core engine through WebDriver and returns the same results. This chapter adds it to a JUnit 5 project, runs it on a local Chrome and then, without code changes, on a remote browser.

The Maven project#

pom.xml needs three dependencies:

<dependencies>
  <dependency>
    <groupId>org.seleniumhq.selenium</groupId>
    <artifactId>selenium-java</artifactId>
    <version>4.52.0</version>
  </dependency>
  <dependency>
    <groupId>com.deque.html.axe-core</groupId>
    <artifactId>selenium</artifactId>
    <version>4.14.0</version>
  </dependency>
  <dependency>
    <groupId>org.junit.jupiter</groupId>
    <artifactId>junit-jupiter</artifactId>
    <version>5.13.4</version>
    <scope>test</scope>
  </dependency>
</dependencies>

plus maven-surefire-plugin 3.x so mvn test runs JUnit 5 tests, and <maven.compiler.release>17</maven.compiler.release>. The axe wrapper's version follows the axe-core version it bundles, so 4.14.0 runs the same rules as the Playwright chapter.

If you use TestNG instead of JUnit, nothing below changes except the annotations; the Selenium with Java and TestNG course shows that setup.

One driver, local or remote#

The test class starts a local Chrome when no TestingBot credentials are set, and a remote Chrome on Windows 11 when they are. Selenium Manager downloads the matching chromedriver for local runs, so there is nothing else to install.

package com.example;

import com.deque.html.axecore.results.Results;
import com.deque.html.axecore.results.Rule;
import com.deque.html.axecore.selenium.AxeBuilder;
import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.TestInfo;
import org.junit.jupiter.api.extension.AfterTestExecutionCallback;
import org.junit.jupiter.api.extension.RegisterExtension;
import org.openqa.selenium.JavascriptExecutor;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;
import org.openqa.selenium.chrome.ChromeOptions;
import org.openqa.selenium.remote.RemoteWebDriver;

import java.net.URL;
import java.util.List;
import java.util.Map;
import java.util.stream.Collectors;

import static org.junit.jupiter.api.Assertions.assertTrue;

class AccessibilityTest {
    private static final List<String> WCAG_AA =
        List.of("wcag2a", "wcag2aa", "wcag21a", "wcag21aa", "wcag22a", "wcag22aa");

    private WebDriver driver;
    private boolean onTestingBot;

    // Runs before @AfterEach, so the session is still open when we report the result.
    @RegisterExtension
    AfterTestExecutionCallback reportResult = context -> {
        if (!onTestingBot) return;
        boolean passed = context.getExecutionException().isEmpty();
        ((JavascriptExecutor) driver).executeScript("tb:test-result=" + (passed ? "passed" : "failed"));
        System.out.println("TestingBot session " + ((RemoteWebDriver) driver).getSessionId()
            + " " + context.getDisplayName() + ": " + (passed ? "passed" : "failed"));
    };

    @BeforeEach
    void startBrowser(TestInfo info) throws Exception {
        String key = System.getenv("TB_KEY");
        String secret = System.getenv("TB_SECRET");
        ChromeOptions options = new ChromeOptions();
        if (key == null) {
            driver = new ChromeDriver(options);
            return;
        }
        options.setBrowserVersion("latest");
        options.setPlatformName("WIN11");
        options.setCapability("tb:options", Map.of(
            "name", info.getDisplayName(),
            "build", System.getenv().getOrDefault("TB_BUILD", "a11y-local")));
        driver = new RemoteWebDriver(
            new URL("https://" + key + ":" + secret + "@hub.testingbot.com/wd/hub"), options);
        onTestingBot = true;
    }

    @AfterEach
    void quit() {
        if (driver != null) driver.quit();
    }

Two details are worth understanding rather than copying:

  • Why an AfterTestExecutionCallback? TestingBot cannot see your JUnit assertions, so the test reports its own result with executeScript("tb:test-result=passed") (documented in annotating tests). That call needs an open session. JUnit's TestWatcher runs after @AfterEach, when the driver has already quit; AfterTestExecutionCallback runs right after the test method, before @AfterEach, and still knows whether the test threw.
  • Why build? It groups every session from one run in the TestingBot dashboard. You will use it for the certification practical.

The scans#

    @Test
    void loginPageHasNoWcagViolations() {
        driver.get("https://the-internet.herokuapp.com/login");

        Results results = new AxeBuilder()
            .withTags(WCAG_AA)
            .analyze(driver);

        assertTrue(results.violationFree(), describe(results.getViolations()));
    }

    @Test
    void marsDemoHasNoWcagViolations() {
        driver.get("https://dequeuniversity.com/demo/mars/");

        Results results = new AxeBuilder()
            .withTags(WCAG_AA)
            .analyze(driver);

        assertTrue(results.violationFree(), describe(results.getViolations()));
    }

    static String describe(List<Rule> violations) {
        return violations.stream()
            .map(v -> String.format("%s (%s, %d nodes): %s%n    first: %s",
                v.getId(), v.getImpact(), v.getNodes().size(), v.getHelp(),
                v.getNodes().get(0).getTarget()))
            .collect(Collectors.joining("\n", "Accessibility violations:\n", ""));
    }
}

The Java API mirrors the JavaScript one: new AxeBuilder() with withTags, withRules, disableRules, include and exclude, then analyze(driver). The Results object has getViolations(), getPasses(), getIncomplete() and getInapplicable(), and violationFree() is a shortcut for "no violations". Each Rule exposes getId(), getImpact(), getHelp(), getHelpUrl() and getNodes().

Like the Playwright version, describe turns the result into a short failure message. Without it a failing assertTrue only says expected: <true> but was: <false>, and nobody can act on that.

Run it#

mvn test

The login page passes: it has no WCAG A or AA violations (a scan without the tag filter would report three best-practice issues, such as the missing h1). Deque's Mars Commuter demo is broken on purpose, and the second test fails with a readable list:

Accessibility violations:
aria-allowed-attr (critical, 1 nodes): Elements must only use supported ARIA attributes
    first: [#player, .ytmVideoInfoVideoTitle]
aria-prohibited-attr (serious, 1 nodes): Elements must only use permitted ARIA attributes
    first: [#player, #movie_player]
button-name (critical, 1 nodes): Buttons must have discernible text
    first: [.departure-date > .ui-datepicker-trigger:nth-child(4)]
color-contrast (serious, 6 nodes): Elements must meet minimum color contrast ratio thresholds
    first: [a[href="mars2.html?a=be_bold"] > h3]
frame-title (serious, 1 nodes): Frames must have an accessible name
    first: [#fafbba78]
html-has-lang (serious, 1 nodes): <html> element must have a lang attribute
    first: [html]
image-alt (critical, 4 nodes): Images must have alternative text
    first: [img[src$="seg"]]
link-in-text-block (serious, 1 nodes): Links must be distinguishable without relying on color
    first: [a[href="mars2.html?a=last_will"]]
link-name (serious, 8 nodes): Links must have discernible text
    first: [.link[href$="mars/#"]]
select-name (critical, 2 nodes): Select element must have an accessible name
    first: [#time0]
target-size (serious, 31 nodes): All touch targets must be 24px large, or leave sufficient space
    first: [.loginnow > ... > .search[name="query"][placeholder="search"]]

(The last selector is shortened here; axe prints the full path.) Three things to notice:

  1. Selectors can have two parts. [#player, .ytmVideoInfoVideoTitle] means "inside the iframe #player, the element .ytmVideoInfoVideoTitle". axe scans iframes too, including the embedded YouTube player. Those two ARIA violations belong to a third party; chapter 4 shows how to scope them out deliberately rather than by accident.
  2. target-size is the WCAG 2.2 rule. It is tagged wcag22aa and fires 31 times here. If you copy an older tag list that stops at wcag21aa, you silently skip it.
  3. Impact is not a priority order you should follow blindly. A missing lang attribute is one line to fix and affects every screen reader user on the page; fix the cheap, broad ones first.

Your Java scan uses withTags(List.of("wcag2a", "wcag2aa", "wcag21a", "wcag21aa")) and passes. A WCAG 2.2 AA audit then reports undersized buttons. Why did the scan miss them?

The wrappers share one engine and one rule set. withTags runs only rules carrying at least one of the listed tags, so leaving out wcag22aa drops the 2.2 rules.

Run the same tests on a remote browser#

Export your TestingBot key and secret (from the member area) and run again:

export TB_KEY=your-key TB_SECRET=your-secret TB_BUILD=course-a11y-java
mvn test
TestingBot session 0af6aad5be92-...-13127366 marsDemoHasNoWcagViolations(): failed
TestingBot session 27582386cefb-...-15581851 loginPageHasNoWcagViolations(): passed

Same results as the local run, now on Chrome on Windows 11, with a video and logs for each session in the dashboard and the pass or fail status set by the callback. The axe script is injected through executeScript, so it works on any remote WebDriver browser; For Firefox, Edge or Safari you change the Options class and platformName. The Selenium capabilities generator lists the combinations, and the JUnit guide covers running classes in parallel.

You moved tb:test-result into a JUnit TestWatcher, and now every session ends with "no such session". Why?

JUnit calls TestWatcher after all after-each callbacks. AfterTestExecutionCallback runs between the test method and @AfterEach, so the session is still open and the outcome is known.

Python and other languages#

For Selenium in Python, a common route is to inject the axe.min.js file from the axe-core npm package with execute_script and then call axe.run() through execute_async_script. On the TestingBot grid there is a shortcut that works in every language with no package at all: the tb:accessibility command, which chapter 7 covers.