jest-axe

What is jest-axe?

jest-axe is a Jest matcher for aXe for testing accessibility. It allows developers to integrate accessibility checks into their Jest test suites, ensuring that their web applications meet accessibility standards.

What are jest-axe's main functionalities?

Accessibility Testing

This feature allows you to test for accessibility violations in your HTML. The code sample demonstrates how to use jest-axe to check if a rendered HTML string has any accessibility violations.

const { axe, toHaveNoViolations } = require('jest-axe');
expect.extend(toHaveNoViolations);

test('should demonstrate this matcher`s usage', async () => {
  const render = () => '<img src="#" alt="test" />';
  const html = render();
  const results = await axe(html);
  expect(results).toHaveNoViolations();
});

Other packages similar to jest-axe

axe-core

axe-core is the underlying library used by jest-axe for accessibility testing. It provides a comprehensive set of rules for accessibility checks and can be used directly in various environments, including Node.js and browsers. Compared to jest-axe, axe-core is more low-level and requires more setup to integrate with testing frameworks.

cypress-axe

cypress-axe is a plugin for Cypress that allows you to run aXe accessibility checks within your Cypress end-to-end tests. It is similar to jest-axe but is designed for use with Cypress instead of Jest, making it suitable for integration and end-to-end testing rather than unit testing.

pa11y

pa11y is an accessibility testing tool that can be used to run automated accessibility tests on web pages. It provides a command-line interface and can be integrated into CI/CD pipelines. While jest-axe is focused on Jest integration, pa11y offers a broader range of usage scenarios, including command-line usage and integration with other testing frameworks.

README

jest-axe

Custom Jest matcher for aXe for testing accessibility

⚠️✋ This project does not guarantee 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 sass-lint: they can find 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 (see also WebAIM's survey results).
• include people with disabilities in user research.

Installation:

npm install --save-dev jest-axe

Usage:

const { axe, toHaveNoViolations } = require('jest-axe')

expect.extend(toHaveNoViolations)

it('should demonstrate this matcher`s usage', async () => {
  const render = () => '<img src="#"/>'

  // pass anything that outputs html to axe
  const html = render()

  expect(await axe(html)).toHaveNoViolations()
})

Note, you can also require 'jest-axe/extend-expect' which will call expect.extend for you. This is especially helpful when using the jest setupTestFrameworkScriptFile configuration.

With React

const { axe, toHaveNoViolations } = require('jest-axe')

expect.extend(toHaveNoViolations)

const React = require('react')
const ReactDOMServer = require('react-dom/server')

it('should demonstrate this matcher`s usage with react', async () => {
  const html = ReactDOMServer.renderToString(
    <img src='#' />
  )

  const results = await axe(html)

  expect(results).toHaveNoViolations()
})

Axe configuration

The axe function allows options to be set with the same options as documented in axe-core:

const { axe, toHaveNoViolations } = require('jest-axe')

expect.extend(toHaveNoViolations)

it('should demonstrate this matcher`s usage with a custom config', async () => {
  const render = () => `
    <div>
      <img src="#"/>
    </div>
  `

  // pass anything that outputs html to axe
  const html = render()

  const results = await axe(html, {
    rules: {
      // for demonstration only, don't disable rules that need fixing.
      'image-alt': { enabled: false }
    }
  })

  expect(results).toHaveNoViolations()
})

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

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

// Individual test file (test.js)
const { toHaveNoViolations } = require('jest-axe')
const axe = require('./axe-helper.js')

expect.extend(toHaveNoViolations)

it('should demonstrate this matcher`s usage with a default config', async () => {
  const render = () => `
    <div>
      <img src="#"/>
    </div>
  `

  // pass anything that outputs html to axe
  const html = render()

  expect(await axe(html)).toHaveNoViolations()
})

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

Changelog

3.1.0

• Add extend-expect file - (PR #44) Thanks @kentcdodds
• Update axe-core to v3.1.1, update jest-matcher-utils to 23.5.0