axe DevTools for Web Cucumber

Link to axe DevTools for Web Cucumber copied to clipboard

The axe-devtools-cucumber gem provides custom step definitions to evaluate if a given page is axe clean.

This gem expands on the steps provided by the axe-core-cucumber gem readme.

Setup and Usage

Ensure you have access to Deque's registry. If not, refer to setup.

  • Add axe-devtools-cucumber to your Gemfile or gemspec file and run bundle install.
gem "axe-devtools-cucumber"
spec.add_dependency "axe-devtools-cucumber"
  • Require the step definitions offered by the gem. Typically, you can do this by adding to an existing cucumber setup file under features/support/env.rb.
require 'axe-cucumber-steps'

API

Step - Be axe Clean (be axe clean)

The step be axe clean is the core component of the integration. It is a complete step on its own and will verify the currently loaded page is axe clean using the default configuration of axe.run (the entire document is checked using the default rules).

Then the page should be axe clean

Step - Be Audited for Accessibility (be audited for accessibility)

This step allows you to audit the accessibility of your site without failing the test suite. For identified violations the matchers will convert the test example to pending and output the detailed violations.

Then the page should be audited for accessibility [including]
[excluding] [according to/according to ruleset] [checking rules/checking-only-rules]
[skipping rules] [logging results for]

Clauses

Clauses are chainable methods for the be axe clean and be audited for accessibility step definitions.

Configurable clauses allow for greater granularity with testing and expectations.

within- Inclusion clause

The inclusion clause (within "#selector") specifies which elements of the page should be checked. A valid CSS selector must be provided and enclosed in double quotes. Compound selectors may be used to select multiple elements, for example, within "#header, .footer". For more information, see the context parameter documentation.

Then the page should be axe clean within "#selector"
excluding- Exclusion clause

The exclusion clause (excluding "#selector") specifies which elements of the document should be ignored. A valid CSS selector must be provided and enclosed in double quotes. Compound selectors may be used to select multiple elements, for example, excluding "#widget, .ad". For more information, see the context parameter documentation.

Then the page should be audited for accessibility excluding "#selector"

If desired, a semicolon (;) or the word but may be used to separate the exclusion clause from the inclusion clause (if present).

Then the page should be audited for accessibility within "main"; excluding "aside"
Then the page should be axe clean within "main" but excluding "aside"
according to- Accessibility Standard (Tag) clause

The tag clause specifies which accessibility standard (or standards) should be used to check the page. The accessibility standards are specified by name (tag). Multiple standards can be specified when comma separated, for example, according to: wcag2a, section508. The acceptable tag names are documented as well as a complete listing of rules that correspond to each tag.

Then the page should be audited for accessibility according to: tag-name

If desired, a semicolon (;) may be used to separate the tag clause from the preceding clause.

Then the page should be axe clean within "#header"; according to: best-practice
checking- Checking Rules clause

The checking-rules clause specifies which additional rules to run (in addition to the specified tags, if any, or the default ruleset). The rules are specified by comma-separated rule IDs.

Then the page should be axe clean checking: ruleId

For a list of valid rule IDs, see the rules documentation.

If desired, a semicolon (;) or the word and may be used to separate the checking-rules clause from the preceding clause.

Then the page should be axe clean according to: wcag2a; checking: color-contrast
Then the page should be audited for accessibility according to: wcag2a and checking: color-contrast
checking only- Exclusive Rules clause

This clause is not really a separate clause. But rather, by adding the word only to the checking-rules clause, the meaning of the step can be changed. As described above, by default the checking-rules clause specifies additional rules to run. If the word only is used, then only the specified rules are checked.

Then the page should be axe clean checking only: ruleId
skipping- Skipping Rules clause

The skipping-rules clause specifies which rules to skip. This allows an accessibility standard to be provided (via the tag clause) while ignoring a particular rule. The rules are specified by comma-separated rule IDs.

Then the page should be audited for accessibility skipping: ruleId

For a list of valid rule IDs, see the rules documentation.

You may use a semicolon (;) or the word but to separate the skipping-rules clause from the preceding clause, as shown below:

Then the page should be axe clean according to: wcag2a; skipping: accesskeys
Then the page should be audited for accessibility according to: wcag2a but skipping: accesskeys
Clauses available only to step - Be Audited for accessibility

The be audited for accessibility matcher provides support for two additional clauses.

according to ruleset- Ruleset clause

The ruleset clause [according to ruleset] helps specify a single ruleset (for example, 508, wcag2, wcag21) to be used to check the page.

Then the page should be axe clean according to ruleset: wcag2
logging results- Logging results clause

To log results from the base matcher and clauses, invoke the chainable method logging results as shown below. The logging results for: report_name clause allows to specify the name of the report generated at the end of step execution.

Then the page should be audited for accessibility logging results for: axe_report_of_my_site
Interoperability between clauses

All the described clauses may be mixed and matched with method chaining. Below are some examples.

Then the page should be audited for accessibility within "main, header" but excluding "footer"

Then the page should be axe clean excluding "#sidebar" according to: wcag2a, wcag2aa but skipping: color-contrast

Then the page should be audited for accessibility checking only: document-title, label

Then the page should be axe clean according to: best-practice and checking: aria-roles, definition-list

Advanced API usage

Refer to advanced usage to see how to configure the API for:

  • Custom rules
  • Custom path to axe source
  • Usage recording
  • Reporting

Is this page helpful?

Help us improve this page

Still need help?