Command line interface for running axe-core accessibility tests on your Storybook stories.

If there are any violations, information about them will be printed, and the command will exit with a non-zero exit code. That way, you can use this as automated accessibility tests on CI.

• Code of conduct
• Minimum requirements
• Installation
• Usage
• Options
• Story parameters
  • disabledRules
  • mode
  • runOptions
  • context
  • config
  • skip
  • timeout
  • waitForSelector (deprecated)
• TypeScript
• Developing
• Security
• Inspiration

This project adheres to the Contributor Covenant code of conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to [email protected].

• Node 18
• Storybook 7.0 or 8.0 (for Storybook 6, use axe-storybook-testing v6.3.1)
• axe-core 4.0

# via npm
npm install --save-dev @chanzuckerberg/axe-storybook-testing

# or with Yarn
yarn add --dev @chanzuckerberg/axe-storybook-testing

To use:

1. Add a script that creates a storybook build and then executes the axe-storybook command

   // In package.json
   "scripts": {
     "test:axe": "storybook build && axe-storybook"
   },

2. Run the tests by calling the script from the previous step

   npm run test:axe

3. (Optional) Install more browsers. By default Chromium is installed. If you want to also use Firefox and/or Safari, install them with:

   npx playwright install

The command-line interface has the following options:

For example, to run non-headlessly in Firefox, you would run

# If using npm
npm run storybook:axe -- --headless false --browser firefox

# or, if using Yarn
yarn storybook:axe --headless false --browser firefox

Stories can use parameters to configure how axe-storybook-testing handles them.

You can provide these wherever Storybook accepts parameters (story, component, or global).

Prevent axe-storybook-testing from running specific Axe rules on a story by using the disabledRules parameter.

// SomeComponent.stories.jsx

export const SomeStory = {
  parameters: {
    axe: {
      disabledRules: ['select-name'],
    },
  }.
};

Rules can also be disabled globally by setting this parameter for all stories in .storybook/preview.js.

// .storybook/preview.js

export const parameters = {
  axe: {
    disabledRules: ['select-name'],
  },
};

Set whether errors for a story will fail the test suite or not.

Valid options are:

• off - the story will be skipped and axe will not run on it. This is the same as setting skip: true.
• warn - axe errors will be printed, but won't fail the test suite. Stories with this set will show up as pending.
• error (default) - axe errors will fail the test suite for a story.

// .storybook/preview.js

export const parameters = {
  axe: {
    mode: 'warn',
  },
};

Allows use of any of the available axe.run options. See the link for more details. When using runOptions.rules in combination with disabledRules, disabledRules will always take precedent.

export const SomeStory = {
  parameters: {
    axe: {
      runOptions: {
        preload: true,
        selectors: true,
        ...
      }
    }
  }
}

Axe context, which is passed to axe.run. Useful for including or excluding elements from the tests.

export const SomeStory = {
  parameters: {
    axe: {
      context: {
        exclude: '.foo',
      },
    }
  }
}

Axe configuration, which is passed to axe.configure.

export const SomeStory = {
  parameters: {
    axe: {
      config: {
        checks: [...],
        ...
      }
    }
  }
}

Prevent axe-storybook-testing from running a story by using the skip parameter. This is shorthand for setting mode: 'off'.

// SomeComponent.stories.jsx

export const SomeStory = {
  parameters: {
    axe: {
      skip: true,
    },
  },
};

Overrides global --timeout for this specific test

// SomeComponent.stories.jsx

export const SomeStory = {
  parameters: {
    axe: {
      timeout: 5000,
    },
  },
};

Deprecated!

Legacy way of waiting for a selector before running Axe.

Now we recommend using a Storybook play function to do the same thing.

// SomeComponent.stories.jsx

// Old, deprecated way.
export const SomeStory = {
  parameters: {
    axe: {
      waitForSelector: '#some-component-selector',
    },
  },
};

// New, better way using a play function - https://storybook.js.org/docs/react/writing-stories/play-function
SomeStory.play = async () => {
  await screen.findByText('some string');
};

axe-storybook-testing provides TypeScript types for the story parameters listed above. Story parameters can be type checked by augmenting Storybook's Parameter type:

// overrides.d.ts

import type { AxeParams } from '@chanzuckerberg/axe-storybook-testing';

declare module '@storybook/react' {
  // Augment Storybook's definition of Parameters so it contains valid options for axe-storybook-testing
  interface Parameters {
    axe?: AxeParams;
  }
}

Annotate your stories with the StoryObj type, and your parameters will be type-checked!

// SomeComponent.stories.ts

export const SomeStory: StoryObj<Args> = {
  parameters: {
    axe: {
      timeout: 5000,
    },
  },
};

If you want to work on this project or contribute back to it, see our wiki entry on Development setup.

To report security issues, see ./SECURITY.md.

This project was originally based on @percy/storybook.