API Reference for Java Playwright
This document provides an API reference to the AxePlaywrightBuilder Java class, which is provided by the Playwright Java integration.
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 | Specifies CSS selectors to be used to exclude certain HTML content during analysis. |
| include | Specifies CSS selectors that include HTML content during analysis. |
| 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
Specify CSS selectors to exclude HTML elements during analysis.
public AxePlaywrightBuilder exclude(List<String> excludeCSS);Parameters
| Name | Type | Description |
|---|---|---|
| excludeCSS | List<String> | A list of CSS selectors 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(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
| Name | Type | Description |
|---|---|---|
| includeCSS | List<String> | A list of CSS selectors 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(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);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"));