Storybook · Writing and testing · all subjects

accessibility testing

25 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Accessibility test parameter values: off, todo, error

The parameters.a11y.test parameter accepts three values: 'off' (do not run accessibility tests, manual verification via addon panel still available), 'todo' (run tests and return warnings in Storybook UI), 'error' (run tests and return failing test in Storybook UI and CLI/CI).

Accessibility addon built on axe-core library

Storybook's Accessibility (a11y) addon is built on top of Deque's axe-core library, which automatically catches up to 57% of WCAG issues.

Install accessibility addon with Storybook CLI

Run the `storybook add @storybook/addon-a11y` command to install and configure the Accessibility addon in your project.

Accessibility addon panel shows three result tabs

The Accessibility addon panel displays results in three sub-tabs: Violations (known WCAG rule violations and best practice violations), Passes (known non-violations), and Incomplete (areas to confirm manually because they could not be checked automatically).

Accessibility addon configuration parameters

The Accessibility addon accepts four configuration properties in parameters.a11y: 1) context (default: 'body') - defines which elements to run checks against; 2) config (default: see documentation) - configuration passed to axe.configure() for configuring individual rules; 3) options (default: {}) - options passed to axe.run() to adjust rulesets checked; 4) test (default: undefined) - determines test behavior with Vitest addon (values: 'off', 'todo', 'error'). Additionally, globals.a11y.manual (default: undefined) set to true prevents stories from being automatically analyzed.

Default accessibility addon config disables region rule

By default, the Accessibility addon disables the region rule because it does not typically apply to components in stories and can lead to false negatives. The default config is: { rules: [{ id: 'region', enabled: false }] }

Accessibility tests use WCAG 2.0, 2.1 and best practices rulesets

By default, the Accessibility addon runs checks based on WCAG 2.0 Level A & AA Rules, WCAG 2.1 Level A & AA Rules, and Best Practices Rules from axe-core.

Change accessibility rulesets with runOnly option

To change which rules are checked (e.g., to check against WCAG 2.2 AA or WCAG 2.x AAA rules), use the runOnly option in the Accessibility addon configuration.

Configure accessibility tests at project, component, or story level

Accessibility configuration can be applied at three levels: project level in .storybook/preview.*, component level in the meta of a story file, or individual story level.

Todo value for marking known accessibility issues

The 'todo' value for parameters.a11y.test is intended to serve as a literal TODO in your codebase to mark stories with known accessibility issues that are not yet ready to fix, allowing you to track and address them later.

Exclude elements from accessibility checks with context

Define a custom context in Accessibility addon configuration to select which elements are included or excluded when running checks. For example, you can ignore elements with a specific class name.

Disable automated accessibility checks with globals.a11y.manual

Set globals.a11y.manual to true to prevent stories from being automatically analyzed when visited. You can still manually trigger checks in the Accessibility addon panel.

Run accessibility tests with Vitest addon in Storybook UI

To run accessibility tests with the Vitest addon in the Storybook UI: expand the testing widget in the sidebar, check the Accessibility checkbox, and press the Run component tests button. Results appear in the sidebar with test status indicators next to each tested story.

Accessibility tests in CI with Vitest addon

When using the Vitest addon, accessibility tests are run automatically in CI for stories with parameters.a11y.test set to 'error' when you run Vitest tests.

Run accessibility tests with test-runner

If using the test-runner, accessibility tests can be run in the terminal or CI environments. Tests are included when the Accessibility addon is installed and parameters.a11y.test is set to a value other than 'off'.

Debug accessibility violations with highlighting

Toggle on highlighting in the Storybook UI to see which elements are causing accessibility violations. Click on highlighted elements to see violation details in a popover menu.

Accessibility tests require error mode to fail in CI

Accessibility tests will only produce errors in CI if parameters.a11y.test is set to 'error'. If set to 'todo', there will be no accessibility-related errors or output in CI, but results are visible as warnings in the Storybook UI when run locally.

Progressive accessibility improvement workflow

Use accessibility configuration to progressively improve UI accessibility: 1) Set parameters.a11y.test to 'error' to fail on violations (ensures new stories meet standards), 2) Find components with failures, 3) Apply 'todo' to temporarily reduce failures to warnings, 4) Pick a component, fix issues using addon suggestions, remove the parameter, 5) Repeat until all components pass.

Browser-based accessibility tests evaluate rendered DOM

Browser-based accessibility tests, like those in Storybook, evaluate the rendered DOM for highest accuracy, rather than auditing uncompiled code.

Accessibility addon panel does not show violations for async components

Modern React components using asynchronous techniques like Suspense or React Server Components may not render their final UI immediately. Storybook does not inherently know when async components have fully rendered, so a11y checks sometimes run too early, leading to false negatives.

Enable developmentModeForBuild for async component accessibility testing

To address accessibility testing issues with async components, enable the developmentModeForBuild feature flag in .storybook/main.js|ts. This sets process.env.NODE_ENV to 'development' in built Storybooks, enabling React's act utility which ensures all updates are processed before making assertions like a11y checks.

Accessibility addon integrates with Vitest addon

The Accessibility addon is designed to integrate with the Vitest addon, allowing you to run accessibility tests alongside your component tests. Install the Vitest addon with the command that automatically configures both Vitest and the addon.

Enable individual accessibility rules with config parameter

Use parameters.a11y.config to enable, disable, or configure individual accessibility rules from axe-core.

Accessibility testing with A11y addon

Storybook's Accessibility (A11y) addon runs automated checks on stories to help ensure components can be used by all users. It checks keyboard navigation, screen reader support, usable color contrast, and other accessibility requirements. Activate accessibility checks by checking the Accessibility checkbox in the testing widget.

Test runner accessibility testing

When you have the Accessibility addon installed, you can run accessibility tests alongside your interaction tests using the test-runner. See the Accessibility testing documentation for configuration options.

Give your agent this brain