API Reference for Java Playwright

This page is not available in the language you requested. You have been redirected to the English version of the page.

Link to this page copied to clipboard

API reference for the AxePlaywrightBuilder class in the Axe DevTools for Web Java Playwright integration

Not for use with personal data

This document provides an API reference to the AxePlaywrightBuilder Java class, which is provided by the Playwright Java integration.

note

Most methods in the AxePlaywrightBuilder class return an AxePlaywrightBuilder object, which allows you to easily chain several methods together. See the code samples below for examples of chaining methods.

Constructors

Constructor	Description
AxePlaywrightBuilder(Page)	Standard constructor that creates an `AxePlaywrightBuilder` object.
AxePlaywrightBuilder(Page, File)	Create an `AxePlaywrightBuilder` object and specify a JSON file containing custom rules to be used during analysis.
AxePlaywrightBuilder(Page, String)	Create an `AxePlaywrightBuilder` object while specifying a JSON `String` containing custom rules.

AxePlaywrightBuilder(Page)

Initializes a new instance of the AxePlaywrightBuilder class for the specified Page object.

public AxePlaywrightBuilder(Page page);

Parameters

Name	Type	Description
page	`com.microsoft.Playwright.Page`	The Page object to be used for accessibility analysis.

Example

The following code example demonstrates this constructor. It also shows how to create a Page object and an AxePlaywrightBuilder object with that Page object.

// Example Page
Page page = browser.newPage();

AxePlaywrightBuilder axePlaywrightBuilder = new AxePlaywrightBuilder(page);

AxePlaywrightBuilder(Page, File)

Initializes a new instance of AxePlaywrightBuilder class with the specified Page object and specified File object. The File contains custom rules in a JSON file.

public AxePlaywrightBuilder(Page page, File rules);

Parameters

Name	Type	Description
page	`com.microsoft.Playwright.Page`	The required Page object.
rules	`File`	A File object representing a JSON file of custom accessibility rules.

Example

The following example shows how to use this constructor.

// Example Page
Page page = browser.newPage();

File customRuleset = new File("somePath/custom-ruleset.json")
AxePlaywrightBuilder axePlaywrightBuilder = new AxePlaywrightBuilder(page, customRuleset);

AxePlaywrightBuilder(Page, String)

Initializes a new instance of AxePlaywrightBuilder class with the specified Page object and specified String object, which contains custom rules in a JSON string.

public AxePlaywrightBuilder(Page page, String rules);

Parameters

Name	Type	Description
page	`com.microsoft.Playwright.Page`	The required `Page` object
rules	`String`	A JSON string representing a set of custom accessibility rules.

Example

The following code example demonstrates this constructor.

// Example Page
Page page = browser.newPage();

String customRuleset = "{...}"
AxePlaywrightBuilder axePlaywrightBuilder = new AxePlaywrightBuilder(page, customRuleset);

Methods

Method	Description
analyze	Analyze the Playwright page and return an `AxeResults` object from the completed analysis.
configure(File)	Provide a custom configuration on how axe-core is run via a JSON file.

configure(String)	Provide a custom configuration on how axe-core is run via a JSON string.
disableRules	Prevents the specified rules from being run during analysis.
exclude(String)	Specifies a single CSS selector to exclude certain HTML content during analysis.
exclude(List<String>)	Specifies a CSS iframe selector to be used to exclude certain HTML content during analysis.
exclude(FromFrames)	Excludes an element inside one or more nested iframes.
exclude(FromShadowDom)	Excludes an element inside one or more nested shadow DOM trees.
exclude(Object)	Excludes a selector supplied as a single object.
exclude(Object...)	Excludes a selector that combines CSS selectors, frame context, and shadow DOM context.
include(String)	Specifies a single CSS selector that includes HTML content during analysis.
include(List<String>)	Specifies a CSS iframe selector that includes HTML content during analysis.
include(FromFrames)	Includes an element inside one or more nested iframes.
include(FromShadowDom)	Includes an element inside one or more nested shadow DOM trees.
include(Object)	Includes a selector supplied as a single object.
include(Object...)	Includes a selector that combines CSS selectors, frame context, and shadow DOM context.
setLegacyMode	Set legacy mode to exclude accessibility issues that may occur in cross-domain frames and iframes.
withAxeSource(File)	Provide a custom version of axe-core using a `File` object.
withAxeSource(String)	Provide a custom version of axe-core by using a `String` object.
withOnlyBestPracticeRules	Checks accessibility using only the best-practice rules.
withOnlyExperimentalRules	Checks accessibility using only the experimental rules.
withRules	Limit the accessibility rules to the ones specified.
withTags	Limit the accessibility rules checked to the specified list of tags.

analyze

Analyze the Playwright Page (specified when the AxePlaywrightBuilder object was created) and return an AxeResults object from the completed analysis.

AxeResults AxePlaywrightBuilder.analyze();

Returns

AxeResults

Example

The following code example demonstrates how to use the analyze method.


AxePlaywrightBuilder axePlaywrightBuilder = new AxePlaywrightBuilder(page);

AxeResults axeResults = axePlaywrightBuilder.analyze();

/* Usage may include:
axeResults.getViolations() - returns only violation results
axeResults.getPasses() - returns only pass results
axeResults.getIncomplete() - returns only incomplete results
*/

configure(File)

Provide a custom configuration to axe-core via a JSON file.

public AxePlaywrightBuilder configure(File axeConfigure);

For more information about the format of the configuration file, see axe-core configuration.

Parameters

Name	Type	Description
file	`File`	A `File` object representing an axe-core configuration in JSON.

Example

The following example shows how to access a configuration and use it with an AxePlaywrightBuilder object.

File myAxeConfigure = new File("./axe-configure.json");

AxePlaywrightBuilder axePlaywrightBuilder = new AxePlaywrightBuilder(page)
        .configure(myAxeConfigure);

configure(String)

Provide a custom configuration to axe-core (the underlying technology for analyzing accessibility) is run via a JSON string.

public AxePlaywrightBuilder configure(String axeConfigure);

For more information about the format of the configuration file, see axe-core configuration.

Parameters

Name	Type	Description
axeConfig	`String`	A `String` object representing an axe-core configuration in JSON.

Example

The following example shows how to access a configuration and use it with an AxePlaywrightBuilder object.

String myAxeConfigure = "{..}"

AxePlaywrightBuilder axePlaywrightBuilder = new AxePlaywrightBuilder(page)
        .configure(myAxeConfigure);

disableRules

Disable rules from being executed during analysis.

public AxePlaywrightBuilder disableRules(List<String> rules);

Parameters

Name	Type	Description
rules	List<String>	A list of strings representing rules to disable during analysis.

Returns

AxePlaywrightBuilder

Example

The following example shows how to disable accessibility checking for a single rule using the singletonList method of the Collections class and multiple rules using a List.

// Single Rule
AxePlaywrightBuilder axePlaywrightBuilder1 = new AxePlaywrightBuilder(page)
        .disableRules(Collections.singletonList("color-contrast"));

// Multiple Rules
AxePlaywrightBuilder axePlaywrightBuilder2 = new AxePlaywrightBuilder(page)
        .disableRules(Arrays.asList("color-contrast", "image-alt"));

exclude(String)

Specify a single CSS selector to exclude HTML elements during analysis. To skip several unrelated parts of the page, call exclude once for each one, passing a single selector each time.

public AxePlaywrightBuilder exclude(String selector);

Parameters

Name	Type	Description
selector	`String`	A CSS selector specifying elements that won't be included in an accessibility analysis.

Returns

AxePlaywrightBuilder

Examples

The following example shows how to exclude elements from analysis with these attributes:

class="some-class"
class="some-other-class"

new AxePlaywrightBuilder(page)
        .exclude(".some-class")
        .exclude(".some-other-class");

exclude(List<String>)

Specify a CSS iframe selector to exclude HTML elements during analysis.

public AxePlaywrightBuilder exclude(List<String> excludeCSS);

Parameters

Name	Type	Description
excludeCSS	`List<String>`	A CSS iframe selector. Every selector but the last matches one level of iframe nesting; the last matches the element to skip inside the innermost iframe.

Returns

AxePlaywrightBuilder

Examples

The following example shows how to exclude elements using CSS iframe selectors.

// To exclude everything within html of parent-iframe
new AxePlaywrightBuilder(page)
        .exclude(Arrays.asList("#parent-iframe", "#html"))

Because there is no exclude(String...) overload, passing more than one string to exclude also produces a single iframe selector rather than separate exclusions. The following call resolves to exclude(Object...) and means the same thing as the example above.

new AxePlaywrightBuilder(page)
        .exclude("#parent-iframe", "#html")

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

exclude(FromFrames)

Exclude an element inside one or more nested iframes, using an explicit FromFrames selector.

public AxePlaywrightBuilder exclude(FromFrames fromFrames);

Import the class with import com.deque.html.axecore.args.FromFrames;.

Parameters

Name	Type	Description
fromFrames	`FromFrames`	A selector built from one CSS selector per level of iframe nesting, followed by a selector for the element to skip inside the innermost iframe.

Returns

AxePlaywrightBuilder

Examples

The following example skips the form inside the #payment-frame iframe.

new AxePlaywrightBuilder(page)
        .exclude(new FromFrames("#payment-frame", "form"))

exclude(FromShadowDom)

Exclude an element inside one or more nested shadow DOM trees, using an explicit FromShadowDom selector.

public AxePlaywrightBuilder exclude(FromShadowDom fromShadowDom);

Import the class with import com.deque.html.axecore.args.FromShadowDom;.

Parameters

Name	Type	Description
fromShadowDom	`FromShadowDom`	A selector built from one CSS selector per shadow host, followed by a selector for the element to skip inside the innermost shadow root.

Returns

AxePlaywrightBuilder

Examples

The following example skips the #search form inside the shadow root attached to .app-header.

new AxePlaywrightBuilder(page)
        .exclude(new FromShadowDom(".app-header", "form#search"))

exclude(Object)

Exclude a selector supplied as a single object. This overload is selected 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 AxePlaywrightBuilder exclude(Object selector);

Parameters

Name	Type	Description
selector	`Object`	A CSS selector string, a list of strings, a `FromFrames` selector, or a `FromShadowDom` selector.

Returns

AxePlaywrightBuilder

exclude(Object...)

Exclude a selector that mixes plain CSS selectors with FromFrames or FromShadowDom selectors, for cases the other overloads cannot express.

public AxePlaywrightBuilder exclude(Object... selector);

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.

note

To reach an iframe that lives inside a shadow root, the FromShadowDom selector must be nested inside the FromFrames selector. The reverse causes an error.

Parameters

Name	Type	Description
selector	`Object...`	A mixed set of CSS selectors and selector objects forming a single path to the element to skip.

Returns

AxePlaywrightBuilder

Examples

The following example skips .target inside the shadow root attached to #host, inside the #frame iframe.

new AxePlaywrightBuilder(page)
        .exclude("#frame", new FromShadowDom("#host", ".target"))

include(String)

Specify a single CSS selector to include during analysis. To test several unrelated parts of the page, call include once for each one, passing a single selector each time.

public AxePlaywrightBuilder include(String selector);

Parameters

Name	Type	Description
selector	`String`	A CSS selector specifying elements that will be included in an accessibility analysis.

Returns

AxePlaywrightBuilder

Examples

The following example shows how to include two different classes in the analysis. Note how the example uses method chaining to specify more than one CSS class.

new AxePlaywrightBuilder(page)
        .include(".some-class")
        .include(".some-other-class");

include(List<String>)

Specify a CSS iframe selector to include during analysis.

public AxePlaywrightBuilder include(List<String> includeCSS);

Parameters

Name	Type	Description
includeCSS	`List<String>`	A CSS iframe selector. Every selector but the last matches one level of iframe nesting; the last matches the element to test inside the innermost iframe.

Returns

AxePlaywrightBuilder

Examples

The following example shows how to include elements using CSS iframe selectors.

// To include everything within html of parent-iframe
new AxePlaywrightBuilder(page)
        .include(Arrays.asList("#parent-iframe", "#html"))

Because there is no include(String...) overload, passing more than one string to include also produces a single iframe selector rather than separate includes. The following call resolves to include(Object...) and means the same thing as the example above.

new AxePlaywrightBuilder(page)
        .include("#parent-iframe", "#html")

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

include(FromFrames)

Include an element inside one or more nested iframes, using an explicit FromFrames selector.

public AxePlaywrightBuilder include(FromFrames fromFrames);

Import the class with import com.deque.html.axecore.args.FromFrames;.

Parameters

Name	Type	Description
fromFrames	`FromFrames`	A selector built from one CSS selector per level of iframe nesting, followed by a selector for the element to test inside the innermost iframe.

Returns

AxePlaywrightBuilder

Examples

The following example tests the form inside the #payment-frame iframe.

new AxePlaywrightBuilder(page)
        .include(new FromFrames("#payment-frame", "form"))

include(FromShadowDom)

Include an element inside one or more nested shadow DOM trees, using an explicit FromShadowDom selector.

public AxePlaywrightBuilder include(FromShadowDom fromShadowDom);

Import the class with import com.deque.html.axecore.args.FromShadowDom;.

Parameters

Name	Type	Description
fromShadowDom	`FromShadowDom`	A selector built from one CSS selector per shadow host, followed by a selector for the element to test inside the innermost shadow root.

Returns

AxePlaywrightBuilder

Examples

The following example tests the #search form inside the shadow root attached to .app-header.

new AxePlaywrightBuilder(page)
        .include(new FromShadowDom(".app-header", "form#search"))

include(Object)

Include a selector supplied as a single object. This overload is selected 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 AxePlaywrightBuilder include(Object selector);

Parameters

Name	Type	Description
selector	`Object`	A CSS selector string, a list of strings, a `FromFrames` selector, or a `FromShadowDom` selector.

Returns

AxePlaywrightBuilder

include(Object...)

Include a selector that mixes plain CSS selectors with FromFrames or FromShadowDom selectors, for cases the other overloads cannot express.

public AxePlaywrightBuilder include(Object... selector);

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.

note

To reach an iframe that lives inside a shadow root, the FromShadowDom selector must be nested inside the FromFrames selector. The reverse causes an error.

Parameters

Name	Type	Description
selector	`Object...`	A mixed set of CSS selectors and selector objects forming a single path to the element to test.

Returns

AxePlaywrightBuilder

Examples

The following example tests .target inside the shadow root attached to #host, inside the #frame iframe.

new AxePlaywrightBuilder(page)
        .include("#frame", new FromShadowDom("#host", ".target"))

setLegacyMode

Excludes accessibility issues that may occur in cross-domain frames and iframes.

public AxePlaywrightBuilder setLegacyMode(boolean legacyMode);

note

This API is expected to be removed in the next version of Axe DevTools.

Returns

AxePlaywrightBuilder

Examples

The following example turns on legacy mode.

new AxePlaywrightBuilder(page)
        .setLegacyMode(true);

withAxeSource(File)

Provide a custom version of axe-core using Java's File object

public AxePlaywrightBuilder withAxeSource(File file);

Parameters

Name	Type	Description
file	`File`	A file containing JavaScript that implements axe-core.

Returns

AxePlaywrightBuilder

Examples

The following example shows how to use a different file for axe-core instead of the supplied version. You would only need to do this in specialized cases.

File axeLegacySource = new File("somepath/axe-core@legacy.js");

new AxePlaywrightBuilder(page)
        .withAxeSource(axeLegacySource);

withAxeSource(String)

Provide a custom version of axe-core using an already parsed source

public AxePlaywrightBuilder withAxeSource(String src);

Parameters

Name	Type	Description
src	`String`	The JavaScript source file represented as a `String`.

Returns

AxePlaywrightBuilder

Examples

The following example shows how to read a file into a String and use that as the source file with withAxeSource.

String source = IOUtils.toString(somepPath.toURI(), StandardCharsets.UTF_8);

new AxePlaywrightBuilder(page)
        .withAxeSource(source);

withOnlyBestPracticeRules

Check for accessibility problems with only the best-practice ruleset enabled.

public AxePlaywrightBuilder withOnlyBestPracticeRules();

Returns

AxePlaywrightBuilder

Examples

The following example shows how to enable accessibility analysis using only the best practice rules.


new AxePlaywrightBuilder(page)
        .withOnlyBestPracticeRules();

withOnlyExperimentalRules

Check for accessibility problems with only the experimental ruleset enabled

public AxePlaywrightBuilder withOnlyExperimentalRules();

Returns

AxePlaywrightBuilder

Examples

The following example shows how to enable accessibility analysis using only the experimental rules.


new AxePlaywrightBuilder(page)
        .withOnlyExperimentalRules();

withRules

Limit the rules to be executed during accessibility analysis to those specified.

public AxePlaywrightBuilder exclude(List<String> rules);

Parameters

Name	Type	Description
rules	`List<String>`	A list of rules to be used for accessibility analysis.

Returns

AxePlaywrightBuilder

Examples

The following example shows two different ways of using the withRules method. The first creates a List with one rule, color-contrast. The second creates a List containing the rules color-contrast and image-alt.

// Single Rule
new AxePlaywrightBuilder(page)
        .withRules(Collections.singletonList("color-contrast"));

// Multiple Rules
new AxePlaywrightBuilder(page)
        .withRules(Arrays.asList("color-contrast", "image-alt"));

withTags

Limits accessibility analysis to the ruleset or rulesets belonging to the specified tags.

public AxePlaywrightBuilder withTags(List<String> tags);

Parameters

Name	Type	Description
tags	`List<String>`	A list of tags that include the rules you would like included in the accessibility analysis.

Returns

AxePlaywrightBuilder

Examples

This example shows how to limit the accessibility analysis to rules belonging to the specified tags. The first code snippet shows how to limit the analysis to rules that are part of the wcag21aa specification. The second snippet shows how to limit the analysis to the wcag21aa specification and the best-practice rules.

// Single tag
new AxePlaywrightBuilder(page)
        .withTags(Collections.singletonList("wcag21aa"));

// Multiple tags
 new AxePlaywrightBuilder(page)
        .withTags(Arrays.asList("wcag21aa", "best-practice"));