Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/veiko/jest-a11y
✨ Custom Jest matchers for testing accessibility
https://github.com/veiko/jest-a11y
a11y a11y-testing jest testing testing-library
Last synced: 24 days ago
JSON representation
✨ Custom Jest matchers for testing accessibility
- Host: GitHub
- URL: https://github.com/veiko/jest-a11y
- Owner: veiko
- License: mit
- Created: 2022-09-10T01:18:06.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2023-01-03T14:07:28.000Z (about 2 years ago)
- Last Synced: 2024-12-30T05:57:29.072Z (about 2 months ago)
- Topics: a11y, a11y-testing, jest, testing, testing-library
- Language: TypeScript
- Homepage: https://veiko.github.io/jest-a11y/
- Size: 3.44 MB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
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](#installation)
- [Usage](#usage)
- [Known Issues](#known-issues)
- [Inspiration](#inspiration)
- [Other Solutions](#other-solutions)
- [Issues](#issues)
- [🐛 Bugs](#-bugs)
- [💡 Feature Requests](#-feature-requests)
- [LICENSE](#license)
## Installation
This module is distributed via [npm](https://www.npmjs.com) which is bundled with [node](https://www.nodejs.org) and should be installed as one of your project's `dependencies`:
With `npm`:
```sh
npm install --save-dev jest-a11y
```
With `yarn`:
```sh
yarn add -D jest-a11y
```
## Usage
```ts
// 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.
```jsx
describe('MyButtonComponent', () => {
it('passes when element is valid', async () => {
render(click me)
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:
```json
// 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:
```ts
// 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](https://github.com/nickcolley/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](https://github.com/veiko/jest-a11y/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) label._
### 🐛 Bugs
Please file an issue for bugs, missing documentation, or unexpected behavior.
- [**File a bug**](https://github.com/veiko/jest-a11y/issues/new?assignees=&labels=%F0%9F%90%9B+fix&template=bug_report.yml&title=fix%3A+)
- [**See existing bugs**](https://github.com/veiko/jest-a11y/labels/%F0%9F%90%9B%20fix)
### 💡 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**](https://github.com/veiko/jest-a11y/labels/%E2%9C%A8%20feature)
## LICENSE
MIT