@chanzuckerberg/axe-storybook-testing

@chanzuckerberg/axe-storybook-testing

Command line interface for running accessibility tests (using axe-core) 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.

Table of contents

• Minimum requirements
• Installation
• Usage
• Options
• Configuring stories
  • skip
  • disabledRules
• Developing
• Inspiration

Minimum requirements

• Node 12
• Storybook 6.4 (for previous versions of Storybook, use axe-storybook-testing v4.1.3)
• axe-core 4.0

Installation

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

# or, if using Yarn
yarn add --dev @chanzuckerberg/axe-storybook-testing

Usage

This package works by analyzing the static files that Storybook produces. Therefore, Storybook's build command must be ran first.

To make this as easy as possible to use, we recommend adding a script to your package.json that builds Storybook and then executes the axe-storybook command.

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

Then you can run the tests with

# If using npm
npm run storybook:axe

# or, if using Yarn
yarn storybook:axe

Options

The command-line interface has the following options.

Option	Default	Type	Description
--browser	chromium	chromium, firefox, or webkit	Which browser to run the tests in
--build-dir	storybook-static	string	Storybook static build directory
--storybook-address		string	Storybook server address to test against instead of using a static build directory. If set, --build-dir will be ignored. e.g. --storybook-address http://localhost:6006
--failing-impact	all	minor, moderate, serious, critical, or all	The lowest impact level that should be considered a failure
--format	spec	string	Format to output test data in. Right now the only option is "spec"
--headless	true	boolean	Whether to run headlessly or not
--pattern	.*	string regex	Only run tests that match a component name pattern
--timeout	2000	number	Timeout (in milliseconds) for each test

For example, to run non-headlessly on 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

Configuring stories

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

skip

Prevent axe-storybook-testing from running a story by using the skip parameter.

// SomeComponent.stories.jsx

SomeStory.parameters = {
  axe: {
    skip: true,
  },
};

disabledRules

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

// SomeComponent.stories.jsx

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'],
  },
};

waitForSelector

Wait for an arbitrary CSS selector after rendering before running the Axe checks. Useful if your component takes some time to render and actually display itself on the page.

// SomeComponent.stories.jsx

export const parameters = {
  axe: {
    waitForSelector: '#some-component-selector',
  },
};

Developing

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

Inspiration

This project was originally based on @percy/storybook.