Advanced API Usage with Ruby

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.

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:

AXE_RULESET_PATH=/path/to/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 https://github.com/dequelabs/axe-core/blob/develop/doc/rule-descriptions.md
  config.rule_set_id = '508'
end

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'
end

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

The reporting configuration can take the following properties:

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'
end

See Also

• Uploading JSON Accessibility Results to axe Reports describes how to upload your results to axe Reports.
• Obtaining an axe Reports API Key tells how to obtain an API key to begin using axe Reports.
• Creating and Filtering Reports shows how you can create accessibility reports in CSV, XML, or HTML from your JSON accessibility results. You can also filter your output by severity using this tool.
• How JSON Results are Stored on Disk describes the file naming conventions for JSON accessibility results.

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 https://usage.deque.com.

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: 'https://usage.deque.com',
end

The usage service specific configuration properties are:

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
end

Configuring Usage Service Options with Environment Variables

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

# To disable usage tracking
AXE_TRACK_USAGE=false
# To configure where usage data is sent
AXE_METRICS_URL=https://usage.dequelabs.com