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:

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.

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.

Yes. It works with either of those tools.

Table of Contents

• Installation
• Usage
  • Known Issues
• Inspiration
• Other Solutions
• Issues
  • 🐛 Bugs
  • 💡 Feature Requests
• LICENSE

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-a11y

With yarn:

yarn add -D jest-a11y

Usage

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

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.

• File a bug
• See existing bugs

💡 Feature Requests

Please file an issue to suggest new features. Vote on feature requests by adding a 👍. This helps maintainers prioritize what to work on.

See Feature Requests

LICENSE

MIT