jest-axe
    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/jest-axe package

    5.0.1 • Public • Published

    jest-axe

    npm version node Repository CI Status JavaScript Style Guide

    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 stylelint: they can find common issues but cannot guarantee what you build works for users.

    You'll also need to:

    Installation:

    npm install --save-dev jest-axe

    TypeScript users can install the community maintained types package:

    npm install --save-dev @types/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()
    })

    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.

    Testing React

    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 matcher`s usage with react', async () => {
      render(<App/>, document.body)
      const results = await axe(document.body)
      expect(results).toHaveNoViolations()
    })

    Testing React with Enzyme

    const React = require('react')
    const App = require('./app')
    
    const { mount } = require('enzyme')
    const { axe, toHaveNoViolations } = require('jest-axe')
    expect.extend(toHaveNoViolations)
    
    it('should demonstrate this matcher`s usage with enzyme', async () => {
      const wrapper = mount(<App/>)
      const results = await axe(wrapper.getDOMNode())
      
      expect(results).toHaveNoViolations()
    })

    Testing React with React Testing Library

    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 matcher`s usage with react testing library', async () => {
      const { container } = render(<App/>)
      const results = await axe(container)
      
      expect(results).toHaveNoViolations()
    })

    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:

    it('should work with React Portals as well', async () => {
      const { baseElement } = render(<App/>)
      const results = await axe(baseElement)
      
      expect(results).toHaveNoViolations()
    })

    Testing Vue with Vue Test Utils

    const App = require('./App.vue')
    
    const { mount } = require('@vue/test-utils')
    const { axe, toHaveNoViolations } = require('jest-axe')
    expect.extend(toHaveNoViolations)
    
    it('should demonstrate this matcher`s usage with vue test utils', async () => {
      const wrapper = mount(Image)
      const results = await axe(wrapper.element)
    
      expect(results).toHaveNoViolations()
    })

    Testing Vue with Vue Testing Library

    const App = require('./app')
    
    const { render } = require('@testing-library/vue')
    const { axe, toHaveNoViolations } = require('jest-axe')
    expect.extend(toHaveNoViolations)
    
    it('should demonstrate this matcher`s usage with react testing library', async () => {
      const { container } = render(<App/>)
      const results = await axe(container)
      
      expect(results).toHaveNoViolations()
    })

    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.

    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()
    })

    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.

    // Global helper file (axe-helper.js)
    const { configureAxe } = require('jest-axe')
    
    const axe = configureAxe({
      globalOptions: {
        checks: [/* custom checks definitions */]
      },
      // ...
    })
    
    module.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".

    // Global helper file (axe-helper.js)
    const { configureAxe } = require('jest-axe')
    
    const axe = configureAxe({
      impactLevels: ['critical'],
      // ...
    })
    
    module.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.
    • jest-image-snapshot for inspiration on README and repo setup

    Install

    npm i jest-axe

    DownloadsWeekly Downloads

    158,207

    Version

    5.0.1

    License

    MIT

    Unpacked Size

    21.5 kB

    Total Files

    6

    Last publish

    Collaborators

    • nickcolley