@sa11y/jest

Accessibility matcher for Jest

- Overview
- Install
- Setup
- Project level
- Test module level
- Usage
- Caveats
- Disabled checks
- Automatic checks
- Using environment variables
- Sa11y results processor
- JSON result transformation
- Group violation results processor
- Limitations
- Disabled Checks
- Related Packages
- Options
- Environment Variables

Overview

The toBeAccessible() API from this library can be used in Jest unit tests to test HTML elements or DOM for accessibility.


!Screenshot showing Sa11y Jest API usage and a11y errors showing up in VSCode

Install

- Using yarn: yarn add -D @sa11y/jest
- Using npm: npm install -D @sa11y/jest

Setup

The accessibility APIs need to be registered with Jest before they can be used in tests.

$3

You can set up the sa11y API once at the project level to make it available to all the Jest tests in the project. For an example look at the Integration test setup in @sa11y.

- Add a Jest setup file (e.g. jest-setup.js) and add the following code that registers the sa11y API

``javascript
// Import using either CommonJS require or ES6 import
const { setup } = require('@sa11y/jest'); // CommonJS
import { setup } from '@sa11y/jest'; // ES6
// Register the sa11y matcher
setup();

// Register with custom options for automatic checks and DOM saving
setup({
autoCheckOpts: { runAfterEach: true, cleanupAfterEach: true },
renderedDOMSaveOpts: {
/ your RenderedDOMSaveOpts here /
},
});
`

- Add or Modify the Jest config at project root to invoke the Jest setup file as setup above.
- In the jest.config.js at the root of your project, add:

`javascript
module.exports = {
setupFilesAfterEnv: ['/sa11y-jest-setup.js'],
};
`

- If the project already has jest configs, they can be merged e.g.

`javascript
const { jestConfig } = require('@salesforce/sfdx-lwc-jest/config');

const setupFilesAfterEnv = jestConfig.setupFilesAfterEnv || [];
setupFilesAfterEnv.push('/jest-sa11y-setup.js');

module.exports = {
...jestConfig,
setupFilesAfterEnv,
};
`

- This makes the toBeAccessible API available for any test in the project.

$3

Invoke setup before using the toBeAccessible API in the tests

`javascript
import { setup } from '@sa11y/jest';

beforeAll(() => {
setup();
});
`

- This makes the toBeAccessible API available for the tests only in that specific test module where setup() is invoked.

Usage

- toBeAccessible can either be invoked on the entire document (JSDOM) or on a specific HTML element to check for accessibility

`javascript
import { extended, full } from '@sa11y/preset-rules';
import { setup } from '@sa11y/jest';

beforeAll(() => {
setup();
});

it('should be accessible', async () => {
// Setup DOM to be tested for accessibility
//...

// assert that DOM is accessible (using base preset-rule)
await expect(document).toBeAccessible();

// Can be used to test accessibility of a specific HTML element
const elem = document.getElementById('foo');
await expect(elem).toBeAccessible();

// To test using an extended ruleset with best practices and experimental rules
await expect(document).toBeAccessible(extended);

// To test using all rules provided by axe
await expect(document).toBeAccessible(full);
});
`

$3

- async: toBeAccessible must be invoked with async/wait or Promise or the equivalent supported asynchronous method in your environment
- Not invoking it async would result in incorrect results e.g. no issues reported even when the page is not accessible
- Promise should not be mixed together with async/wait. Doing so could result in Jest timeout and other errors.
- In spite of using async/await correctly if you run into the error Axe is already running. Use await axe.run() to wait for the previous run to finish before starting a new run. try running tests serially by using Jest's run in band option.
- useRealTimers: ⏲ When Timer is mocked (e.g. jest.useFakeTimers()) accessibility API can timeout. Before invoking the accessibility API switch to the real timer (e.g. jest.useRealTimers()).
- DOM: 💡 The accessibility checks _cannot_ be run on static HTML markup. They can only be run against a rendered DOM.
- template: