Nightwatch aXe-core

Nightwatch.js commands for running aXe-core.

Installation

Install using yarn or npm

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

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

`js
{
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.

$3

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:

`js
// 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.

`js
// 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()
}
}
`

$3

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.

`js
axe(context, options)
`

For example;
`js
// 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()
}
}
`

$3

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

`js
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.