jest-a11y
Custom Jest matchers for testing accessibility.
The problem
When writing web applications, the ability to easily follow accessibility guidelines is becoming essential. As developers, we need a framework to easily and quickly test compliance.
This solution
The jest-a11y project aims to provide a set of jest matchers that will check whether the provided DOM element has the correct ARIA roles and supports keyboard navigation.
FAQ:
Why are ARIA roles important?
ARIA roles provide semantic meaning to content, allowing screen readers and other tools to present and support interaction with object in a way that is consistent with user expectations of that type of object. ARIA roles can be used to describe elements that don't natively exist in HTML or exist but don't yet have full browser support.
How is this different from jest-axe?
The jest-axe plugin will parse through the provided DOM structure and check for any violations. This plugin will also attempt to validate keyboard navigation.
Does this work with Enzyme or React Testing Library?
Yes. It works with either of those tools.
Table of Contents
Installation
This module is distributed via npm which is bundled with node and should be installed as one of your project's dependencies:
With npm:
npm install --save-dev jest-a11yWith yarn:
yarn add -D jest-a11yUsage
// In your own jest-setup.js (or any other name e.g. setupTests.js)
import 'jest-a11y'From there, you can use the matchers in your tests.
describe('MyButtonComponent', () => {
it('passes when element is valid', async () => {
render(<button>click me</button>)
expect(screen.getByRole('button')).toBeAccessibleButton()
})
})With Typescript
If you're using TypeScript, make sure your setup file is a .ts and not a .js to include the necessary types.
You will also need to include your setup file in your tsconfig.json if you haven't already:
// In tsconfig.json
"include": [
...
"./jest-setup.ts"
],CommonJS and older versions of jest
In order to extend the matchers correctly in projects using CommonJS or older versions of jest it may be necessary to extend expect manually. This can be achieved with:
// In your own jest-setup.js (or any other name e.g. setupTests.js)
import * as matchers from 'jest-a11y/lib/matchers'
expect.extend(matchers)Inspiration
As I have been working on different web projects, accessibility has started to become a major concern and product requirement, but it can be cumbersome to re-write the re-test the same functionality across multiple projects. As projects also started shifting to React Testing Library instead of Enzyme, it now became possible to test DOM output and keyboard navigation in unit tests.
Other Solutions
There's jest-axe which exports a single matcher and doesn't (yet) test any user interactions.
Issues
Looking to contribute? Look for the Good First Issue label.
🐛 Bugs
Please file an issue for bugs, missing documentation, or unexpected behavior.
💡 Feature Requests
Please file an issue to suggest new features. Vote on feature requests by adding a
LICENSE
MIT