Advanced API Usage with Ruby

Link to Advanced API Usage with Ruby copied to clipboard

This document discusses custom rules, reporting options, and the usage service with Ruby.

Custom Rules

You can specify custom axe rules in a JSON file.


If you do not yet have custom rules and wish to start with an empty custom ruleset, create an axe-ruleset.json file in the local directory with an empty JavaScript object, e.g.: {}.

Configure Custom Rules via an Environment Variable

The default configuration expects the custom rules file location to be config/axe-ruleset.json, relative to the current working directory.

You may override this location with the AXE_RULESET_PATH environment variable or manually via the Axe DevTools configuration.

Set the AXE_RULESET_PATH environment variable to change the location of your axe-ruleset.json:


Configuring Custom Rules via axe DevTools Configuration

A configuration object is available for defining a custom rule location using the AxeDevTools.configure method if you do not wish to work with the AXE_RULESET_PATH environment variable.

All settings below are optional. You may omit the entire AxeDevTools.configure invocation to use original default values.

AxeDevTools.configure do |config|
  # path to json configuration providing custom rules and checks
  # set defaults to "config/axe-ruleset.json"
  config.axe_ruleset_path = "config/axe-ruleset.json"

  # Configure user pre-defined standard rule sets. Custom
  # rules override these rule sets. See
  config.rule_set_id = '508'

Reporting Options

Configuring Reporting Options with axe DevTools Configuration

The axe-devtools-* gems enable logging test results. Use the AxeDevTools.Configure invocation to set up a global configuration for reporting:

AxeDevTools.configure do |config|
  config.output_directory: 'my-results',
  config.test_machine: 'my-server',
  config.test_suite_name: 'Accessibility Tests For Application',
  config.user_agent: 'Headless Chrome'

expect(page).to be_audited_for_accessibility.logging_results({
  ui_state: 'Landing Page Load',

The reporting configuration can take the following properties:

Attribute Default Value Description
ui_state (Mandatory) Attribute to pass in options object.
output_directory (Optional) axe-reports Directory name, into which the reports are to be generated.
test_machine (Optional) Value to depict where the test is run. E.g., CircleCI, TesterMachine01
test_suite_name (Optional) axe-a11yCheck Suite name for the tests. E.g., My Module Test Suite
user_agent (Optional) null Pass a target user agent. E.g., chrome.
verbose (Optional) false flag to enable/disable detailed logging of stack trace and messages.

Also, note that all the above options for AxeDevTools.configure can be passed when configuring the WebDriver of choice. For example:

require 'axe-devtools-capybara'

AxeCapybara.configure do |config|
 config.axe_config_path = 'config/my-ruleset.json'

See Also

Usage Service

You can gain insight into axe DevTools usage trends within your organization with the usage service.

By default, the usage service is disabled, and the tracking url is

Configuring Usage Service Options with AxeDevTools Configuration

The axe-devtools-* gems allow for configuring the usage service via a global configuration:

AxeDevTools.configure do |config|
  config.setTrackingUrl: '',

The usage service specific configuration properties are:

Attribute Default Value Description
enableTracking true Option to enable usage tracking.
setTrackingUrl Option to override tracking URL.

Also, note that all of the above options for AxeDevTools.configure can also be passed when configuring the WebDriver of choice. For example, for Capybara:

require 'axe-devtools-capybara'

AxeCapybara.configure do |config|
 config.enableTracking = false

Configuring Usage Service Options with Environment Variables

Additionally, usage service options can be configured as environment variables.


Values set as environment variables can be overridden by AxeDevTools.configure.

# To disable usage tracking
# To configure where usage data is sent