@chanzuckerberg/axe-storybook
Command-line interface for running accessibility checks via 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.
Originally based on @percy/storybook.
Project goals
These will be used to determine development work and direction, and triage bugs and pull requests.
- Run axe-core on Storybook stories written in Component Story Format.
- Be human readable on local machines (in other words, useful outside of a CI).
- Have reasonable performance. It doesn't have to maximize speed in every possible way, but needs to be fast enough that people will actually use it.
- Allow configuration of axe rules, so that people can fit the tool to their needs.
Installation
First, install the package
# via npm
npm install --save-dev @chanzuckerberg/axe-storybook
# or, if using Yarn
yarn add --dev @chanzuckerberg/axe-storybook
Second, add a script to your package.json that executes Storybook's build-storybook
command and runs axe-storybook
// In package.json
"scripts": {
"storybook:axe": "build-storybook && axe-storybook"
},
Usage
Assuming you've added the script in the install section above, you'll run this application 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. |
--headless |
true |
boolean | Whether to run headlessly or not. |
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 handles them.
disabled
Prevent axe-storybook from running a story by using the disabled
parameter.
SomeStory.parameters = {
axe: {
disabled: true,
},
};
disabledRules
Prevent axe-storybook from running specific Axe rules on a story by using the disabledRules
parameter.
SomeStory.parameters = {
axe: {
disabledRules: ['select-name'],
},
};