API Reference for Java Playwright

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

Constructors

AxePlaywrightBuilder(Page)

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

public AxePlaywrightBuilder(Page page);

Parameters

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

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

Example

The following code example demonstrates this constructor.

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

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

Methods

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

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

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

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

Specify CSS selectors to exclude HTML elements during analysis.

public AxePlaywrightBuilder exclude(List<String> excludeCSS);

Parameters

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(Collections.singletonList(".some-class"))
        .exclude(Collections.singletonList(".some-other-class"));

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"))

include

CSS selectors to include during analysis

public AxePlaywrightBuilder include(List<String> includeCSS);

Parameters

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(Collections.singletonList(".some-class"))
        .include(Collections.singletonList(".some-other-class"));

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"))

setLegacyMode

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

public AxePlaywrightBuilder setLegacyMode(boolean legacyMode);

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

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

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

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

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"));