axe-devtools-behave API Reference

This package integrates axe DevTools into Behave, a cucumber-like python testing framework.

Usage

Before you can use axe-devtools-behave, you must setup a few things.

First of all, you have to configure opening and closing a browser, via features/environment.py:

# features/environment.py

import behave_webdriver

def before_all(context):
    context.behave_driver = behave_webdriver.Chrome()

def after_all(context):
    # cleanup after tests run
    context.behave_driver.quit()

Next you must import axe-devtools-behave, which can be done by doing so in features/steps/axe.py:

# features/steps/axe.py

from axe_devtools_behave import *

Now you can make use of axe-devtools-behave in your feature files.

The axe-devtools-behave package makes use of behave-webdriver, so all steps from that library are brought in and available for usage.

Accessibility Cucumber Steps

The example accessibility checks below use Then the page should be axe clean, but all checks work interchangeably with Then the page should be audited for accessibility.

The difference is that should be axe clean runs axe and fails the test if there are violations, while should be audited for accessibility runs axe and saves the results to an axe-reports directory. should be audited for accessibility never fails.

To construct an axe accessibility Cucumber step, begin with the base step, and append any clauses necessary. All of the following clauses may be mixed and matched; however, they must appear in the specified order:

Then the page should be axe clean [including] [excluding] [according-to] [checking-rules/checking-only-rules] [skipping-rules]

Base Step

    Then the page should be axe clean

The base step is the core component of the Cucumber step. It is a complete step on its own and verifies the currently loaded page is accessible using the default configuration of axe.a11yCheck (the entire document check uses the default rules).

Inclusion clause

    Then the page should be axe clean within "#selector"

The inclusion clause (within "#selector") specifies which elements to check on the page. The inclusion clause must include a valid CSS selector surrounded in double quotes. Use compound selectors to select multiple elements. E.g. within "#header, .footer"

Exclusion clause

    Then the page should be axe clean excluding "#selector"

The exclusion clause (excluding "#selector") specifies which document elements to ignore. Provide a valid CSS selector surrounded in double quotes. Use compound selectors to select multiple elements. E.g. excluding "#widget, .ad"

Use the semicolon (;) or the word but to separate the exclusion clause from the inclusion clause if present.

    Then the page should be axe clean within "main"; excluding "aside"
    Then the page should be axe clean within "main" but excluding "aside"

Accessibility Standard (Tag) clause

    Then the page should be axe clean according to: tag-name

The tag clause specifies which accessibility standard (or standards) to use in the page check. Specify the accessibility standards by name (tag). Multiple standards can be specified when comma-separated. E.g. according to: wcag2a, section508

Acceptable tag names are documented in addition to a complete list of rule descriptions that correspond to each tag.

Use 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 Rules clause

    Then the page should be axe clean checking: ruleId

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

See Rule Descriptions for a list of valid rule IDs.

Use a semicolon (;) or the word and 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 axe clean according to: wcag2a and checking: color-contrast

Exclusive Rules clause

    Then the page should be axe clean checking only: ruleId

This clause is not separate. By adding the word only to the checking-rules clause, you can change the meaning of the step. As previously described, the checking-rules clause specifies additional rules to run by default. Only specified rules are checked if the word only is used.

Skipping Rules clause

    Then the page should be axe clean skipping: ruleId

The skipping-rules clause specifies which rules to skip. Specify the accessibility standard to use (via the tag clause) while ignoring a particular rule. Specify rules by comma-separated rule IDs.

See Rule Descriptions for a list of valid rule IDs

Use a semicolon (;) or the word but to separate the skipping-rules clause from the preceding clause.

Then the page should be axe clean according to: wcag2a; skipping: accesskeys
Then the page should be axe clean according to: wcag2a but skipping: accesskeys

Tagged rulesets

Access tagged rulesets through a Cucumber clause. This functionality enables developers to specify a ruleset (Eg: 508, wcag2, wcag2.1) to audit page accessibility.

The following code demonstrates Cucumber Gherkin syntax required to assess a specific ruleset during analysis:

Scenario: Test Page with options
  When I visit "http://abcdcomputech.dequecloud.com/"
  Then the page should be audited for accessibility within "title" according to ruleset: wcag2.1