@chanzuckerberg/axe-storybook-testing
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.
Table of contents
Code of conduct
This project adheres to the Contributor Covenant code of conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to opensource@chanzuckerberg.com.
Minimum requirements
- Node 18
- Storybook 7.0 or 8.0 (for Storybook 6, use axe-storybook-testing v6.3.1)
- axe-core 4.0
Installation
npm install --save-dev @chanzuckerberg/axe-storybook-testing
yarn add --dev @chanzuckerberg/axe-storybook-testing
Usage
To use:
-
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"
},
-
Run the tests by calling the script from the previous step
npm run test:axe
-
(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
Options
The command-line interface has the following options:
Option | Default | Values | Description |
---|
--browser | chromium | chromium, firefox, webkit | Which browser to run the tests |
--build-dir | storybook-static | path | Storybook static build directory |
--failing-impact | all | all, minor, moderate, serious, critical | The lowest impact level that should be considered a failure |
--headless | true | boolean | Whether to run headlessly or not |
--pattern | .* | regex pattern | Only run tests that match a component name pattern |
--reporter | spec | spec, dot, nyan, tap, landing, list, progress, json, json-stream, min, doc, markdown, xunit | How to display the test run. Can be any built-in Mocha reporter. |
--reporter-options | | string | Options to pass to the mocha reporter. Especially useful with the xunit reporter - e.g. --reporter-options output=./filename.xml |
--storybook-address | | url | Deprecated! Use --storybook-url instead. |
--storybook-url | | url | Url to a running Storybook to test against. Alternative to --build-dir , which will be ignored if this is set. |
--timeout | 2000 | number | Deprecated! Use the timeout story parameter instead. |
For example, to run non-headlessly in Firefox, you would run
npm run storybook:axe -- --headless false --browser firefox
yarn storybook:axe --headless false --browser firefox
Story parameters
Stories can use parameters to configure how axe-storybook-testing handles them.
You can provide these wherever Storybook accepts parameters (story, component, or global).
disabledRules
Prevent axe-storybook-testing from running specific Axe rules on a story by using the disabledRules
parameter.
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.
export const parameters = {
axe: {
disabledRules: ['select-name'],
},
};
mode
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.
export const parameters = {
axe: {
mode: 'warn',
},
};
runOptions
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,
...
}
}
}
}
config
Axe configuration, which is passed to axe.configure.
export const SomeStory = {
parameters: {
axe: {
config: {
checks: [...],
...
}
}
}
}
skip
Prevent axe-storybook-testing from running a story by using the skip
parameter. This is shorthand for setting mode: 'off'
.
export const SomeStory = {
parameters: {
axe: {
skip: true,
},
},
};
timeout
Overrides global --timeout
for this specific test
export const SomeStory = {
parameters: {
axe: {
timeout: 5000,
},
},
};
waitForSelector
Deprecated!
Legacy way of waiting for a selector before running Axe.
Now we recommend using a Storybook play function to do the same thing.
export const SomeStory = {
parameters: {
axe: {
waitForSelector: '#some-component-selector',
},
},
};
SomeStory.play = async () => {
await screen.findByText('some string');
};
TypeScript
axe-storybook-testing provides TypeScript types for the story parameters listed above.
Story parameters can be type checked by augmenting Storybook's Parameter
type:
import type { AxeParams } from '@chanzuckerberg/axe-storybook-testing';
declare module '@storybook/react' {
interface Parameters {
axe?: AxeParams;
}
}
Annotate your stories with the StoryObj
type, and your parameters will be type-checked!
export const SomeStory: StoryObj<Args> = {
parameters: {
axe: {
timeout: 5000,
},
},
};
Developing
If you want to work on this project or contribute back to it, see our wiki entry on Development setup.
Security
To report security issues, see ./SECURITY.md.
Inspiration
This project was originally based on @percy/storybook.