Custom Jest matcher for aXe for testing accessibility
npm install jest-axebash
npm install --save-dev jest jest-axe jest-environment-jsdom
`
TypeScript users can install the community maintained types package:
`bash
npm install --save-dev @types/jest-axe
`
Usage:
`javascript
/**
* @jest-environment jsdom
*/
const { axe, toHaveNoViolations } = require('jest-axe')
expect.extend(toHaveNoViolations)
it('should demonstrate this matchers usage', async () => {
!Screenshot of the resulting output from the usage example
> Note, you can also require 'jest-axe/extend-expect' which will call expect.extend for you.
> This is especially helpful when using the jest setupFilesAfterEnv configuration.
$3
`javascript
const React = require('react')
const { render } = require('react-dom')
const App = require('./app')
const { axe, toHaveNoViolations } = require('jest-axe')
expect.extend(toHaveNoViolations)
it('should demonstrate this matchers usage with react', async () => {
$3
`javascript
const React = require('react')
const App = require('./app')
const { render } = require('@testing-library/react')
const { axe, toHaveNoViolations } = require('jest-axe')
expect.extend(toHaveNoViolations)
it('should demonstrate this matchers usage with react testing library', async () => {
> Note: If you're using react testing library <9.0.0 you should be using the
> cleanup method. 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:
`js
it('should work with React Portals as well', async () => {
const { baseElement } = render( )
const results = await axe(baseElement)
expect(results).toHaveNoViolations()
})
`
$3
`javascript
const App = require('./App.vue')
const { mount } = require('@vue/test-utils')
const { axe, toHaveNoViolations } = require('jest-axe')
expect.extend(toHaveNoViolations)
it('should demonstrate this matchers usage with vue test utils', async () => {
$3
`javascript
const App = require('./app')
const { render } = require('@testing-library/vue')
const { axe, toHaveNoViolations } = require('jest-axe')
expect.extend(toHaveNoViolations)
it('should demonstrate this matchers usage with react testing library', async () => {
> Note: If you're using vue testing library <3.0.0 you should be using the
> cleanup method. This method removes the rendered application from the DOM and ensures a clean HTML Document for further testing.
$3
`typescript
import { ComponentFixture, TestBed } from "@angular/core/testing";
import { axe } from "jest-axe";
import { SomeComponent } from "./some.component";
describe("SomeComponent", () => {
let fixture: ComponentFixture;
beforeEach(() => {
TestBed.configureTestingModule({
declarations: [SomeComponent],
});
fixture = TestBed.createComponent(SomeComponent);
});
it("should create", async () => {
const results = await axe(fixture.nativeElement);
expect(results).toHaveNoViolations();
});
});
`
> Note: You may need to extend jest by importing jest-axe/extend-expect at test-setup.ts
$3
> 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:
`javascript
jest.useRealTimers();
const results = await axe(wrapper.element);
jest.useFakeTimers();
`
$3
The axe function allows options to be set with the same options as documented in axe-core:
`javascript
const { axe, toHaveNoViolations } = require('jest-axe')
expect.extend(toHaveNoViolations)
it('should demonstrate this matchers usage with a custom config', async () => {
$3
> 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:
`javascript
const { configureAxe } = require('jest-axe')
const axe = configureAxe({
rules: {
// disable landmark rules when testing isolated components.
'region': { enabled: false }
}
})
`
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
`javascript
// Global helper file (axe-helper.js)
const { configureAxe } = require('jest-axe')
const axe = configureAxe({
rules: {
// for demonstration only, don't disable rules that need fixing.
'image-alt': { enabled: false }
}
})
module.exports = axe
`
`javascript
// Individual test file (test.js)
const { toHaveNoViolations } = require('jest-axe')
const axe = require('./axe-helper.js')
expect.extend(toHaveNoViolations)
it('should demonstrate this matchers usage with a default config', async () => {
$3
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.
`javascript
// Global helper file (axe-helper.js)
const { configureAxe } = require('jest-axe')
const axe = configureAxe({
globalOptions: {
checks: [/ custom checks definitions /]
},
// ...
})
module.exports = axe
`
$3
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".
`javascript
// Global helper file (axe-helper.js)
const { configureAxe } = require('jest-axe')
const axe = configureAxe({
impactLevels: ['critical'],
// ...
})
module.exports = axe
``