---
title: axe-core with Selenium in Java | TestingBot
description: 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…
source_url:
  html: https://testingbot.com/resources/courses/accessibility-testing/axe-with-selenium-java
  md: https://testingbot.com/resources/courses/accessibility-testing/axe-with-selenium-java.md
---

Course

[Accessibility Testing Tutorial: WCAG 2.2](https://testingbot.com/resources/courses/accessibility-testing)

Chapter 4 of 10

1. [1 Accessibility Testing Tutorial: WCAG 2.2 in Practice](https://testingbot.com/resources/courses/accessibility-testing)
2. [2 Manual Accessibility Checks You Still Need](https://testingbot.com/resources/courses/accessibility-testing/manual-accessibility-checks)
3. [3 axe-core with Playwright: Your First Scan](https://testingbot.com/resources/courses/accessibility-testing/axe-core-with-playwright)
4. [4 axe-core with Selenium in Java](https://testingbot.com/resources/courses/accessibility-testing/axe-with-selenium-java)
5. [5 Scoping Scans, Rules and a Baseline of Known Issues](https://testingbot.com/resources/courses/accessibility-testing/scoping-rules-and-baselines)
6. [6 Fixing Common Violations: Contrast, Forms and ARIA](https://testingbot.com/resources/courses/accessibility-testing/fixing-common-violations)
7. [7 Running Accessibility Checks in CI](https://testingbot.com/resources/courses/accessibility-testing/accessibility-checks-in-ci)
8. [8 Accessibility Testing on TestingBot](https://testingbot.com/resources/courses/accessibility-testing/accessibility-testing-on-testingbot)
9. [9 What Automated Accessibility Testing Cannot Catch](https://testingbot.com/resources/courses/accessibility-testing/what-automation-cannot-catch)
10. [10 Knowledge check](https://testingbot.com/resources/courses/accessibility-testing/knowledge-check)

[Exit course](https://testingbot.com/resources/courses)

 Chapter 4 of 10 Intermediate 7 min read 2 quick checks Updated Nov 2026 

# axe-core with Selenium in Java
On this page
1. [The Maven project](https://testingbot.com#the-maven-project)
2. [One driver, local or remote](https://testingbot.com#one-driver-local-or-remote)
3. [The scans](https://testingbot.com#the-scans)
4. [Run it](https://testingbot.com#run-it)
5. [Run the same tests on a remote browser](https://testingbot.com#run-the-same-tests-on-a-remote-browser)
6. [Python and other languages](https://testingbot.com#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[#](https://testingbot.com#the-maven-project)

`pom.xml` needs three dependencies:

```xml
<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](https://testingbot.com/resources/courses/selenium-testng) shows that setup.

## One driver, local or remote[#](https://testingbot.com#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.

```java
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](https://testingbot.com/support/web-automate/selenium/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[#](https://testingbot.com#the-scans)

```java
@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[#](https://testingbot.com#run-it)

```bash
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 Java wrapper does not support WCAG 2.2 The `target-size` rule is tagged `wcag22aa`, which the list does not include `target-size` only runs in Playwright Undersized buttons are always reported as `incomplete`

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[#](https://testingbot.com#run-the-same-tests-on-a-remote-browser)

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

```bash
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](https://testingbot.com/support/web-automate/selenium/capabilities) lists the combinations, and the [JUnit guide](https://testingbot.com/support/web-automate/selenium/java/junit) covers running classes in parallel.

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

 `tb:test-result` only works in Playwright The build name is missing from `tb:options` `TestWatcher` runs before the test method starts `TestWatcher` runs after `@AfterEach` has already quit the driver

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[#](https://testingbot.com#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.

[Previous · Chapter 3 axe-core with Playwright: Your First Scan](https://testingbot.com/resources/courses/accessibility-testing/axe-core-with-playwright) [Next · Chapter 5 Scoping Scans, Rules and a Baseline of Known Issues](https://testingbot.com/resources/courses/accessibility-testing/scoping-rules-and-baselines)

On this page

1. [The Maven project](https://testingbot.com#the-maven-project)
2. [One driver, local or remote](https://testingbot.com#one-driver-local-or-remote)
3. [The scans](https://testingbot.com#the-scans)
4. [Run it](https://testingbot.com#run-it)
5. [Run the same tests on a remote browser](https://testingbot.com#run-the-same-tests-on-a-remote-browser)
6. [Python and other languages](https://testingbot.com#python-and-other-languages)

Certification

Earn the free, resume-worthy TestingBot Accessibility Testing Certification for this course.

[How it works](https://testingbot.com/resources/courses/accessibility-testing/certification)
