API Reference for Hamcrest

Reference for types provided by the hamcrest package.

The IsAccessible and IsAuditedForAccessibility classes provide primary functionality. You get an instance of either one from its static factory method, isAxeClean() or isAuditedForAccessibility(), and then chain the AxeDevtoolsMatcher methods onto it to configure the check.

The examples on this page assume webDriver is your Selenium WebDriver, driver is an AxeDriver wrapping it, and these static imports. The selector classes come from com.deque.html.axedevtools.matchers.selectors, and AxeReportingOptions from com.deque.html.axedevtools.selenium.reporter.

import static org.hamcrest.MatcherAssert.assertThat;
import static com.deque.html.axedevtools.matchers.IsAccessible.isAxeClean;
import static com.deque.html.axedevtools.matchers.IsAuditedForAccessibility.isAuditedForAccessibility;

com.deque.html.axedevtools.matchers.AxeDevtoolsMatcher

The base class of the Axe DevTools matchers. It extends Hamcrest's TypeSafeMatcher<AxeDriver>, so it matches against an AxeDriver. You don't create one directly: use IsAccessible or IsAuditedForAccessibility, which inherit every method below.

Each configuration method returns the same matcher, so calls can be chained. The scan itself runs when assertThat evaluates the matcher. Behind the scenes, each matcher runs an AxeSelenium scan, so the rules described there for combining options apply here too.

within(String...)

Limits the scan to the elements matched by the given CSS selectors, and their descendants. Each selector adds a separate area to the scan, so within("#header", "#footer") tests both, the same as calling within once for each. This differs from AxeSelenium.include(Object...), where several arguments form one path.

public AxeDevtoolsMatcher within(String... cssSelectors);

Parameters

Returns

This matcher, for method chaining.

Example

assertThat(driver, isAxeClean().within("#header", "#footer"));

within(Selector...)

Limits the scan to the areas described by Selector objects. Use it with IFrameSelector to test an element inside an iFrame. Each selector adds a separate area to the scan.

public AxeDevtoolsMatcher within(Selector... selectors);

Parameters

Returns

This matcher, for method chaining.

Example

// Test the form inside the #payment-frame iframe
assertThat(driver, isAxeClean().within(new IFrameSelector("#payment-frame", "form")));

within(Object...)

Limits the scan to areas described by other selector objects, most usefully FromFrames and FromShadowDom. Use it to test an element inside a shadow DOM tree, which Selector objects can't express. Each argument adds a separate area to the scan.

public AxeDevtoolsMatcher within(Object... selectors);

Parameters

Returns

This matcher, for method chaining.

Example

// Test the #search form inside the shadow root attached to .app-header
assertThat(driver, isAxeClean().within(new FromShadowDom(".app-header", "form#search")));

excluding(String...)

Removes the elements matched by the given CSS selectors, and their descendants, from the scan. Each selector removes a separate area. Exclusions apply on top of any within calls, which lets you test a region except for part of it.

public AxeDevtoolsMatcher excluding(String... cssSelectors);

Parameters

Returns

This matcher, for method chaining.

Example

// Test main, but skip the .cookie-banner and .ad-slot inside it
assertThat(driver, isAxeClean().within("main").excluding(".cookie-banner", ".ad-slot"));

excluding(Selector...)

Removes the areas described by Selector objects from the scan, such as an element inside an iFrame. Each selector removes a separate area.

public AxeDevtoolsMatcher excluding(Selector... selectors);

Parameters

Returns

This matcher, for method chaining.

Example

// Skip the third-party ad inside the #ad-frame iframe
assertThat(driver, isAxeClean().excluding(new IFrameSelector("#ad-frame", ".ad")));

excluding(Object...)

Removes areas described by other selector objects, most usefully FromFrames and FromShadowDom, from the scan. Each argument removes a separate area.

public AxeDevtoolsMatcher excluding(Object... selectors);

Parameters

Returns

This matcher, for method chaining.

Example

// Skip the chat widget inside the shadow root attached to support-chat
assertThat(driver, isAxeClean().excluding(new FromShadowDom("support-chat", ".widget")));

accordingTo(String...)

Runs only the rules that carry at least one of the given tags, such as wcag2a or best-practice.

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 AxeDevtoolsMatcher accordingTo(String... tags);

Parameters

Returns

This matcher, for method chaining.

Example

assertThat(driver, isAxeClean().accordingTo("wcag2a", "wcag2aa"));

checkingOnly(String...)

Runs only the named rules and no others.

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 AxeDevtoolsMatcher checkingOnly(String... rules);

Parameters

Returns

This matcher, for method chaining.

Example

assertThat(driver, isAxeClean().checkingOnly("label", "color-contrast"));

checking(String...)

Turns on the named rules in addition to the rules already selected by the ruleset or by accordingTo.

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 check.

public AxeDevtoolsMatcher checking(String... rules);

Parameters

Returns

This matcher, for method chaining.

Example

// WCAG 2.0 Level A rules, plus the tabindex best-practice rule
assertThat(driver, isAxeClean().accordingTo("wcag2a").checking("tabindex"));

skipping(String...)

Turns off the named rules, leaving the rest of the selected ruleset or tags in place.

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 check.

public AxeDevtoolsMatcher skipping(String... rules);

Parameters

Returns

This matcher, for method chaining.

Example

assertThat(driver, isAxeClean().skipping("color-contrast", "image-alt"));

ignoring(String, String)

Removes a rule's violations from the results when that rule fails on a given element, so they don't fail the assertion. The selector must match the element's target in the results exactly, in the form "[#sidebar]".

Filtering works on whole rules: if any element that fails the rule matches the selector, the rule's entire entry is removed, including failures on other elements. One call per rule is enough; two calls for the same rule that both match throw an IllegalStateException. See AxeSelenium.ignoring(String, String) for details.

public AxeDevtoolsMatcher ignoring(String selector, String ruleId);

Parameters

Returns

This matcher, for method chaining.

Example

assertThat(driver, isAxeClean().ignoring("[#sidebar]", "color-contrast"));

forConfig(URL)

Selects the audit suite (a JSON rule configuration file) to check with, by URL. Like AxeSelenium.forConfig(URL), this sets the global audit suite, so it also applies to later checks.

public AxeDevtoolsMatcher forConfig(URL auditPath);

Parameters

Returns

This matcher, for method chaining.

Example

URL auditSuite = getClass().getResource("/config/my-audit-suite.json");
assertThat(driver, isAxeClean().forConfig(auditSuite));

forConfig(String)

Selects the audit suite to check with, by its path on the file system. Like forConfig(URL), it sets the global audit suite.

public AxeDevtoolsMatcher forConfig(String auditPath) throws MalformedURLException;

Parameters

Returns

This matcher, for method chaining.

Throws

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

Example

@Test
public void matchesAuditSuite() throws MalformedURLException {
    assertThat(driver, isAxeClean().forConfig("/opt/axe/my-audit-suite.json"));
}

forRuleset(String)

Selects the ruleset to check with, such as wcag2.2 or 508, with best-practice rules turned off. Passing null selects the default, wcag2.1. Like AxeSelenium.forRuleset(String), this sets the global ruleset, so it also applies to later checks. See AxeConfiguration.forRuleset(String) for the ruleset IDs.

The matchers have no way to turn on best-practice rules along with a ruleset. To do that, call AxeConfiguration.configure().forRuleset(rulesetId, true) before the check, and don't also call the matcher's forRuleset, which turns best-practice rules back off.

public AxeDevtoolsMatcher forRuleset(String rulesetId);

Parameters

Returns

This matcher, for method chaining.

Example

assertThat(driver, isAxeClean().forRuleset("wcag2.2"));

logResults(AxeReportingOptions)

Writes a report of this check: a .log file listing the violations and a .json file with the full results. The file names and location come from reportingOptions; see AxeReportingOptions. With isAxeClean(), no report is written unless you call logResults.

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

public AxeDevtoolsMatcher logResults(AxeReportingOptions reportingOptions);

Parameters

Returns

This matcher, for method chaining.

Example

AxeReportingOptions options = new AxeReportingOptions()
    .testSuiteName("checkout")
    .uiState("page-loaded");

assertThat(driver, isAxeClean().logResults(options));

setReportingOptions(AxeReportingOptions)

Replaces the reporting options that isAuditedForAccessibility() uses when you don't call logResults. It has no effect on isAxeClean(), which only writes a report through logResults. The options you pass replace the defaults entirely: any value you don't set falls back to AxeConfiguration (reports go to axe-reports unless you set outputDirectory), and you must set uiState.

public AxeDevtoolsMatcher setReportingOptions(AxeReportingOptions reportingOptions);

Parameters

Returns

This matcher, for method chaining.

Example

assertThat(driver, isAuditedForAccessibility()
    .setReportingOptions(new AxeReportingOptions().testSuiteName("nightly").uiState("home")));

setTimeout(int)

Sets how long, in seconds, axe-core may analyze the page before the check fails with a timeout. The default is 30 seconds.

public AxeDevtoolsMatcher setTimeout(int timeout);

Parameters

Returns

This matcher, for method chaining.

Example

assertThat(driver, isAxeClean().setTimeout(120));

enableAnalytics(boolean)

Turns the usage service on or off for this check. 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 AxeDevtoolsMatcher enableAnalytics(boolean state);

Parameters

Returns

This matcher, for method chaining.

Example

assertThat(driver, isAxeClean().enableAnalytics(false));

trackingEnabled()

Reports whether this check sends usage data.

public boolean trackingEnabled();

Returns

true if the usage service is on.

setAnalyticsUrl(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 AxeDevtoolsMatcher setAnalyticsUrl(String url);

Parameters

Returns

This matcher, for method chaining.

Example

assertThat(driver, isAxeClean().setAnalyticsUrl("https://usage.example.com"));

setAnalyticsDisinctId(String)

Sets the distinct ID sent with usage data. The method name is spelled Disinct in the API, so type it exactly as shown. 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 AxeDevtoolsMatcher setAnalyticsDisinctId(String id);

Parameters

Returns

This matcher, for method chaining.

Example

assertThat(driver, isAxeClean().setAnalyticsDisinctId("build-agent-7"));

setAnalyticsComponentName(String)

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

public AxeDevtoolsMatcher setAnalyticsComponentName(String name);

Parameters

Returns

This matcher, for method chaining.

Example

assertThat(driver, isAxeClean()
    .setAnalyticsComponentName("storefront-tests")
    .setAnalyticsDisinctId("build-agent-7"));

com.deque.html.axedevtools.matchers.IsAccessible

A matcher that fails the assertion when the page has accessibility violations. It extends AxeDevtoolsMatcher, so every method above can be chained onto it to set the scope, rules, audit suite, and reporting.

When the assertion fails, the failure message lists each violation, the affected elements, and how to fix them, in the same format as the .log report. If axe-core returns an error instead of results, the check throws an AxeRuntimeException rather than failing the assertion.

assertThat(driver, isAxeClean()
    .within("#header")
    .within("#footer")
    .excluding(".graphics")
    .accordingTo("wcag2a", "wcag2aa"));

isAxeClean()

Creates an IsAccessible matcher. This static method is the only way to get one. With no further configuration, it checks the whole page against the global ruleset, which defaults to wcag2.1, and writes no report.

public static IsAccessible isAxeClean();

Returns

A new IsAccessible matcher.

Example

@Test
public void homePageIsAccessible() {
    webDriver.get("https://example.com");
    assertThat(driver, isAxeClean());
}

com.deque.html.axedevtools.matchers.IsAuditedForAccessibility

A matcher that scans the page and writes a report, but never fails the assertion because of violations. An axe-core error still throws an AxeRuntimeException, as with isAxeClean(). Use it to collect results for monitoring without breaking the build; you'll need to track regressions from the reports, outside of test passes and failures. It extends AxeDevtoolsMatcher, so every method above can be chained onto it.

Unless you call logResults, the report is written to target/axe-report/accessibility-check.log and target/axe-report/accessibility-check.json. Use setReportingOptions to change those defaults. Each check overwrites the previous report at the same path, so give each check its own test suite name or UI state through setReportingOptions or logResults, or turn on useUniqueFilename.

assertThat(driver, isAuditedForAccessibility()
    .within("#header")
    .within("#footer")
    .excluding(".graphics")
    .accordingTo("wcag2a", "wcag2aa"));

isAuditedForAccessibility()

Creates an IsAuditedForAccessibility matcher. This static method is the only way to get one.

public static IsAuditedForAccessibility isAuditedForAccessibility();

Returns

A new IsAuditedForAccessibility matcher.

Example

@Test
public void auditCheckoutPage() {
    webDriver.get("https://example.com/checkout");
    assertThat(driver, isAuditedForAccessibility()
        .logResults(new AxeReportingOptions().testSuiteName("checkout").uiState("loaded")));
}

com.deque.html.axedevtools.matchers.selectors.Selector

The interface implemented by ElementSelector and IFrameSelector. Pass selectors to within(Selector...) or excluding(Selector...).

toList()

Returns the selector as a list of CSS selectors: one per iFrame level, followed by the selector for the element. Both implementations provide it. The matchers call it for you; you don't need to call it in tests.

List<String> toList();

Returns

The CSS selectors, as a List\<String>.

com.deque.html.axedevtools.matchers.selectors.ElementSelector

A Selector for an element in the current document. On its own it's equivalent to passing the CSS selector string to within or excluding; its main use is as the innermost part of an IFrameSelector.

ElementSelector(String)

Creates a selector for the elements matched by a CSS selector.

public ElementSelector(String cssSelector);

Parameters

Example

// The form inside #inner-frame, which is inside #outer-frame
Selector form = new IFrameSelector("#outer-frame",
    new IFrameSelector("#inner-frame", new ElementSelector("form")));

com.deque.html.axedevtools.matchers.selectors.IFrameSelector

A Selector for an element inside an iFrame. Nest one IFrameSelector inside another to reach an element inside nested iFrames.

IFrameSelector(String, String)

Creates a selector for an element inside one iFrame.

public IFrameSelector(String frameSelector, String cssSelector);

Parameters

Example

assertThat(driver, isAxeClean().within(new IFrameSelector("#payment-frame", "form")));

IFrameSelector(String, Selector)

Creates a selector for an element inside an iFrame, where the element is described by another Selector. Pass another IFrameSelector to go one iFrame deeper, or an ElementSelector.

public IFrameSelector(String frameSelector, Selector selector);

Parameters

Example

// The form inside #inner-frame, which is inside #outer-frame
assertThat(driver, isAxeClean().within(
    new IFrameSelector("#outer-frame", new IFrameSelector("#inner-frame", "form"))));