API Reference for Selenium

This document is a reference for the AxeSelenium and AxeConfiguration classes, and for the selector, reporting, and results types they use. The AxeSelenium class should cover most use cases, and AxeConfiguration should cover the rest.

The examples on this page assume webDriver is your Selenium WebDriver and driver is an AxeDriver wrapping it.

com.deque.html.axedevtools.selenium.AxeSelenium

Configures an accessibility scan and runs it. Each configuration method returns the same AxeSelenium instance, so calls can be chained, and run(AxeDriver) performs the scan.

Results results = new AxeSelenium()
    .include(".my-css-class")
    .skipping("aria-required-parent")
    .run(driver);

AxeSelenium()

Creates an AxeSelenium scan that uses the global AxeConfiguration settings, such as the ruleset, audit suite, and report output directory. Use this constructor unless you need to customize the underlying AxeBuilder.

public AxeSelenium();

Example

Results results = new AxeSelenium().run(driver);

AxeSelenium(AxeBuilder)

Creates an AxeSelenium scan that runs through the AxeBuilder you supply, from the axe-core Selenium integration (com.deque.html.axecore.selenium.AxeBuilder). Use it to reach AxeBuilder options that AxeSelenium doesn't expose, such as legacy mode. The global AxeConfiguration settings still apply.

public AxeSelenium(AxeBuilder axeBuilder);

Parameters

Example

import com.deque.html.axecore.selenium.AxeBuilder;

Results results = new AxeSelenium(new AxeBuilder().setLegacyMode())
    .run(driver);

run(AxeDriver)

Scans the page that page currently shows, using every option configured on this AxeSelenium, and returns the results. Ignored violations (see AxeSelenium.ignoring(String, String)) are removed from the results, and, if logResults was called, the report files are written before run returns.

If axe-core reports an error while scanning, run throws it instead of returning results.

public Results run(AxeDriver page);

Parameters

Returns

A Results object (com.deque.html.axecore.results.Results) holding the violations, passes, incomplete, and inapplicable results.

Throws

• AxeRuntimeException (com.deque.html.axecore.results.AxeRuntimeException) when axe-core returns an error instead of results.
• RuntimeException when the scan itself fails, for example when axe.finishRun fails or the driver can't switch between windows.

Example

webDriver.get("https://example.com");
Results results = new AxeSelenium().run(driver);

if (!results.violationFree()) {
    System.out.println(results.getViolations().size() + " rules have violations");
}

runCommand()

Returns the generic axe.run script that AxeSelenium runs in the browser in legacy mode. The script doesn't include this scan's context or options, and with axe-core 4.3 or later (the default, non-legacy mode) scans run through a different set of calls. AxeSelenium passes this script to the reporter, so it's mainly useful when you build your own report text with AxeDevtoolsReporter.generateReport.

public String runCommand();

Returns

The script, as a String.

include(String)

Limits the scan to the elements matched by one CSS selector, and their descendants. Each call adds another area to the scan, so to test several unrelated parts of the page, call include once for each one. A single comma-separated selector (".sidebar, .some-class") also works, because it's passed to the browser as-is.

public AxeSelenium include(String cssSelector);

Parameters

Returns

This AxeSelenium, for method chaining.

Example

// Test .sidebar and .some-class, which are both in the top-level document
Results results = new AxeSelenium()
    .include(".sidebar")
    .include(".some-class")
    .run(driver);

include(List\<String>)

Limits the scan to an element inside one or more nested iFrames. Every string but the last matches one level of iFrame nesting; the last matches the element to test inside the innermost iFrame. The list describes one path, not several selectors.

Because there is no include(String...) overload, passing more than one string to include also produces a single iFrame selector rather than separate includes: include("#parent-iframe", "#html") resolves to include(Object...) and means the same thing as the example below.

include(FromFrames) expresses the same thing more explicitly and is the recommended form for new tests.

public AxeSelenium include(List<String> selector);

Parameters

Returns

This AxeSelenium, for method chaining.

Example

// Test #html inside the iframe matched by #parent-iframe
Results results = new AxeSelenium()
    .include(Arrays.asList("#parent-iframe", "#html"))
    .run(driver);

include(FromFrames)

Limits the scan to an element inside one or more nested iFrames, using an explicit FromFrames selector.

public AxeSelenium include(FromFrames fromFrames);

Parameters

Returns

This AxeSelenium, for method chaining.

Example

// Test the form inside the #payment-frame iframe
Results results = new AxeSelenium()
    .include(new FromFrames("#payment-frame", "form"))
    .run(driver);

include(FromShadowDom)

Limits the scan to an element inside one or more nested shadow DOM trees, using an explicit FromShadowDom selector.

public AxeSelenium include(FromShadowDom fromShadowDom);

Parameters

Returns

This AxeSelenium, for method chaining.

Example

// Test the #search form inside the shadow root attached to .app-header
Results results = new AxeSelenium()
    .include(new FromShadowDom(".app-header", "form#search"))
    .run(driver);

include(Object)

Limits the scan using a selector supplied as a single object. Java selects this overload only when the argument's static type is not one of the types above, such as a variable declared as Object. Prefer the typed overloads.

public AxeSelenium include(Object selector);

Parameters

Returns

This AxeSelenium, for method chaining.

Example

// The selector's type is chosen at runtime, so it's held as Object
Object scope = useFrame ? new FromFrames("#frame", "main") : "main";
Results results = new AxeSelenium()
    .include(scope)
    .run(driver);

include(Object...)

Limits the scan using a selector that mixes plain CSS selectors with FromFrames or FromShadowDom selectors, for cases the other overloads cannot express. All the arguments together form a single path to one element; they are not separate includes.

This overload is selected whenever the call passes more than one argument. Passing a single FromFrames or FromShadowDom selects include(FromFrames) or include(FromShadowDom) instead.

To reach an iFrame that lives inside a shadow root, nest the FromShadowDom selector inside the FromFrames selector. The reverse can't be expressed, because FromShadowDom only accepts strings.

public AxeSelenium include(Object... selector);

Parameters

Returns

This AxeSelenium, for method chaining.

Example

// Test .target inside the shadow root attached to #host, inside the #frame iframe
Results results = new AxeSelenium()
    .include("#frame", new FromShadowDom("#host", ".target"))
    .run(driver);

exclude(String)

Removes the elements matched by one CSS selector, and their descendants, from the scan. Each call removes another area, so to skip several unrelated parts of the page, call exclude once for each one. Exclusions apply on top of any include calls, which lets you test a region except for part of it.

public AxeSelenium exclude(String cssSelector);

Parameters

Returns

This AxeSelenium, for method chaining.

Example

// Test main, but skip the .cookie-banner and .ad-slot inside it
Results results = new AxeSelenium()
    .include("main")
    .exclude(".cookie-banner")
    .exclude(".ad-slot")
    .run(driver);

exclude(List\<String>)

Removes an element inside one or more nested iFrames from the scan. Every string but the last matches one level of iFrame nesting; the last matches the element to skip inside the innermost iFrame. The list describes one path, not several selectors.

Because there is no exclude(String...) overload, passing more than one string to exclude also produces a single iFrame selector rather than separate exclusions: exclude(".iframe1", ".third-party-ad") resolves to exclude(Object...) and means the same thing as the example below.

exclude(FromFrames) expresses the same thing more explicitly and is the recommended form for new tests.

public AxeSelenium exclude(List<String> selector);

Parameters

Returns

This AxeSelenium, for method chaining.

Example

// Skip .third-party-ad inside the iframe matched by .iframe1
Results results = new AxeSelenium()
    .exclude(Arrays.asList(".iframe1", ".third-party-ad"))
    .run(driver);

exclude(FromFrames)

Removes an element inside one or more nested iFrames from the scan, using an explicit FromFrames selector.

public AxeSelenium exclude(FromFrames fromFrames);

Parameters

Returns

This AxeSelenium, for method chaining.

Example

// Skip the form inside the #payment-frame iframe
Results results = new AxeSelenium()
    .exclude(new FromFrames("#payment-frame", "form"))
    .run(driver);

exclude(FromShadowDom)

Removes an element inside one or more nested shadow DOM trees from the scan, using an explicit FromShadowDom selector.

public AxeSelenium exclude(FromShadowDom fromShadowDom);

Parameters

Returns

This AxeSelenium, for method chaining.

Example

// Skip the #search form inside the shadow root attached to .app-header
Results results = new AxeSelenium()
    .exclude(new FromShadowDom(".app-header", "form#search"))
    .run(driver);

exclude(Object)

Removes an area from the scan using a selector supplied as a single object. Java selects this overload only when the argument's static type is not one of the types above, such as a variable declared as Object. Prefer the typed overloads.

public AxeSelenium exclude(Object selector);

Parameters

Returns

This AxeSelenium, for method chaining.

Example

// The selector's type is chosen at runtime, so it's held as Object
Object skip = adInFrame ? new FromFrames("#ad-frame", ".ad") : ".ad";
Results results = new AxeSelenium()
    .exclude(skip)
    .run(driver);

exclude(Object...)

Removes an area from the scan using a selector that mixes plain CSS selectors with FromFrames or FromShadowDom selectors, for cases the other overloads cannot express. All the arguments together form a single path to one element; they are not separate exclusions.

This overload is selected whenever the call passes more than one argument. Passing a single FromFrames or FromShadowDom selects exclude(FromFrames) or exclude(FromShadowDom) instead.

To reach an iFrame that lives inside a shadow root, nest the FromShadowDom selector inside the FromFrames selector. The reverse can't be expressed, because FromShadowDom only accepts strings.

public AxeSelenium exclude(Object... selector);

Parameters

Returns

This AxeSelenium, for method chaining.

Example

// Skip .target inside the shadow root attached to #host, inside the #frame iframe
Results results = new AxeSelenium()
    .exclude("#frame", new FromShadowDom("#host", ".target"))
    .run(driver);

accordingTo(String...)

Runs only the rules that carry at least one of the given tags, such as wcag2a or best-practice. Use it to test against part of a standard, for example only WCAG 2.0 Level A, rather than a whole ruleset.

accordingTo and checkingOnly set the same option, so only the last of the two calls takes effect. A second accordingTo call also replaces the tags from the first, so pass all the tags in one call.

public AxeSelenium accordingTo(String... tags);

Parameters

Returns

This AxeSelenium, for method chaining.

Example

// Run only the WCAG 2.0 Level A and Section 508 rules
Results results = new AxeSelenium()
    .accordingTo("wcag2a", "section508")
    .run(driver);

checkingOnly(String...)

Runs only the named rules and no others. Use it to focus a test on one or two rules, for example while fixing a specific issue.

checkingOnly and accordingTo set the same option, so only the last of the two calls takes effect. A second checkingOnly call also replaces the rules from the first, so pass all the rule IDs in one call.

public AxeSelenium checkingOnly(String... rules);

Parameters

Returns

This AxeSelenium, for method chaining.

Example

// Run only the label and color-contrast rules
Results results = new AxeSelenium()
    .checkingOnly("label", "color-contrast")
    .run(driver);

checking(String...)

Turns on the named rules in addition to the rules already selected by the ruleset or by accordingTo. Use it to add a rule that the selected tags or ruleset leave out, such as a best-practice rule.

checking and skipping set the same option, so only the last of the two calls takes effect, and a second checking call replaces the rules from the first. Pass all the rule IDs in one call, and don't combine checking with skipping in the same scan.

public AxeSelenium checking(String... rules);

Parameters

Returns

This AxeSelenium, for method chaining.

Example

// Run the WCAG 2.0 Level A rules, plus the tabindex best-practice rule
Results results = new AxeSelenium()
    .accordingTo("wcag2a")
    .checking("tabindex")
    .run(driver);

skipping(String...)

Turns off the named rules, leaving the rest of the selected ruleset or tags in place. Use it to turn a rule off entirely; to drop the violation on one element and keep the rule's other results, use ignoring instead.

skipping and checking set the same option, so only the last of the two calls takes effect, and a second skipping call replaces the rules from the first. Pass all the rule IDs in one call, and don't combine skipping with checking in the same scan.

public AxeSelenium skipping(String... rules);

Parameters

Returns

This AxeSelenium, for method chaining.

Example

// Run the default ruleset without the color-contrast and image-alt rules
Results results = new AxeSelenium()
    .skipping("color-contrast", "image-alt")
    .run(driver);

forConfig(URL)

Selects the audit suite (a JSON rule configuration file) to scan with, by URL. This sets the global audit suite on AxeConfiguration, so it also applies to every later AxeSelenium scan, not just this one.

When no audit suite is set, Axe DevTools uses the file named by the AXE_RULESET_PATH environment variable or, if that isn't set, a config/axe-ruleset.json resource on the classpath.

public AxeSelenium forConfig(URL auditConfigPath);

Parameters

Returns

This AxeSelenium, for method chaining.

Example

URL auditSuite = getClass().getResource("/config/my-audit-suite.json");
Results results = new AxeSelenium()
    .forConfig(auditSuite)
    .run(driver);

forConfig(String)

Selects the audit suite to scan with, by its path on the file system. Like forConfig(URL), it sets the global audit suite, so it also applies to later scans.

public AxeSelenium forConfig(String auditConfigPath) throws MalformedURLException;

Parameters

Returns

This AxeSelenium, for method chaining.

Throws

MalformedURLException if the path can't be converted to a URL.

Example

Results results = new AxeSelenium()
    .forConfig("/opt/axe/my-audit-suite.json")
    .run(driver);

AxeSelenium.forRuleset(String)

Selects the ruleset to scan with, such as wcag2.2 or 508, with best-practice rules turned off. The default ruleset is wcag2.1. If an audit suite is also configured, it modifies the selected ruleset.

This sets the global ruleset on AxeConfiguration, so it also applies to every later scan. See AxeConfiguration.forRuleset(String) for the list of ruleset IDs.

public AxeSelenium forRuleset(String rulesetId);

Parameters

Returns

This AxeSelenium, for method chaining.

Example

Results results = new AxeSelenium()
    .forRuleset("wcag2.2")
    .run(driver);

AxeSelenium.forRuleset(String, boolean)

Selects the ruleset to scan with, and whether to also run best-practice rules. Otherwise it behaves like AxeSelenium.forRuleset(String), including setting the ruleset globally.

public AxeSelenium forRuleset(String rulesetId, boolean enableBestPractices);

Parameters

Returns

This AxeSelenium, for method chaining.

Example

// WCAG 2.1 rules plus best-practice rules
Results results = new AxeSelenium()
    .forRuleset("wcag2.1", true)
    .run(driver);

AxeSelenium.ignoring(String, String)

Removes a rule's violations from the results after the scan when that rule fails on a given element. The rule still runs and still reports its passes. One call per rule is enough, because a match removes the rule's whole entry. Don't call it twice for the same rule: if both selectors match failing elements, the scan throws an IllegalStateException.

Filtering works on whole rules: if any element that fails the rule matches the selector, the rule's entire entry is removed from the violations, including failures on other elements. To keep those, narrow the scan with exclude instead.

The selector must match the element's target in the results exactly, written the way Java prints a list: the target selector inside square brackets, such as "[#sidebar]", or "[#frame, .ad]" for an element inside an iFrame. Copy it from a previous scan's results rather than writing it by hand.

public AxeSelenium ignoring(String attestSelector, String ruleId);

Parameters

Returns

This AxeSelenium, for method chaining.

Example

// Ignore the known color-contrast violation on the sidebar
Results results = new AxeSelenium()
    .ignoring("[#sidebar]", "color-contrast")
    .run(driver);

disableIframeTesting()

Stops Axe DevTools from injecting axe-core into iFrames and from collecting results from them, so only the top-level document is tested. Use it when iFrame content is out of your control or when injecting into iFrames causes errors.

public AxeSelenium disableIframeTesting();

Returns

This AxeSelenium, for method chaining.

Example

Results results = new AxeSelenium()
    .disableIframeTesting()
    .run(driver);

setTimeout(int)

Sets how long, in seconds, axe-core may analyze the page before the scan fails with a timeout. The default is 30 seconds. Raise it for very large pages.

public AxeSelenium setTimeout(int timeout);

Parameters

Returns

This AxeSelenium, for method chaining.

Example

Results results = new AxeSelenium()
    .setTimeout(120)
    .run(driver);

logResults(AxeReportingOptions)

Writes a report of this scan when run completes: a .log file listing the violations and a .json file with the full results. The file names and location come from reportingOptions; see AxeReportingOptions. Without this call, no report files are written.

If reportingOptions has no line number set, Axe DevTools records the line of your test that called logResults.

public AxeSelenium logResults(AxeReportingOptions reportingOptions);

Parameters

Returns

This AxeSelenium, for method chaining.

Example

// Writes axe-reports/checkout-page-loaded.log and .json
AxeReportingOptions options = new AxeReportingOptions()
    .testSuiteName("checkout")
    .uiState("page-loaded")
    .outputDirectory("axe-reports");

Results results = new AxeSelenium()
    .logResults(options)
    .run(driver);

loggingConfigured()

Reports whether logResults has been called on this AxeSelenium.

public boolean loggingConfigured();

Returns

true if reporting options have been set.

enableTracking(boolean)

Turns the usage service on or off for this AxeSelenium. The usage service is on by default. When the AXE_TRACK_USAGE environment variable is set, it takes precedence and this method has no effect: true turns the service on and any other value turns it off.

public AxeSelenium enableTracking(boolean state);

Parameters

Returns

This AxeSelenium, for method chaining.

Example

Results results = new AxeSelenium()
    .enableTracking(false)
    .run(driver);

trackingEnabled()

Reports whether this AxeSelenium sends usage data.

public boolean trackingEnabled();

Returns

true if the usage service is on.

setTrackingUrl(String)

Sets the URL that usage data is sent to. The default is the AXE_METRICS_URL environment variable, or https://usage.deque.com when that isn't set. When AXE_METRICS_URL is set, this method has no effect.

public AxeSelenium setTrackingUrl(String url);

Parameters

Returns

This AxeSelenium, for method chaining.

Example

Results results = new AxeSelenium()
    .setTrackingUrl("https://usage.example.com")
    .run(driver);

setDistinctId(String)

Sets the distinct ID sent with usage data, which lets the usage service group the events from one user or machine. The ID is saved to ~/.deque/distinct_id, so later runs on the same machine keep using it. When the ID came from the AXE_DISTINCT_ID environment variable, this method has no effect.

public AxeSelenium setDistinctId(String id);

Parameters

Returns

This AxeSelenium, for method chaining.

Example

Results results = new AxeSelenium()
    .setDistinctId("build-agent-7")
    .run(driver);

setAnalyticsComponentName(String)

Sets the project name sent with usage data. This also resets any earlier setTrackingUrl and enableTracking calls on this AxeSelenium to their defaults, so call it before those methods. A distinct ID set with setDistinctId is kept.

public AxeSelenium setAnalyticsComponentName(String name);

Parameters

Returns

This AxeSelenium, for method chaining.

Example

Results results = new AxeSelenium()
    .setAnalyticsComponentName("storefront-tests")
    .setDistinctId("build-agent-7")
    .run(driver);

com.deque.html.axecore.args.FromFrames

A selector that targets an element inside one or more nested iFrames. Pass it to include or exclude on AxeSelenium.

import com.deque.html.axecore.args.FromFrames;

FromFrames(Object...)

Creates a FromFrames selector from a path through nested iFrames to one element.

public FromFrames(Object... selectors);

Parameters

Example

// The form inside #inner-frame, which is inside #outer-frame
FromFrames checkoutForm = new FromFrames("#outer-frame", "#inner-frame", "form");

// The main element inside an iframe that lives in the shadow root attached to #widget
FromFrames widgetFrame = new FromFrames(new FromShadowDom("#widget", "iframe"), "main");

getFromFrames()

Returns the selectors that make up the path through the nested iFrames.

public List<Object> getFromFrames();

Returns

The selectors, as a List\<Object>.

setFromFrames(Object...)

Replaces the selectors that make up the path through the nested iFrames.

public void setFromFrames(Object... fromFrames);

Parameters

Example

FromFrames selector = new FromFrames("#frame", "form");
selector.setFromFrames("#frame", "nav");

com.deque.html.axecore.args.FromShadowDom

A selector that targets an element inside one or more nested shadow DOM trees. Pass it to include or exclude on AxeSelenium.

import com.deque.html.axecore.args.FromShadowDom;

FromShadowDom(String...)

Creates a FromShadowDom selector from a path through nested shadow roots to one element.

public FromShadowDom(String... selectors);

Parameters

Example

// The button inside the shadow root of .dialog, which is inside the shadow root of app-shell
FromShadowDom closeButton = new FromShadowDom("app-shell", ".dialog", "button.close");

getFromShadowDom()

Returns the selectors that make up the path through the nested shadow roots.

public List<String> getFromShadowDom();

Returns

The selectors, as a List\<String>.

setFromShadowDom(String...)

Replaces the selectors that make up the path through the nested shadow roots.

public void setFromShadowDom(String... fromShadowDom);

Parameters

Example

FromShadowDom selector = new FromShadowDom("app-shell", "nav");
selector.setFromShadowDom("app-shell", "footer");

com.deque.html.axedevtools.selenium.AxeDriver

Wraps a Selenium WebDriver so that Axe DevTools can inject axe-core into the page it controls. Every AxeSelenium scan, and every Hamcrest matcher, takes an AxeDriver. Keep using your WebDriver to navigate and interact with the page.

AxeDriver(WebDriver)

Creates an AxeDriver for a Selenium WebDriver.

public AxeDriver(WebDriver webDriver);

Parameters

Example

WebDriver webDriver = new ChromeDriver();
AxeDriver driver = new AxeDriver(webDriver);

webDriver.get("https://example.com");
Results results = new AxeSelenium().run(driver);

com.deque.html.axedevtools.selenium.AxeConfiguration

Holds settings that apply to every scan in the test run: the axe-core script, the audit suite, the ruleset, and the defaults used in reports. There is one shared instance, which you get with AxeConfiguration.configure(). Set it up once, before any tests run.

Methods on AxeSelenium such as forRuleset and forConfig change this shared instance too.

// Code runs once before any tests are run
public void setupOnce() {
  AxeConfiguration.configure()
    .withAxeScript(axeURL)
    .forAuditSuite(auditURL)
    .forRuleset("508")
    .outputDirectory("my-axe-results");
}

configure()

Returns the shared AxeConfiguration instance. This static method is the only way to get an AxeConfiguration.

public static AxeConfiguration configure();

Returns

The shared AxeConfiguration.

Example

AxeConfiguration config = AxeConfiguration.configure();

reset()

Replaces the shared configuration with a new one that has default settings. Use it between test classes that need different global settings. An AxeConfiguration you obtained before calling reset keeps its old settings, so call configure() again afterward.

public static void reset();

Example

@AfterClass
public static void tearDown() {
    AxeConfiguration.reset();
}

forAuditSuite(URL)

Selects the audit suite (a JSON rule configuration file) for every scan, by URL. When no audit suite is set, Axe DevTools uses the file named by the AXE_RULESET_PATH environment variable or, if that isn't set, a config/axe-ruleset.json resource on the classpath.

public AxeConfiguration forAuditSuite(URL auditConfigPath);

Parameters

Returns

This AxeConfiguration, for method chaining.

Example

AxeConfiguration.configure()
    .forAuditSuite(getClass().getResource("/config/my-audit-suite.json"));

forAuditSuite(String)

Selects the audit suite for every scan, by its path on the file system.

public AxeConfiguration forAuditSuite(String auditConfigPath) throws MalformedURLException;

Parameters

Returns

This AxeConfiguration, for method chaining.

Throws

MalformedURLException if the path can't be converted to a URL.

Example

AxeConfiguration.configure()
    .forAuditSuite("/opt/axe/my-audit-suite.json");

withAxeScript(URL)

Selects the axe-core script to inject into the page, instead of the one bundled with Axe DevTools. Use it to pin a specific axe-core build.

public AxeConfiguration withAxeScript(URL axeScript);

Parameters

Returns

This AxeConfiguration, for method chaining.

Example

AxeConfiguration.configure()
    .withAxeScript(getClass().getResource("/axe.min.js"));

AxeConfiguration.forRuleset(String)

Selects the ruleset for every scan, with best-practice rules turned off. The default ruleset is wcag2.1.

public AxeConfiguration forRuleset(String rulesetId);

Parameters

The ruleset IDs are:

• wcag2
• wcag2.1
• wcag2.2
• wcag2aaa
• wcag2.1aaa
• wcag2.2aaa
• 508
• ttv5
• en301549
• rgaav4

Returns

This AxeConfiguration, for method chaining.

Example

AxeConfiguration.configure().forRuleset("wcag2.2");

AxeConfiguration.forRuleset(String, boolean)

Selects the ruleset for every scan, and whether to also run best-practice rules.

public AxeConfiguration forRuleset(String rulesetId, boolean enableBestPractices);

Parameters

Returns

This AxeConfiguration, for method chaining.

Example

AxeConfiguration.configure().forRuleset("508", true);

getTestSuiteName()

Returns the default test suite name used in reports. The default is axe-run.

public String getTestSuiteName();

AxeConfiguration.testSuiteName(String)

Sets the default test suite name used in report file names and report contents. An AxeReportingOptions.testSuiteName(String) value overrides it for one report.

public AxeConfiguration testSuiteName(String testSuiteName);

Parameters

Returns

This AxeConfiguration, for method chaining.

Example

AxeConfiguration.configure().testSuiteName("storefront");

AxeConfiguration.getOutputDirectory()

Returns the default directory that reports are written to. The default is axe-reports.

public String getOutputDirectory();

AxeConfiguration.outputDirectory(String)

Sets the default directory that reports are written to. Missing directories are created when a report is written. An AxeReportingOptions.outputDirectory(String) value overrides it for one report.

public AxeConfiguration outputDirectory(String outputDirectory);

Parameters

Returns

This AxeConfiguration, for method chaining.

Example

AxeConfiguration.configure().outputDirectory("target/axe-reports");

AxeConfiguration.getUserAgent()

Returns the default user agent recorded in reports, or null if none is set.

public String getUserAgent();

AxeConfiguration.userAgent(String)

Sets the default user agent recorded in reports. It's a label only, and doesn't change the user agent the browser sends. An AxeReportingOptions.userAgent(String) value overrides it for one report.

public AxeConfiguration userAgent(String userAgent);

Parameters

Returns

This AxeConfiguration, for method chaining.

Example

AxeConfiguration.configure().userAgent("Chrome 130 headless");

AxeConfiguration.getTestMachine()

Returns the default test machine name recorded in reports, or null if none is set.

public String getTestMachine();

AxeConfiguration.testMachine(String)

Sets the default test machine name recorded in reports. An AxeReportingOptions.testMachine(String) value overrides it for one report.

public AxeConfiguration testMachine(String testMachine);

Parameters

Returns

This AxeConfiguration, for method chaining.

Example

AxeConfiguration.configure().testMachine(System.getenv("HOSTNAME"));

com.deque.html.axedevtools.selenium.reporter.AxeReportingOptions

Describes one report: where to write it, and the test suite, UI state, user agent, test machine, and line number to record in it. Pass it to logResults. It implements ReportingOptions.

Any value you don't set falls back to the matching AxeConfiguration setting. The report files are named <test suite name>-<UI state>.log and .json, so give each check in a test suite its own UI state, or the later report overwrites the earlier one.

AxeReportingOptions()

Creates an AxeReportingOptions with no values set, so every value comes from AxeConfiguration until you set it. The UI state has no default and must be set before a report is written.

public AxeReportingOptions();

Example

AxeReportingOptions options = new AxeReportingOptions()
    .uiState("home-page");

defaultAuditReportingOptions()

Returns new options with the output directory target/axe-report, test suite name accessibility, and UI state check, so the report is written to target/axe-report/accessibility-check.log and .json. These are the options the Hamcrest isAuditedForAccessibility() matcher uses when you don't call logResults.

public static AxeReportingOptions defaultAuditReportingOptions();

Returns

A new AxeReportingOptions.

Example

Results results = new AxeSelenium()
    .logResults(AxeReportingOptions.defaultAuditReportingOptions())
    .run(driver);

getSuiteTestName()

Returns the test suite name for this report, or the AxeConfiguration default if none is set.

public String getSuiteTestName();

AxeReportingOptions.testSuiteName(String)

Sets the test suite name for this report. It's the first part of the report file names.

public AxeReportingOptions testSuiteName(String testSuiteName);

Parameters

Returns

This AxeReportingOptions, for method chaining.

Example

AxeReportingOptions options = new AxeReportingOptions()
    .testSuiteName("checkout")
    .uiState("payment-step");

getUiState()

Returns the UI state for this report.

public String getUiState();

Throws

MissingUIStateException if no UI state has been set.

uiState(String)

Sets the UI state for this report: a short name for what the page looked like when it was checked, such as menu-open or form-errors. It's the second part of the report file names, and it's required: writing a report without it throws MissingUIStateException.

public AxeReportingOptions uiState(String uiState);

Parameters

Returns

This AxeReportingOptions, for method chaining.

Example

webDriver.findElement(By.id("menu-button")).click();

Results results = new AxeSelenium()
    .logResults(new AxeReportingOptions().uiState("menu-open"))
    .run(driver);

AxeReportingOptions.getOutputDirectory()

Returns the directory this report is written to, or the AxeConfiguration default if none is set.

public String getOutputDirectory();

AxeReportingOptions.outputDirectory(String)

Sets the directory this report is written to. Missing directories are created when the report is written.

public AxeReportingOptions outputDirectory(String outputDirectory);

Parameters

Returns

This AxeReportingOptions, for method chaining.

Example

AxeReportingOptions options = new AxeReportingOptions()
    .outputDirectory("target/axe-reports/checkout")
    .uiState("cart");

getFileName()

Returns the report file name without an extension: the test suite name and UI state joined by a hyphen, followed by a timestamp if useUniqueFilename is on.

public String getFileName();

getFilePath(String)

Returns the full path of a report file: the output directory, a /, the file name, and extension.

public String getFilePath(String extension);

Parameters

Returns

The file path.

Example

AxeReportingOptions options = new AxeReportingOptions()
    .testSuiteName("checkout")
    .uiState("cart")
    .outputDirectory("axe-reports");

String jsonPath = options.getFilePath(".json"); // axe-reports/checkout-cart.json

useUniqueFilename(boolean)

Adds a UTC timestamp to the report file names, so that running the same check again writes new files instead of overwriting the previous report.

This method returns the ReportingOptions interface rather than AxeReportingOptions, so call it as a separate statement, as in the example, rather than in a chain you assign to an AxeReportingOptions or pass to logResults. The .log and .json file names are built separately, so their timestamps can differ slightly.

public ReportingOptions useUniqueFilename(boolean uniqueFilename);

Parameters

Returns

This object, typed as ReportingOptions.

Example

AxeReportingOptions options = new AxeReportingOptions()
    .testSuiteName("nightly")
    .uiState("home");
options.useUniqueFilename(true);

AxeReportingOptions.getUserAgent()

Returns the user agent recorded in this report, or the AxeConfiguration default if none is set.

public String getUserAgent();

AxeReportingOptions.userAgent(String)

Sets the user agent recorded in this report. It's a label only, and doesn't change the user agent the browser sends.

public AxeReportingOptions userAgent(String userAgent);

Parameters

Returns

This AxeReportingOptions, for method chaining.

Example

String userAgent = (String) ((JavascriptExecutor) webDriver).executeScript("return navigator.userAgent");
AxeReportingOptions options = new AxeReportingOptions()
    .userAgent(userAgent)
    .uiState("home");

AxeReportingOptions.getTestMachine()

Returns the test machine name recorded in this report, or the AxeConfiguration default if none is set.

public String getTestMachine();

AxeReportingOptions.testMachine(String)

Sets the test machine name recorded in this report.

public AxeReportingOptions testMachine(String testMachine);

Parameters

Returns

This AxeReportingOptions, for method chaining.

Example

AxeReportingOptions options = new AxeReportingOptions()
    .testMachine("ci-linux-04")
    .uiState("home");

getLineNum()

Returns the test line number recorded in this report, or null if none is set.

public String getLineNum();

lineNum(String)

Sets the test line number recorded in this report, replacing any value already set. You rarely need it: logResults records the calling line automatically when no line number is set.

public AxeReportingOptions lineNum(String lineNum);

Parameters

Returns

This AxeReportingOptions, for method chaining.

Example

AxeReportingOptions options = new AxeReportingOptions()
    .lineNum("42")
    .uiState("home");

lineNumIfEmpty(String)

Sets the test line number only if none is set yet. logResults uses it to record the calling line without overwriting a value you set with lineNum.

This method returns the ReportingOptions interface rather than AxeReportingOptions, so call it as a separate statement rather than in a chain you assign to an AxeReportingOptions or pass to logResults.

public ReportingOptions lineNumIfEmpty(String lineNum);

Parameters

Returns

This object, typed as ReportingOptions.

com.deque.html.axedevtools.selenium.reporter.MissingUIStateException

A RuntimeException thrown when a report is written with reporting options that have no UI state, with the message "Please provide the UI State of the current page under test". To avoid it, call uiState on every AxeReportingOptions you pass to logResults.

com.deque.html.axedevtools.selenium.results.ResultsFilter

Holds the element and rule pairs to drop from results. Each AxeSelenium creates its own ResultsFilter, which you add to with AxeSelenium.ignoring(String, String) rather than creating one yourself. You can also use a ResultsFilter directly to filter a Results object you already have.

filterIgnoredViolations(Results)

Removes the ignored violations from results. A rule's entire entry is removed from the violations when the rule ID matches and any of its nodes has a target equal to an ignored selector, even if other nodes don't match. The Results object you pass in is modified and returned.

public Results filterIgnoredViolations(Results results);

Parameters

Returns

The same Results object, with the ignored violations removed.

Example

Results results = new AxeSelenium().run(driver);

new ResultsFilter()
    .ignoring("[#legacy-widget]", "aria-allowed-attr")
    .filterIgnoredViolations(results);

ResultsFilter.ignoring(String, String)

Adds an element and rule pair to ignore. The selector must match a node's target exactly, in the form "[#sidebar]"; see AxeSelenium.ignoring(String, String).

public ResultsFilter ignoring(String cssSelector, String ruleId);

Parameters

Returns

This ResultsFilter, for method chaining.

Example

ResultsFilter filter = new ResultsFilter()
    .ignoring("[#sidebar]", "color-contrast")
    .ignoring("[.third-party-iframe]", "frame-title");

com.deque.html.axedevtools.reporter.AxeDevtoolsReporter

Writes the .log and .json report files for a scan. AxeSelenium and the Hamcrest matchers use it for you when you call logResults; use it directly only to report on Results you already have.

AxeDevtoolsReporter()

Creates an AxeDevtoolsReporter.

public AxeDevtoolsReporter();

Example

AxeDevtoolsReporter reporter = new AxeDevtoolsReporter();

generateReport(Results, String)

Returns a plain-text summary of the violations in results: each rule's help text and URL, each affected node's target, and the checks to fix, followed by the command that produced the results. This is the text written to the .log file, and the text the Hamcrest isAxeClean() matcher shows when an assertion fails.

public String generateReport(Results results, String executedCommand);

Parameters

Returns

The report text.

Example

AxeSelenium axe = new AxeSelenium();
Results results = axe.run(driver);

String report = new AxeDevtoolsReporter().generateReport(results, axe.runCommand());
System.out.println(report);

report(ReportingOptions, Results, String)

Writes the report for results to two files at the path given by reportingOptions: a .log file with the generateReport text and a .json file with the full results. If reportingOptions is null, nothing is written.

public void report(ReportingOptions reportingOptions, Results results, String executedCommand);

Parameters

Throws

MissingUIStateException if reportingOptions has no UI state, or a RuntimeException if the files can't be written.

Example

AxeSelenium axe = new AxeSelenium();
Results results = axe.run(driver);

new AxeDevtoolsReporter().report(
    new AxeReportingOptions().uiState("after-login"),
    results,
    axe.runCommand());

com.deque.html.axedevtools.utils.FileUtils

File helpers that Axe DevTools uses internally to read and write report files. It isn't intended for use in your tests.