Write Cucumber Tests

Using Cucumber with axe DevTools

Prerequisites

In order to write accessibility tests and produce results, you must have already created a test file with axe DevTools and your choice of Selenium WebDriver pre-imported & pre-initialized. If you haven't done this yet, read this guide on how to do so.

Configuration

First, add axe DevTools to your configuration

public class AppConfiguration {

    @Bean
    public static AxeWorld axeWorld() {
        return new AxeWorld();
    }
}

Now, add the required steps for using axe DevTools

public class StepDefinitions {

    private AxeWorld axeWorld;

    public StepDefinitions(AxeWorld axeWorld) {
        this.axeWorld = axeWorld;
    }

    private WebDriver webDriver;

    @Before
    public void setup() throws IOException {
        webDriver = new ChromeDriver();
        axeWorld.setPage(new AxeDriver(webDriver));
    }

    @After
    public void tearDown() throws Exception {
        webDriver.quit();
    }

    @When("^I visit \"([^\"]*)\"$")
    public void iVisit(String url) throws Throwable {
        webDriver.get(url);

    }
}

Writing Tests

Before you can test a page, you need to access it. The first step is to instantiate Selenium WebDriver and access a page

WebDriver webDriver = new ChromeDriver();
webDriver.get("'https://broken-workshop.dequelabs.com'");

Then, you can create an axe DevTools scan driver object and pass in the WebDriver

AxeDriver axeDriver = new AxeDriver(webDriver);

Finally, include the axeDriver in your step definitions

// Inject AxeWorld into your step definitions.
public StepDefinitions(AxeWorld axeWorld) {
  this.axeWorld = axeWorld;
}
// Provide the page to the Axe World
axeWorld.setPage(new axeDriver(webDriver));

You can then test the page for accessibility. Currently, axe DevTools supports Pico and Spring testing through Cucumber.

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 between these two is whether testing will fail on accessibility violations with Then the page should be axe clean, versus not fail with Then the page should be audited for accessibility.

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

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. It performs an audit on the accessibility of your page. The audit logs accessibility issues to target/axe-report/accessibility-check.log and creates JSON output of the results at target/axe-report/accessibility-check.json.

Then the page should be axe clean

This step will cause test suite failures if accessibility violations are found

Then the page should be audited for accessibility

This step will require handling of violations outside of test suite failures, as this step does not trigger the suite to fail if violations are found.

Scoping

Axe DevTools allows for accessibility scans to be scoped inclusively and exclusively. Additionally, these scopes can work within each other to create complex enclaves and exclaves of scoping. These scopes work off of CSS selectors.

Inclusion Clause

The inclusion clause within "#selector" specifies which elements to check on the page. Only elements within the selected scope will be scanned. 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"

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

Exclusion Clause

The exclusion clause excluding "#selector" specifies which elements to ignore. No elements within the selected scope will be scanned. The exclusion clause must include a valid CSS selector surrounded in double quotes. Use compound selectors to select multiple elements. E.g. excluding "#widget, .ad"

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

Chaining inclusion and exclusion

In order to chain inclusion and exclusion clauses, Use the semicolon (;) or the word but to separate them.

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

Rule configuration

There are a few ways to change your standard rule configuration using the Cucumber API. You can select rules by group through the use of tags, or select rules individually by their rule ID.

Rule Tag Clause

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

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

Then the page should be axe clean according to: best-practice

Check Additional Rules Clause

This clause allows you to append additional rules onto your existing rules. You can specify a single rule by rule ID, or a list of rules separated by commas. See the rules documentation for a list of the rules and their rule IDs. Use a semicolon (;) or the word and to separate the checking-rules clause from any preceding clause(s).

Then the page should be axe clean checking: color-contrast

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

Checking Only Specified Rules Clause

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. Only specified rules are checked if the word only is used. See the rules documentation for a list of the rules and their rule IDs. Use a semicolon (;) or the word and to separate the checking-rules clause from any preceding clause(s).

Then the page should be axe clean checking only: color-contrast

Skipping Rules Clause

The skipping-rules clause specifies which rules to skip from the existing rule configuration. Rules to be skipped are specified by comma-separated rule IDs. See the rules documentation for a list of the rules and their rule IDs. Use a semicolon (;) or the word and to separate the checking-rules clause from any preceeding clause(s).

Then the page should be axe clean skipping: color-contrast

Then the page should be axe clean according to: wcag2a; skipping: color-contrast
Then the page should be axe clean according to: wcag2a but skipping: color-contrast

Ruleset Selection Clause

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

Then the page should be axe clean according to ruleset: wcag2.1

Usage Service

Gain insight into axe DevTools usage trends within your organization

By default the usage-service is disabled and the default url is https://usage.deque.com.

Environment variables

This method allows users to change specific values of the usage service via environment variables

Next Steps

For further use of your axe DevTools scan results, like reporting, see the axe DevTools Java Selenium package documentation

Troubleshooting

If you experience issues setting up your accessibility testing, contact your Deque representative directly, reach us via our support desk, or send us an email. We're happy to help get your accessibility testing efforts off the ground.