Java Troubleshooting

Link to Java Troubleshooting copied to clipboard

How to work around errors caused by axe DevTools Java 4.3 and later. For information on troubleshooting the Java Playwright integration, see Java Playwright Troubleshooting.

Version 4.3.0 and above of the axe DevTools integrations use a new technique when calling which opens a new window at the end of a run. Many of the issues outlined in this document address common problems with this technique and their potential solutions.

Having an Out-of-date Driver

A common problem is having an out-of-date driver. To fix this issue make sure that your local install of geckodriver or chromedriver is up-to-date.

An example error message for this problem will include a message about switchToWindow.

For example, see the following:

(node:17566) UnhandledPromiseRejectionWarning: Error: Malformed type for "handle" parameter of command switchToWindow
Expected: string
Actual: undefined

Having Popup blockers enabled

Popup blockers prevent us from opening the new window when calling AxeSelenium::run . The default configuration for most automation testing libraries should allow popups. Please make sure that you do not explicitly enable popup blockers which may cause an issue while running the tests.

AxeBuilder::setLegacyMode(boolean legacy)

If for some reason you are unable to run the new AxeSelenium::run technique without errors, axe provides a new chainable method that allows you to run the legacy version of AxeSelenium::run. When using this method axe excludes accessibility issues that may occur in cross-domain frames and iframes.


AxeBuilder::setLegacyMode is deprecated and will be removed in v5.0. Please report any errors you may have while running AxeSelenium::run so that they can be fixed before the legacy version is removed.


import com.deque.html.axedevtools.selenium.AxeSelenium;
import com.deque.html.axedevtools.selenium.AxeDriver;
import com.deque.html.axecore.selenium.AxeBuilder;

public class Main {
    public static void main(String[] args) {
        var webDriver = ...; // open wbdriver and go to your test page
        var axeDriver = new AxeDriver(webDriver);
        var results = new AxeSelenium(new AxeBuilder().setLegacyMode())