Nightwatch aXe-core

Nightwatch.js commands for running aXe-core.

Installation

Install using yarn or npm

npm install nightwatch-axe-core --save-dev

Add these commands to the custom_commands_path in your Nightwatch.js configuration.

{
  custom_commands_path : [
    "./node_modules/nightwatch-axe-core/commands"
  ]
}

Configuration & Usage

The axe() command takes the following two parameters:

Parameter Name | Parameter Type | Description ------------- | ---------------- | ----------- context | string or object | css selector or include/exclude object options | object | set of axe options

These can be defined globally and/or per call to the axe() command.

In addition to the standard aXe options:

• options.timeout configures Nightwatch's timeoutsAsyncScript() amount, default value is 1000 milliseconds.

aXe can require a fair amount of time to run, so increasing the timeout option is often required.

Injecting aXe-core

Since Nightwatch 2.3.6, axe is included by default, but still requires calling both axeInject() and axeRun(). This command handles both.

Global configuration file

Create an axe.conf.js file in your project root as an CommonJS module that exports a default object with both the context and options parameters:

// axe.conf.js

module.exports = {
  context: {
    include: [['html']],
    exclude: [['.advertising']],
  },
  options: {
    runOnly: {
      type: 'tag',
      values: ['wcag2a', 'wcag2aa'],
    },
    timeout: 2000,
  }
};

Then your test simply needs to call the axe() command.

// nightwatch-test.js

export default {
  '@tags': ['accessibility'],

  'Thing passes aXe-core checks': function (browser) {
    browser
      .url(`${browser.launch_url}/page-to-test`)
      .waitForElementPresent('.thing-to-test')
      .axe()
      .end()
  }
}

Per test configuration

When calling axe() you can can pass in the context and options values as arguments. context will override any globally defined contexts, whilst options will be merged with any globally defined options. This way you can have edge case tests that inherit global config but can easily be change one or two things.

axe(context, options)

For example;

// nightwatch-test.js

export default {
  '@tags': ['accessibility'],

  'Thing passes aXe-core checks': function (browser) {
    browser
      .url(`${browser.launch_url}/page-to-test`)
      .waitForElementPresent('.thing-to-test')
      .axe('.thing-to-test', {
        runOnly: {
          type: 'tag',
          values: ['wcag2a']
        },
        rules: {
          'color-contrast': { enabled: true },
          'valid-lang': { enabled: false }
        },
      })
      .end()
  }
}

Debugging

When debugging a failure it can be useful to enable all of the output options, and set a large timeout;

options: {
  timeout: 60000,
  verbose: true,
  selectors: true,
  absolutePaths: true,
  ancestry: true,
  elementRef: true,
}

This will give you as much information as possible into what caused the failure.

Another helpful option is setting resultTypes: ['violations'], as described in the axe-core docs which can improve performance and reduce timeout failures.