Gathering detailed insights and metrics for jest-axe
Custom Jest matcher for aXe for testing accessibility ♿️🃏
Installations
npm install jest-axeDeveloper Guide
BETA
Typescript
No
Module System
CommonJS
Min. Node Version
>= 16.0.0
Node Version
20.14.0
NPM Version
10.7.0
Score
98
Supply Chain
98.2
Quality
76.7
Maintenance
100
Vulnerability
98.2
License
Releases
7
Contributors
25
Languages
1
JavaScript
JavaScript (100%)
Love this project? Help keep it running — sponsor us today! 🚀
Developer
nickcolley
Download Statistics
Total Downloads
84,685,917
Last Day
136,849
Last Week
185,431
Last Month
2,278,557
Last Year
29,102,938
GitHub Statistics
1,070 Stars
299 Commits
55 Forks
3 Watching
5 Branches
25 Contributors
Bundle Size
631.04 kB
Minified
172.81 kB
Minified + Gzipped
Maintainers
1
Package Meta Information
Latest Version
9.0.0
Package Id
jest-axe@9.0.0
Unpacked Size
20.48 kB
Size
6.85 kB
File Count
5
NPM Version
10.7.0
Node Version
20.14.0
Publised On
07 Jun 2024
Total Downloads
Cumulative downloads
Total Downloads
84,685,917
Last day
11.3%
136,849
Compared to previous day
Last week
-65.6%
185,431
Compared to previous week
Last month
14.2%
2,278,557
Compared to previous month
Last year
17.4%
29,102,938
Compared to previous year
Daily Downloads
Weekly Downloads
Monthly Downloads
Yearly Downloads
Versions
jest-axe
Custom Jest matcher for axe for testing accessibility
⚠️✋ This project does not guarantee that what you build is accessible.
The GDS Accessibility team found that only ~30% of issues are found by automated testing.
Tools like axe are similar to code linters such as eslint or stylelint: they can find common issues but cannot guarantee that what you build works for users.
You'll also need to:
- test your interface with the assistive technologies that real users use (see also WebAIM's survey results).
- include disabled people in user research.
Checks that do not work in jest-axe
Color contrast checks do not work in JSDOM so are turned off in jest-axe.
Installation:
1npm install --save-dev jest jest-axe jest-environment-jsdom
TypeScript users can install the community maintained types package:
1npm install --save-dev @types/jest-axe
Usage:
1/** 2 * @jest-environment jsdom 3 */ 4const { axe, toHaveNoViolations } = require('jest-axe') 5 6expect.extend(toHaveNoViolations) 7 8it('should demonstrate this matcher`s usage', async () => { 9 const render = () => '<img src="#"/>' 10 11 // pass anything that outputs html to axe 12 const html = render() 13 14 expect(await axe(html)).toHaveNoViolations() 15})
Note, you can also require
'jest-axe/extend-expect'which will callexpect.extendfor you. This is especially helpful when using the jestsetupFilesAfterEnvconfiguration.
Testing React
1const React = require('react') 2const { render } = require('react-dom') 3const App = require('./app') 4 5const { axe, toHaveNoViolations } = require('jest-axe') 6expect.extend(toHaveNoViolations) 7 8it('should demonstrate this matcher`s usage with react', async () => { 9 render(<App/>, document.body) 10 const results = await axe(document.body) 11 expect(results).toHaveNoViolations() 12})
Testing React with React Testing Library
1const React = require('react') 2const App = require('./app') 3 4const { render } = require('@testing-library/react') 5const { axe, toHaveNoViolations } = require('jest-axe') 6expect.extend(toHaveNoViolations) 7 8it('should demonstrate this matcher`s usage with react testing library', async () => { 9 const { container } = render(<App/>) 10 const results = await axe(container) 11 12 expect(results).toHaveNoViolations() 13})
Note: If you're using
react testing library<9.0.0 you should be using thecleanupmethod. This method removes the rendered application from the DOM and ensures a clean HTML Document for further testing.
If you're using React Portals, use the baseElement instead of container:
1it('should work with React Portals as well', async () => { 2 const { baseElement } = render(<App/>) 3 const results = await axe(baseElement) 4 5 expect(results).toHaveNoViolations() 6})
Testing Vue with Vue Test Utils
1const App = require('./App.vue') 2 3const { mount } = require('@vue/test-utils') 4const { axe, toHaveNoViolations } = require('jest-axe') 5expect.extend(toHaveNoViolations) 6 7it('should demonstrate this matcher`s usage with vue test utils', async () => { 8 const wrapper = mount(Image) 9 const results = await axe(wrapper.element) 10 11 expect(results).toHaveNoViolations() 12})
Testing Vue with Vue Testing Library
1const App = require('./app') 2 3const { render } = require('@testing-library/vue') 4const { axe, toHaveNoViolations } = require('jest-axe') 5expect.extend(toHaveNoViolations) 6 7it('should demonstrate this matcher`s usage with react testing library', async () => { 8 const { container } = render(<App/>) 9 const results = await axe(container) 10 11 expect(results).toHaveNoViolations() 12})
Note: If you're using
vue testing library<3.0.0 you should be using thecleanupmethod. This method removes the rendered application from the DOM and ensures a clean HTML Document for further testing.
Testing Angular with Nx
1import { ComponentFixture, TestBed } from "@angular/core/testing"; 2import { axe } from "jest-axe"; 3 4import { SomeComponent } from "./some.component"; 5 6describe("SomeComponent", () => { 7 let fixture: ComponentFixture<SomeComponent>; 8 9 beforeEach(() => { 10 TestBed.configureTestingModule({ 11 declarations: [SomeComponent], 12 }); 13 14 fixture = TestBed.createComponent(SomeComponent); 15 }); 16 17 it("should create", async () => { 18 const results = await axe(fixture.nativeElement); 19 expect(results).toHaveNoViolations(); 20 }); 21});
Note: You may need to extend jest by importing
jest-axe/extend-expectattest-setup.ts
Usage with jest.useFakeTimers() or mocking setTimeout
thrown: "Exceeded timeout of 5000 ms for a test. Use jest.setTimeout(newTimeout) to increase the timeout value, if this is a long-running test."
aXe core does not work when timers (setTimeout) are mocked. When using jest.useFakeTimers() aXe core will timeout often causing failing tests.
We recommend renabling the timers temporarily for aXe:
1jest.useRealTimers(); 2const results = await axe(wrapper.element); 3jest.useFakeTimers();
Axe configuration
The axe function allows options to be set with the same options as documented in axe-core:
1const { axe, toHaveNoViolations } = require('jest-axe') 2 3expect.extend(toHaveNoViolations) 4 5it('should demonstrate this matcher`s usage with a custom config', async () => { 6 const render = () => ` 7 <div> 8 <img src="#"/> 9 </div> 10 ` 11 12 // pass anything that outputs html to axe 13 const html = render() 14 15 const results = await axe(html, { 16 rules: { 17 // for demonstration only, don't disable rules that need fixing. 18 'image-alt': { enabled: false } 19 } 20 }) 21 22 expect(results).toHaveNoViolations() 23})
Testing isolated components
All page content must be contained by landmarks (region)
When testing with aXe sometimes it assumes you are testing a page. This then results in unexpected violations for landmarks for testing isolation components.
You can disable this behaviour with the region rule:
1const { configureAxe } = require('jest-axe') 2 3const axe = configureAxe({ 4 rules: { 5 // disable landmark rules when testing isolated components. 6 'region': { enabled: false } 7 } 8})
Setting global configuration
If you find yourself repeating the same options multiple times, you can export a version of the axe function with defaults set.
Note: You can still pass additional options to this new instance; they will be merged with the defaults.
This could be done in Jest's setup step
1// Global helper file (axe-helper.js) 2const { configureAxe } = require('jest-axe') 3 4const axe = configureAxe({ 5 rules: { 6 // for demonstration only, don't disable rules that need fixing. 7 'image-alt': { enabled: false } 8 } 9}) 10 11module.exports = axe
1// Individual test file (test.js) 2const { toHaveNoViolations } = require('jest-axe') 3const axe = require('./axe-helper.js') 4 5expect.extend(toHaveNoViolations) 6 7it('should demonstrate this matcher`s usage with a default config', async () => { 8 const render = () => ` 9 <div> 10 <img src="#"/> 11 </div> 12 ` 13 14 // pass anything that outputs html to axe 15 const html = render() 16 17 expect(await axe(html)).toHaveNoViolations() 18})
Setting custom rules and checks.
The configuration object passed to configureAxe, accepts a globalOptions property to configure the format of the data used by axe and to add custom checks and rules. The property value is the same as the parameter passed to axe.configure.
1// Global helper file (axe-helper.js) 2const { configureAxe } = require('jest-axe') 3 4const axe = configureAxe({ 5 globalOptions: { 6 checks: [/* custom checks definitions */] 7 }, 8 // ... 9}) 10 11module.exports = axe
Setting the level of user impact.
An array which defines which impact level should be considered. This ensures that only violations with a specific impact on the user are considered. The level of impact can be "minor", "moderate", "serious", or "critical".
1// Global helper file (axe-helper.js) 2const { configureAxe } = require('jest-axe') 3 4const axe = configureAxe({ 5 impactLevels: ['critical'], 6 // ... 7}) 8 9module.exports = axe
Refer to Developing Axe-core Rules for instructions on how to develop custom rules and checks.
Thanks
- Jest for the great test runner that allows extending matchers.
- axe for the wonderful axe-core that makes it so easy to do this.
- Government Digital Service for making coding in the open the default.
- GOV.UK Publishing Frontend team who published the basis of the aXe reporter
- jest-image-snapshot for inspiration on README and repo setup
No vulnerabilities found.
Reason
no dangerous workflow patterns detected
Reason
no binaries found in the repo
Reason
license file detected
Details
- Info: project has a license file: LICENSE.txt:0
- Info: FSF or OSI recognized license: MIT License: LICENSE.txt:0
Reason
4 existing vulnerabilities detected
Details
- Warn: Project is vulnerable to: GHSA-3xgq-45jj-v275
- Warn: Project is vulnerable to: GHSA-952p-6rrq-rcjv
- Warn: Project is vulnerable to: GHSA-mwcw-c2x4-8c55
- Warn: Project is vulnerable to: GHSA-3h5v-q93c-6h6q
Reason
dependency not pinned by hash detected -- score normalized to 3
Details
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/test.yml:22: update your workflow using https://app.stepsecurity.io/secureworkflow/NickColley/jest-axe/test.yml/main?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/test.yml:24: update your workflow using https://app.stepsecurity.io/secureworkflow/NickColley/jest-axe/test.yml/main?enable=pin
- Info: 0 out of 2 GitHub-owned GitHubAction dependencies pinned
- Info: 1 out of 1 npmCommand dependencies pinned
Reason
Found 3/13 approved changesets -- score normalized to 2
Reason
detected GitHub workflow tokens with excessive permissions
Details
- Warn: no topLevel permission defined: .github/workflows/test.yml:1
- Info: no jobLevel write permissions found
Reason
0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0
Reason
no effort to earn an OpenSSF best practices badge detected
Reason
security policy file not detected
Details
- Warn: no security policy file detected
- Warn: no security file to analyze
- Warn: no security file to analyze
- Warn: no security file to analyze
Reason
project is not fuzzed
Details
- Warn: no fuzzer integrations found
Reason
SAST tool is not run on all commits -- score normalized to 0
Details
- Warn: 0 commits out of 23 are checked with a SAST tool
Score
3.8
/10
Last Scanned on 2025-02-03
The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.
Learn More