Skip to main content

 jest-a11y

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.

Overview​

The matchers provided by this project aim to assist developers in maintaining a baseline of accessibility features for UI components.

The jest-a11y matchers can work with any library or framework that returns DOM elements from queries.

Installation​

Inside your project directory, install jest-a11y by running either of the following:

yarn add -D jest-a11y

Import jest-a11y once (for instance in your tests setup file) and you're good to go:

// In your own jest-setup.js (or any other name)
import 'jest-a11y'

// In jest.config.js add (if you haven't already)
setupFilesAfterEnv: ['<rootDir>/jest-setup.js']

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"
  ],

You're ready to start using jest-a11y matchers in your tests:

import { screen } from '@testing-library/dom'

test('uses jest-a11y', () => {
  document.body.innerHTML = '<button>click me</button>'

  expect(screen.queryByRole('button')).toBeAccessibleButton()
})
This project does not guarantee what you build is accessible.

This tool may help you identify common issues but cannot guarantee what you build works for users. You'll also need to test your interface with the assistive technologies that real users use.