mirror of
https://github.com/storybookjs/storybook.git
synced 2025-04-05 16:11:33 +08:00
157 lines
5.9 KiB
Markdown
157 lines
5.9 KiB
Markdown
---
|
||
title: 'Accessibility testing with Storybook'
|
||
---
|
||
|
||
Accessibility is the practice of making websites inclusive to all. That means supporting requirements such as: keyboard navigation, screen reader support, touch-friendly, usable color contrast, reduced motion, and zoom support.
|
||
|
||
Accessibility tests audit the rendered DOM against a set of heuristics based on [WCAG](https://www.w3.org/WAI/standards-guidelines/wcag/) rules and other industry-accepted best practices. They act as the first line of QA to catch blatant accessibility violations.
|
||
|
||
Storybook’s official [a11y addon](https://storybook.js.org/addons/@storybook/addon-a11y) runs accessibility audits while you’re developing components to give you a fast feedback loop. It's powered by Deque's [axe-core](https://github.com/dequelabs/axe-core), which automatically catches up to [57% of WCAG issues](https://www.deque.com/blog/automated-testing-study-identifies-57-percent-of-digital-accessibility-issues/).
|
||
|
||
|
||
|
||
### Setup a11y addon
|
||
|
||
To enable accessibility testing with Storybook, you'll need to install the [`@storybook/addon-a11y`](https://storybook.js.org/addons/@storybook/addon-a11y/) addon. Run the following command:
|
||
|
||
```shell
|
||
# With npm
|
||
npm install @storybook/addon-a11y --save-dev
|
||
|
||
# With yarn
|
||
yarn add --dev @storybook/addon-a11y
|
||
```
|
||
|
||
Update your Storybook configuration (in `.storybook/main.js`) to include the accessibility addon:
|
||
|
||
<!-- prettier-ignore-start -->
|
||
|
||
<CodeSnippets
|
||
paths={[
|
||
'common/storybook-a11y-register.js.mdx',
|
||
]}
|
||
/>
|
||
|
||
<!-- prettier-ignore-end -->
|
||
|
||
Start your Storybook, and you will see some noticeable differences in the UI. A new toolbar icon and the accessibility panel where you can inspect the results of the tests.
|
||
|
||
<video autoPlay muted playsInline loop>
|
||
<source
|
||
src="storybook-a11y-starter-setup-optimized.mp4"
|
||
type="video/mp4"
|
||
/>
|
||
</video>
|
||
|
||
### How it works
|
||
|
||
Storybook's a11y addon runs [Axe](https://github.com/dequelabs/axe-core) on the selected story. Allowing you to catch and fix accessibility issues during development. For example, if you’re working on a button component and included the following set of stories:
|
||
|
||
<!-- prettier-ignore-start -->
|
||
|
||
<CodeSnippets
|
||
paths={[
|
||
'common/component-story-with-accessibility.js.mdx',
|
||
]}
|
||
/>
|
||
|
||
<!-- prettier-ignore-end -->
|
||
|
||
Cycling through both stories, you will see that the `Inaccessible` story contains some issues that need fixing. Opening the violations tab in the accessibility panel provides a clear description of the accessibility issue and guidelines for solving it.
|
||
|
||
|
||
|
||
### Configure
|
||
|
||
Out of the box, Storybook's accessibility addon includes a set of accessibility rules that cover most issues. You can also fine tune the [addon configuration](https://github.com/storybookjs/storybook/tree/next/addons/a11y#parameters) or override [Axe's ruleset](https://github.com/storybookjs/storybook/tree/next/addons/a11y#handling-failing-rules) to best suit your needs.
|
||
|
||
#### Global a11y configuration
|
||
|
||
If you need to dismiss an accessibility rule or modify its settings across all stories, you can add the following to your [storybook/preview.js](../configure/overview.md#configure-story-rendering):
|
||
|
||
<!-- prettier-ignore-start -->
|
||
|
||
<CodeSnippets
|
||
paths={[
|
||
'common/storybook-addon-a11y-global-config.js.mdx',
|
||
]}
|
||
/>
|
||
|
||
<!-- prettier-ignore-end -->
|
||
|
||
#### Component-level a11y configuration
|
||
|
||
You can also customize your own set of rules for all stories of a component. Update your story's default export and add a parameter with the required configuration:
|
||
|
||
<!-- prettier-ignore-start -->
|
||
|
||
<CodeSnippets
|
||
paths={[
|
||
'common/storybook-addon-a11y-component-config.js.mdx',
|
||
]}
|
||
/>
|
||
|
||
<!-- prettier-ignore-end -->
|
||
|
||
#### Story-level a11y configuration
|
||
|
||
Customize the a11y ruleset at the story level by updating your story to include a new parameter
|
||
|
||
<!-- prettier-ignore-start -->
|
||
|
||
<CodeSnippets
|
||
paths={[
|
||
'common/storybook-addon-a11y-story-config.js.mdx',
|
||
]}
|
||
/>
|
||
|
||
<!-- prettier-ignore-end -->
|
||
|
||
#### How to disable a11y tests
|
||
|
||
Disable accessibility testing for stories or components by adding the following parameter to your story’s export or component’s default export respectively:
|
||
|
||
<!-- prettier-ignore-start -->
|
||
|
||
<CodeSnippets
|
||
paths={[
|
||
'common/storybook-addon-a11y-disable.js.mdx',
|
||
]}
|
||
/>
|
||
|
||
<!-- prettier-ignore-end -->
|
||
|
||
## Automate accessibility tests with Jest
|
||
|
||
Accessibility testing with Storybook shortens the feedback loop which means you fix issues faster. Reuse stories in a Jest test and run an accessibility audit on them using the the [jest-axe integration](https://github.com/nickcolley/jest-axe). That also unlocks the ability to integrate accessibility tests into your functional testing pipeline.
|
||
|
||
For example, include the following test file to run an accessibility test on a story:
|
||
|
||
<!-- prettier-ignore-start -->
|
||
|
||
<CodeSnippets
|
||
paths={[
|
||
'common/accessibility-testing-with-jest-axe.js.mdx',
|
||
]}
|
||
/>
|
||
|
||
<!-- prettier-ignore-end -->
|
||
|
||
When you execute your test script, it will run the accessibility audit along with any interaction tests you might have.
|
||
|
||
|
||
|
||
---
|
||
|
||
#### What’s the difference between browser-based and linter-based accessibility tests?
|
||
|
||
Browser-based accessibility tests, like found in Storybook, evaluates the rendered DOM because that gives you the highest accuracy. Auditing code that hasn't been compiled yet is one step removed from the real thing so you won't catch everything the user might experience.
|
||
|
||
#### Learn about other UI tests
|
||
|
||
- [Visual tests](./visual-testing.md) for appearance
|
||
- Accessibility tests for accessibility
|
||
- [Interaction tests](./interaction-testing.md) for user behavior simulation
|
||
- [Snapshot tests](./snapshot-testing.md) for rendering errors and warnings
|
||
- [Import stories in other tests](./importing-stories-in-tests.md) for other tools
|