Advanced API Usage with Ruby

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

Custom Elements and ElementInternals

Starting in Axe DevTools Ruby 4.13.0, scans read the ARIA semantics that web components declare in JavaScript through ElementInternals, rather than only the role and aria-* attributes present in the markup. No configuration is required. Semantics in the DOM still take precedence: an explicit role or aria-* attribute on the element overrides the value from ElementInternals.

Your components must publish their internals for any of this to take effect, and a component that stores them in a private class field cannot be read. See Testing Custom Elements That Use ElementInternals.

Custom Rules

You can specify custom axe-core 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.
• Using the CLI to Send Accessibility Results to Axe Developer Hub shows how you can upload your .json results files to Axe Developer Hub.

Usage Service

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

By default, the usage service is enabled, 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

Teams

You can record the teams running your tests in usage events. Each team is a hash with string id and name values. Entries without both are dropped, and an empty array sends no teams.

You can set teams in three places. If more than one is set, the first one in this list is used:

1. For a single RSpec check, the for_teams clause.

2. For the whole run, the teams configuration property:

   AxeDevTools.configure do |config|
     config.teams = [{ id: "1", name: "Web" }]
   end

3. The AXE_TEAMS environment variable, set to a JSON array of { "id": "...", "name": "..." } objects or to the path of a JSON file containing one. If the value can't be read, the API prints a warning and sends no teams, and the scan continues.

The Cucumber gem has no per-check option, so use the teams configuration property or AXE_TEAMS with Cucumber.

Usage events also record whether a person or an automated pipeline ran the tests. The API reports automation when a common CI environment variable such as CI, GITHUB_ACTIONS, or JENKINS_URL is set, and human otherwise. Set AXE_ACTOR to human or automation to override this.

Configuring Usage Service Options with Environment Variables

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