Writing Tests for Axe DevTools for Web for WebdriverIO

Writing tests with Axe DevTools

The individual snippets in the sections below are JavaScript, and they compile unchanged in TypeScript. The Complete Sample File section gives the full test in both languages.

Prerequisites

In order to import and initialize Axe DevTools for Web it needs to be installed first. If you haven't yet, read the guide on how to install it from a bundle, from your artifact repository, or from Deque's Agora. You also need to have WebdriverIO downloaded and configured.

Importing and Initializing

Import both Axe DevTools for Web and WebdriverIO. The syntax depends on the language and module system your project uses. Pick the one that matches your project:

JavaScript with CommonJS modules

This is the default for a Node.js project without "type": "module" in its package.json.

const { AxeDevToolsWebdriverIO } = require('@axe-devtools/webdriverio');
const webdriverio = require('webdriverio');

JavaScript with ES modules

Use this syntax in a project with "type": "module" in its package.json, or in .mjs files.

import { AxeDevToolsWebdriverIO } from '@axe-devtools/webdriverio';
import { remote } from 'webdriverio';

TypeScript

TypeScript uses the same import syntax as ES modules. @axe-devtools/webdriverio ships its own type declarations, so there is no separate @types/ package to install. Scan results are typed as AxeResults, which axe-core exports:

import { AxeDevToolsWebdriverIO } from '@axe-devtools/webdriverio';
import { remote } from 'webdriverio';
import type { AxeResults } from 'axe-core';

Initializing the Client

At this point, you'll be able to initialize your webdriver inside your testing function. In JavaScript:

const client = await webdriverio.remote({
  capabilities: {
    browserName: 'chrome'
  }
});

In TypeScript, the client is a WebdriverIO.Browser, which is the type AxeDevToolsWebdriverIO expects:

const client: WebdriverIO.Browser = await remote({
  capabilities: {
    browserName: 'chrome'
  }
});

Then, you can initialize Axe DevTools for Web with the webdriver client. This statement is the same in both languages:

const axeDevTools = new AxeDevToolsWebdriverIO({ client });

Getting Scan Context

Before you can scan a page for accessibility, it needs to be accessed by WebdriverIO.

await client.url('<URL>');

Once WebdriverIO has accessed the page, you can scan it with Axe DevTools and save the results. The most simple way to view the results of the scan is to console log the results object.

const results = await axeDevTools.analyze();
console.log(results);

Complete Sample File

The same test is shown below in JavaScript and in TypeScript. The Axe DevTools API is identical in both; the TypeScript version uses import syntax and annotates the client and the scan results.

JavaScript

const webdriverio = require('webdriverio');
const { AxeDevToolsWebdriverIO } = require('@axe-devtools/webdriverio');

const simpleExample = async () => {
  const client = await webdriverio.remote({
    capabilities: {
      browserName: 'chrome'
    }
  });

  await client.url('https://google.com');

  const axeDevTools = new AxeDevToolsWebdriverIO({ client });
  const results = await axeDevTools.analyze();
  await client.deleteSession();
  return results;
};

simpleExample()
  .then(results => {
    console.log(results);
  })
  .catch(err => {
    throw err;
  });

TypeScript

import { remote } from 'webdriverio';
import { AxeDevToolsWebdriverIO } from '@axe-devtools/webdriverio';
import type { AxeResults } from 'axe-core';

const simpleExample = async (): Promise<AxeResults> => {
  const client: WebdriverIO.Browser = await remote({
    capabilities: {
      browserName: 'chrome'
    }
  });

  await client.url('https://google.com');

  const axeDevTools = new AxeDevToolsWebdriverIO({ client });
  const results: AxeResults = await axeDevTools.analyze();
  await client.deleteSession();
  return results;
};

simpleExample()
  .then(results => {
    console.log(results);
  })
  .catch(err => {
    throw err;
  });

Next Steps

Now that you've successfully completed an accessibility scan, you're ready to move on to more advanced scanning topics like generating reports and using the results object.

Troubleshooting

If you have trouble with getting scan results, contact your Deque representative directly, reach us via our support desk, or send us an email. We'll be happy to help.