Accessibility testing for Intern
How it works
Accessibility testing works by having a scanner check a page or page fragment for rule violations. The most commonly used rules are defined in the W3C's Web Content Accessibility Guidelines (WCAG) and the GSA's Section 508 Standards. There are twelve general WCAG guidelines at three levels of success criteria: A, AA, and AAA. Scanners can check for violations at any of the levels, and can typically be configured to only check a subset of rules.
Both scanners are able to test entire pages and document fragments (or portions of a full page). In all cases, though, the scanners operate on a fully styled DOM. This means that if a user needs to test a single commponent in isolation, they'll need to create a test page with all the styles and supporting code required by the component, and use that page to run accessibility tests on the component.
Note that because aXe must be injected into a loaded page, it can only be used in functional test suites (i.e., those listed in
functionalSuites in an Intern config). Tenon makes HTTP calls to an external service and can be used in unit or functional tests.
The a11y module should be installed as a peer of Intern.
$ npm install intern --save-dev $ npm install @theintern/a11y --save-dev
Using either the aXe or Tenon modules is straightforward. The service modules can be accessed from the
services property on the
;const axe = servicesaxe;
const axe = servicesaxe;
The simplest Tenon test looks like:
'check accessibility'return tenon;
Similarly, the simplest aXe test looks like:
'check accessibility'return aXe;
aXe may also be used inline in a Leadfoot Command chain:
In all cases, the check is asynchronous and Promise-based. If the check fails (i.e., accessibility violations are detected), the returned Promise is rejected.
The repository contains two example projects that use
- cd into
TENON_API_KEY=<your key> npm test
- cd into
npm run build
TENON_API_KEY=<your key> npm test
@theintern/a11y module will return an object with a
services property. This property value is an object with
axe properties. You can also import the service modules directly:
The aXe checker must be injected into the page being analyzed, and therefore can only be used in functional test suites. The aXe checker provides two functions,
check function performs an accessibility analysis on a given URL using a given Command object (typically
The two required parameters are
remote is a Leadfoot Command object, generally
this.remote in a test.
source is the URL that will be analyzed.
There are three optional parameters.
waitFor is a number of milliseconds to wait after a page has loaded before starting the accessibility analysis.
context is a CSS selector (ID or class name) that can be used to confine analysis to a specific part of a page. The
config paramter contains aXe configuration options.
createChecker function returns a Leadfoot Command helper (a
then callback). It assumes that a page has already been loaded and is ready to be tested, so it doesn't need a source or Command object.
createCheckerconfig?: AxeTestOptions: Command<A11yResults>
The Tenon checker works by making requests to a remote cloud service. It can be used in functional or unit test suites.
check function works the same way as the axe module's, and takes a similar argument object.
The A11yReporter class is an Intern reporter that will write test failure detail reports to a file or directory. The
check methods will fail if accessibility failures are present, regardless of whether the A11yReporter reporter is in use. This reporter simply outputs more detailed information for any failures that are detected.
The reporter is loaded as an Intern plugin. It can be configured with a filename, which may name an HTML file, in which case all test reports will be written to a single file, or a directory name, in which case test reports will be written to individual HTML files in the given directory.
plugins:script: '@theintern/a11y/A11yReporter'options:// If this is a filename, all failures will be written to the given// file. If it's a directory name (no extension), each test failure// report will be written to an individual file in the given directory.filename: 'somereport.html'
The A11yReporter class also exposes a
writeReport static method. This method allows accessibility test results to be explicitly written to a file rather than relying on the reporter:
First, clone this repo. Then:
$ npm install $ npm run build
Output will be generated in the
_build/ directory. To clean up, run
$ npm run clean
To run tests:
$ TENON_API_KEY=<your key> npm test
You can provide standard Intern arguments like
Note that a Tenon API key must be provided to run Tenon self-tests. If no key is provided, the tests will be skipped.
a11y is offered under the New BSD license.