Deque axe™ Integration


Deque's axe™ is one of the world's leading digital accessibility toolkits. The axe-core library provided by Deque allows you to inject functionality into your tests in order to scan content and return an a11y score.

Below is a guide to set up the Sauce Labs integration. This integration allows you to run your accessibility tests, using axe™, on our platform.

What does a11y stand for, and what is Accessibility Testing?

See the following link for further information.

What You'll Need#


For the purpose of this guide, we will focus entirely on WebdriverIO

Set Up Dependencies#

Add the following dependencies to your package.json file:

  • axe-core for Accessibility tests (a11y results)
  • sauce-service for the WebdriverIO plugin service
"@axe-core/webdriverio": "4.2.1"

Create the Configuration#

Next, create a wdio.conf.js in your root project directory, see the WebdriverIO documentation for further details.

WebdriverIO Instance#

In the wdio.conf.js file, create an object called axeWdio. This object creates a new AxeWebdriverIO instance which accepts the current browser object from WDIO as an argument.

before: function (capabilities, specs, browser) {
const axeWdio = new AxeWebdriverIO({
client: browser

Next, we need to inject an axe-core command into the current page so that it scan for content:

browser.addCommand('getAxeResults', function (name) {
return axeWdio.analyze()

When the analyze() command is called, axe-core then scans the current document content.

The final step is to define a local variable to store the violations (critical, moderate, and/or minor) and return the result:

browser.addCommand('getAxeResults', function (name) {
return axeWdio.analyze()
.then(async (result) => {
const { violations = [] } = result`Test: ${name} - Violations: ${violations.length}`)
return result
.catch(err => {

Set Local Driver Capabilities#

Before you test on Sauce Labs, ensure your axe™ accessibility tests return the desired a11y results. The best course of action is to test against local drivers such as chrome, firefox, safari, etc.

Here are some examples of how to instantiate a local driver through the capabilities object:

capabilities: [{
browserName: 'chrome',
'goog:chromeOptions': {
args: [

For further information please read the following:

Running the Test#

Now in your actual tests, all you need to do is call the following to get the axe-core test results:


Sauce Labs Setup#

It's recommended that you create a separate .conf.js file in order to manage the Sauce Labs configuration details.

For example:

const {config} = require('./wdio.conf');
config.user = "yourUserName";
config.key = "yourAccessKey";
config.region = "yourRegion -> us / eu";
config.capabilities = [
]; ='sauce');
exports.config = config;

Sauce Labs Credentials#

Specify the Sauce Labs user access key and data center region in which you want to run your tests.

config.user = "yourUserName";
config.key = "yourAccessKey";
config.region = "yourRegion -> us / eu";

You can retrieve your Sauce Labs account credentials with this link. The region property is used for both Virtual Machine Cloud and Real Device Cloud tests, and the acceptable values are:

  • us - default
  • eu
Don't Hard-Code Credentials

Hard-coding your user, key, and region property values is not a recommended best practice due to security reasons.

Instead, export your Sauce Labs Account Credentials as Environment Variables and add them in your script like the following example:

config.user = process.env.SAUCE_USERNAME;
config.key = process.env.SAUCE_ACCESS_KEY;
config.region = process.env.REGION || 'us';

Visit the WebDriverIO documentation for further details.

Set Sauce Labs Capabilities#

In order to test on Sauce Labs with multiple different browsers and platforms, add the following configuration options in the capabilities object.

Here are some examples:

browserName: 'googlechrome',
platformName: 'Windows 10',
browserVersion: 'latest',
Browers and OS support on Sauce Labs

For a full list of supported browsers/platforms visit this page.

It's also a best practice to set test options that are specific to Sauce Labs features. For example, declare this at the top of your configuration:

const defaultBrowserSauceOptions = {
build: `Best Practices: Sauce Labs Desktop Web build-${new Date().getTime()}`,
screenResolution: '1600x1200',

and call it in the sauce:options test option, as a part of the capabilities object, like in this example below:

config.capabilities = [
browserName: 'googlechrome',
platformName: 'Windows 10',
browserVersion: 'latest',
'sauce:options': {

Additional Resources#

Last updated on by James Tacker