Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs updates for Storybook Test #30035

Open
wants to merge 1 commit into
base: next
Choose a base branch
from
+368 −99
Open

Docs updates for Storybook Test #30035

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions MIGRATION.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -427,12 +427,14 @@

### Addon-a11y: Component test integration

In Storybook 8.4, we introduced a new addon called [addon test](https://storybook.js.org/docs/writing-tests/test-addon). Powered by Vitest under the hood, this addon lets you watch, run, and debug your component tests directly in Storybook.
In Storybook 8.4, we introduced the [Test addon](https://storybook.js.org/docs/writing-tests/test-addon) (`@storybook/experimental-addon-test`). Powered by Vitest under the hood, this addon lets you watch, run, and debug your component tests directly in Storybook.

In Storybook 8.5, we revamped the Accessibility addon (`@storybook/addon-a11y`) to integrate it with the component tests feature. This means you can now extend your component tests to include accessibility tests. If you upgrade to Storybook 8.5 via `npx storybook@latest upgrade`, the Accessibility addon will be automatically configured to work with the component tests. However, if you're upgrading manually and you have the [addon test](https://storybook.js.org/docs/writing-tests/test-addon) installed, adjust your configuration as follows:
In Storybook 8.5, we revamped the [Accessibility addon](https://storybook.js.org/docs/writing-tests/accessibility-testing) (`@storybook/addon-a11y`) to integrate it with the component tests feature. This means you can now extend your component tests to include accessibility tests.

If you upgrade to Storybook 8.5 via `npx storybook@latest upgrade`, the Accessibility addon will be automatically configured to work with the component tests. However, if you're upgrading manually and you have the Test addon installed, adjust your configuration as follows:

```diff
// .storybook/vitest.config.ts
// .storybook/vitest.setup.ts
...
+import * as a11yAddonAnnotations from '@storybook/addon-a11y/preview';

Expand Down
2 changes: 2 additions & 0 deletions docs/_snippets/vitest-plugin-vitest-config-alias.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,8 @@ export default {
```

```js filename="vitest.config.ts" renderer="common" tabTitle="After"
import { defineConfig } from 'vitest/config';

export default defineConfig({
// ...
resolve: {
Expand Down
24 changes: 3 additions & 21 deletions docs/_snippets/vitest-plugin-vitest-config.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,6 @@ export default mergeConfig(
// storybookNextJsPlugin(),
],
test: {
// Glob pattern to find story files
include: ['src/**/*.stories.?(m)[jt]s?(x)'],
// Enable browser mode
browser: {
enabled: true,
Expand All @@ -28,13 +26,9 @@ export default mergeConfig(
provider: 'playwright',
headless: true,
},
// Speed up tests and better match how they run in Storybook itself
// https://vitest.dev/config/#isolate
// Consider removing this if you have flaky tests
isolate: false,
setupFiles: ['./.storybook/vitest.setup.ts'],
},
}),
})
);
```

Expand All @@ -57,8 +51,6 @@ export default mergeConfig(
storybookVuePlugin(),
],
test: {
// Glob pattern to find story files
include: ['src/**/*.stories.?(m)[jt]s?(x)'],
// Enable browser mode
browser: {
enabled: true,
Expand All @@ -67,13 +59,9 @@ export default mergeConfig(
provider: 'playwright',
headless: true,
},
// Speed up tests and better match how they run in Storybook itself
// https://vitest.dev/config/#isolate
// Consider removing this if you have flaky tests
isolate: false,
setupFiles: ['./.storybook/vitest.setup.ts'],
},
}),
})
);
```

Expand All @@ -97,8 +85,6 @@ export default mergeConfig(
// storybookSveltekitPlugin(),
],
test: {
// Glob pattern to find story files
include: ['src/**/*.stories.?(m)[jt]s?(x)'],
// Enable browser mode
browser: {
enabled: true,
Expand All @@ -107,12 +93,8 @@ export default mergeConfig(
provider: 'playwright',
headless: true,
},
// Speed up tests and better match how they run in Storybook itself
// https://vitest.dev/config/#isolate
// Consider removing this if you have flaky tests
isolate: false,
setupFiles: ['./.storybook/vitest.setup.ts'],
},
}),
})
);
```
18 changes: 0 additions & 18 deletions docs/_snippets/vitest-plugin-vitest-workspace.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,8 +20,6 @@ export default defineWorkspace([
],
test: {
name: 'storybook',
// Glob pattern to find story files
include: ['src/**/*.stories.?(m)[jt]s?(x)'],
// Enable browser mode
browser: {
enabled: true,
Expand All @@ -30,10 +28,6 @@ export default defineWorkspace([
provider: 'playwright',
headless: true,
},
// Speed up tests and better match how they run in Storybook itself
// https://vitest.dev/config/#isolate
// Consider removing this if you have flaky tests
isolate: false,
setupFiles: ['./.storybook/vitest.setup.ts'],
},
},
Expand Down Expand Up @@ -63,8 +57,6 @@ export default defineWorkspace([
],
test: {
name: 'storybook',
// Glob pattern to find story files
include: ['src/**/*.stories.?(m)[jt]s?(x)'],
// Enable browser mode
browser: {
enabled: true,
Expand All @@ -73,10 +65,6 @@ export default defineWorkspace([
provider: 'playwright',
headless: true,
},
// Speed up tests and better match how they run in Storybook itself
// https://vitest.dev/config/#isolate
// Consider removing this if you have flaky tests
isolate: false,
setupFiles: ['./.storybook/vitest.setup.ts'],
},
},
Expand Down Expand Up @@ -107,8 +95,6 @@ export default defineWorkspace([
],
test: {
name: 'storybook',
// Glob pattern to find story files
include: ['src/**/*.stories.?(m)[jt]s?(x)'],
// Enable browser mode
browser: {
enabled: true,
Expand All @@ -117,10 +103,6 @@ export default defineWorkspace([
provider: 'playwright',
headless: true,
},
// Speed up tests and better match how they run in Storybook itself
// https://vitest.dev/config/#isolate
// Consider removing this if you have flaky tests
isolate: false,
setupFiles: ['./.storybook/vitest.setup.ts'],
},
},
Expand Down
82 changes: 54 additions & 28 deletions docs/writing-tests/accessibility-testing.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,17 +67,17 @@ If you need to dismiss an accessibility rule or modify its settings across all s

#### Component-level a11y configuration

<IfRenderer renderer="svelte">
<If renderer="svelte">

You can also customize your own set of rules for all stories of a component. If you're using Svelte CSF with the native templating syntax, you can update the `defineMeta` function or the default export of the CSF story and provide the required configuration:
You can also customize your own set of rules for all stories of a component. If you're using Svelte CSF with the native templating syntax, you can update the `defineMeta` function. If you're using regular CSF, you can update the default export of the story file.

</IfRenderer>
</If>

<IfRenderer renderer={['angular', 'vue', 'web-components', 'ember', 'html', 'react', 'preact', 'qwik', 'solid']}>
<If notRenderer={['svelte']}>

You can also customize your own set of rules for all stories of a component. Update your story's default export and add parameters and globals with the required configuration:
You can also customize your own set of rules for all stories of a component. Update the story file's default export and add parameters and globals with the required configuration:

</IfRenderer>
</If>

{/* prettier-ignore-start */}

Expand All @@ -97,17 +97,17 @@ Customize the a11y ruleset at the story level by updating your story to include

#### Turn off automated a11y tests

<IfRenderer renderer="svelte">
<If renderer="svelte">

If you are using Svelte CSF, you can turn off automated accessibility testing for stories or components by adding globals to your story or adjusting the defineMeta function with the required configuration. With a regular CSF story, you can add the following to your story's export or component's default export:
If you are using Svelte CSF, you can turn off automated accessibility testing for stories or components by adding globals to your story or adjusting the `defineMeta` function with the required configuration. With a regular CSF story, you can add the following to your story's export or component's default export:

</IfRenderer>
</If>

<IfRenderer renderer={['angular', 'vue', 'web-components', 'ember', 'html', 'react', 'preact', 'qwik', 'solid']}>
<If notRenderer={['svelte']}>

Disable automated accessibility testing for stories or components by adding the following globals to your story’s export or component’s default export respectively:
Disable automated accessibility testing for stories or components by adding the following globals to your story’s export or component’s default export:

</IfRenderer>
</If>


{/* prettier-ignore-start */}
Expand All @@ -120,43 +120,69 @@ Customize the a11y ruleset at the story level by updating your story to include

## Test addon integration

The accessibility addon provides seamless integration with Storybook's [test addon](./test-addon.mdx), enabling you to run automated accessibility checks for all your tests in the background while you run component tests. If there are any violations, the test will fail, and you will see the results in the sidebar without any additional setup.
The accessibility addon provides seamless integration with the [Test addon](./test-addon.mdx), enabling you to run automated accessibility checks for all your tests in the background while you run component tests. If there are any violations, the test will fail, and you will see the results in the sidebar without any additional setup.

{/* TODO: add asset of the changed UI here */}
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

style: TODO comment should be removed before merging


### Manual upgrade

If you enabled the addon and you're manually upgrading to Storybook 8.5 or later, you'll need to adjust your existing configuration (i.e., `.storybook/vitest.config.ts`) to enable the integration as follows:
If you enabled the addon and you're manually upgrading to Storybook 8.5 or later, you'll need to adjust your existing configuration (i.e., `.storybook/vitest.setup.ts`) to enable the integration as follows:

<CodeSnippets path="storybook-addon-a11y-test-setup.md" />

### Override accessibility violation levels
### Configure accessibility tests with the test addon

By default, when the accessibility addon runs with the test addon enabled, it interprets all violations as errors. This means that if a story has a minor accessibility violation, the test will fail. However, you can override this behavior by setting the `warnings` parameter in the `a11y` configuration object to define an array of impact levels that should be considered warnings.
Like the Test addon, the accessibility addon also supports [tags](../writing-stories/tags.mdx) to filter the tests you want to run. By default, the addon applies the `a11ytest` tag to all stories. If you need to exclude a story from being accessibility tested, you can remove that tag by applying the `!a11ytest` tag to the story. This also works at the project (in `.storybook/preview.js|ts`) or component level (default export in the story file).

{/* prettier-ignore-start */}
You can use tags to progressively work toward a more accessible UI by enabling accessibility tests for a subset of stories and gradually increasing the coverage. For example, a typical workflow might look like this:

<CodeSnippets path="storybook-addon-a11y-test-override-warning-levels.md" />
1. Run accessibility tests for your entire project.
1. Find that many stories have accessibility issues (and maybe feel a bit overwhelmed!).
1. Temporarily exclude all stories from accessibility tests.

{/* prettier-ignore-end */}
```ts title=".storybook/preview.ts"
// Replace your-renderer with the renderer you are using (e.g., react, vue3)
import { Preview } from '@storybook/your-renderer';

const preview: Preview = {
// ...
// 👇 Temporarily remove the a11ytest tag from all stories
tags: ['!a11ytest'],
};

export default preview;
```

1. Pick a good starting point (we recommend something like Button, for its simplicity and likelihood of being used within other components) and re-include it in the accessibility tests.

```ts title="Button.stories.ts"
// Replace your-renderer with the renderer you are using (e.g., react, vue3)
import { Meta } from '@storybook/your-renderer';

import { Button } from './Button';

const meta = {
component: Button,
// 👇 Re-apply the a11ytest tag for this component's stories
tags: ['a11ytest'],
};

export default preview;
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

logic: export default meta instead of preview here

Comment on lines +158 to +170
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just a bit of a sanity check here: don't forget to convert the example into a full-fledged snippet file with the supported renderers and frameworks (including Svelte CSF, if possible).

```

In the example above, we configured all the `minor` or `moderate` accessibility violations to be considered warnings. All other levels (i.e., `serious` or `critical`) will continue to be considered errors, fail the test, and report the results accordingly in the Storybook UI or Vitest.
1. Pick another component and repeat the process until you've covered all your components and you're an accessibility hero!

### Configure accessibility tests with the test addon
### Override accessibility violation levels

If you want to run accessibility tests only for a subset of your stories, you can use the [tags](../writing-stories/tags.mdx) mechanism to filter the tests you want to run with the test addon. For example, to turn off accessibility tests for a specific story, add the `!a11ytest` tag to the story's meta or directly to the story's `tags` configuration option. For example:
By default, when the accessibility addon runs with the test addon enabled, it interprets all violations as errors. This means that if a story has a minor accessibility violation, the test will fail. However, you can override this behavior by setting the `warnings` parameter in the `a11y` configuration object to define an array of impact levels that should be considered warnings.

{/* prettier-ignore-start */}

<CodeSnippets path="storybook-test-addon-disable-tests.md" />
<CodeSnippets path="storybook-addon-a11y-test-override-warning-levels.md" />

{/* prettier-ignore-end */}

<Callout variant="info">

Tags can be applied at the project, component (meta), or story levels. Read our [documentation](../writing-stories/tags.mdx) for more information on configuring tags.

</Callout>
In the example above, we configured all the `minor` or `moderate` accessibility violations to be considered warnings. All other levels (i.e., `serious` or `critical`) will continue to be considered errors, fail the test, and report the results accordingly in the Storybook UI or CLI output.

</If>

Expand Down
Loading
Loading