AxeRunOptions Class

The AxeRunOptions class provides configuration options that control how axe-core performs accessibility testing. This class allows you to enable or disable specific rules, limit which rules are executed, and configure analysis details such as ancestry information for accessibility violations.

These options are passed to axe-core at runtime to customize the behavior of the accessibility analysis engine.

Constructor

AxeRunOptions()

Creates a new instance of AxeRunOptions with default settings. By default, the ancestry property is set to false.

AxeRunOptions options = new AxeRunOptions();

Methods

setAncestry(boolean ancestry)

Sets the ancestry property. When set to true, the axe-core engine will include the complete CSS selector path for elements with accessibility violations, including all parent elements. This helps in locating violations in complex DOM structures.

Parameters:

• ancestry - Boolean value to enable or disable ancestry information

Returns:

• AxeRunOptions - The current instance for method chaining

Example:

AxeRunOptions options = new AxeRunOptions();
options.setAncestry(true);

setRunOnly(AxeRunOnly runOnly)

Sets the runOnly property, which allows you to limit which accessibility rules are executed. Use this to focus testing on specific standards or rule sets.

Parameters:

• runOnly - An AxeRunOnly instance specifying which rules or tags to run

Returns:

• AxeRunOptions - The current instance for method chaining

Example:

AxeRunOnly runOnly = new AxeRunOnly()
    .setType("tag")
    .setValues(Arrays.asList("wcag21aa", "best-practice"));

AxeRunOptions options = new AxeRunOptions();
options.setRunOnly(runOnly);

setRules(Map<String, AxeRuleOptions> rules)

Sets the rules property, which allows you to enable or disable specific accessibility rules by ID.

Parameters:

• rules - A map of rule IDs to AxeRuleOptions instances

Returns:

• AxeRunOptions - The current instance for method chaining

Example:

Map<String, AxeRuleOptions> rules = new HashMap<>();
rules.put("color-contrast", new AxeRuleOptions().setEnabled(false));
rules.put("aria-roles", new AxeRuleOptions().setEnabled(true));

AxeRunOptions options = new AxeRunOptions();
options.setRules(rules);

getAncestry()

Gets the current value of the ancestry property.

Returns:

• boolean - The current value of the ancestry property

Example:

AxeRunOptions options = new AxeRunOptions();
options.setAncestry(true);
boolean ancestry = options.getAncestry(); // Returns true

getRunOnly()

Gets the current AxeRunOnly configuration.

Returns:

• AxeRunOnly - The current runOnly configuration, or null if not set

Example:

AxeRunOptions options = new AxeRunOptions();
AxeRunOnly runOnly = new AxeRunOnly()
    .setType("tag")
    .setValues(Arrays.asList("wcag21aa"));
options.setRunOnly(runOnly);

AxeRunOnly currentRunOnly = options.getRunOnly(); // Returns the runOnly configuration

getRules()

Gets the current map of rule configurations.

Returns:

• Map<String, AxeRuleOptions> - The current rules configuration, or null if not set

Example:

AxeRunOptions options = new AxeRunOptions();
Map<String, AxeRuleOptions> rules = new HashMap<>();
rules.put("color-contrast", new AxeRuleOptions().setEnabled(false));
options.setRules(rules);

Map<String, AxeRuleOptions> currentRules = options.getRules(); // Returns the rules map

toJson()

Serializes the AxeRunOptions instance to a JSON string.

Returns:

• String - A JSON string representation of the options

Example:

AxeRunOptions options = new AxeRunOptions()
    .setAncestry(true)
    .setRunOnly(new AxeRunOnly()
        .setType("tag")
        .setValues(Arrays.asList("wcag21aa")));

String json = options.toJson();
// Returns JSON like: {"ancestry":true,"runOnly":{"type":"tag","values":["wcag21aa"]}}

Configuration Validation Notes

When configuring AxeRunOptions, be aware of the following validation rules:

1. When using setRules():

   • The rules map must contain at least one entry.
   • Each rule value cannot be null.

2. When using setRunOnly():

   • The type property must be one of: "rule", "rules", "tag", or "tags"
   • The values property must contain at least one value
   • The values property cannot contain null entries

3. Mutually exclusive configurations:

   • You cannot use both runOnly in AxeRunOptions and accessibilityStandard in ConfigurationOverrides at the same time.

See Also

• AxeRuleOptions
• AxeRunOnly
• AxeRunContext
• AxeWatcherOptions