From 6fb17c9ab97ced368a5e6ef22195567ea15f43a6 Mon Sep 17 00:00:00 2001 From: Kyle Gach Date: Wed, 11 Dec 2024 23:30:25 -0700 Subject: [PATCH] Docs updates for Storybook Test - Focused tests - Coverage - A11y - Remove `test.include` & `test.isolate` from example Vitest configs - Streamline Test addon introduction - Address feedback from EAP --- MIGRATION.md | 8 +- .../vitest-plugin-vitest-config-alias.md | 2 + docs/_snippets/vitest-plugin-vitest-config.md | 24 +- .../vitest-plugin-vitest-workspace.md | 18 -- docs/writing-tests/accessibility-testing.mdx | 82 ++++-- docs/writing-tests/test-addon.mdx | 93 +++++-- docs/writing-tests/test-coverage.mdx | 240 +++++++++++++++++- 7 files changed, 368 insertions(+), 99 deletions(-) diff --git a/MIGRATION.md b/MIGRATION.md index fd3ce9e10be5..58b42f10c0aa 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -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'; diff --git a/docs/_snippets/vitest-plugin-vitest-config-alias.md b/docs/_snippets/vitest-plugin-vitest-config-alias.md index 5777c37f2616..ac1f59857c72 100644 --- a/docs/_snippets/vitest-plugin-vitest-config-alias.md +++ b/docs/_snippets/vitest-plugin-vitest-config-alias.md @@ -17,6 +17,8 @@ export default { ``` ```js filename="vitest.config.ts" renderer="common" tabTitle="After" +import { defineConfig } from 'vitest/config'; + export default defineConfig({ // ... resolve: { diff --git a/docs/_snippets/vitest-plugin-vitest-config.md b/docs/_snippets/vitest-plugin-vitest-config.md index 4cd240e86a44..b3f271a6e636 100644 --- a/docs/_snippets/vitest-plugin-vitest-config.md +++ b/docs/_snippets/vitest-plugin-vitest-config.md @@ -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, @@ -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'], }, - }), + }) ); ``` @@ -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, @@ -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'], }, - }), + }) ); ``` @@ -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, @@ -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'], }, - }), + }) ); ``` diff --git a/docs/_snippets/vitest-plugin-vitest-workspace.md b/docs/_snippets/vitest-plugin-vitest-workspace.md index b4e9ba800211..46b5a3e22edd 100644 --- a/docs/_snippets/vitest-plugin-vitest-workspace.md +++ b/docs/_snippets/vitest-plugin-vitest-workspace.md @@ -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, @@ -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'], }, }, @@ -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, @@ -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'], }, }, @@ -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, @@ -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'], }, }, diff --git a/docs/writing-tests/accessibility-testing.mdx b/docs/writing-tests/accessibility-testing.mdx index 7072edb154ad..a0eb50683630 100644 --- a/docs/writing-tests/accessibility-testing.mdx +++ b/docs/writing-tests/accessibility-testing.mdx @@ -67,17 +67,17 @@ If you need to dismiss an accessibility rule or modify its settings across all s #### Component-level a11y 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 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. - + - + - 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: - + {/* prettier-ignore-start */} @@ -97,17 +97,17 @@ Customize the a11y ruleset at the story level by updating your story to include #### Turn off automated a11y tests - + - 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: - + - + - 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: - + {/* prettier-ignore-start */} @@ -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 */} ### 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: -### 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: - +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; + ``` -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 */} - + {/* prettier-ignore-end */} - - - 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. - - +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. diff --git a/docs/writing-tests/test-addon.mdx b/docs/writing-tests/test-addon.mdx index fbf331c69dd8..550e634401b0 100644 --- a/docs/writing-tests/test-addon.mdx +++ b/docs/writing-tests/test-addon.mdx @@ -7,9 +7,9 @@ sidebar: - The Test addon, powered by [Vitest](https://vitest.dev/), is currently only supported in [React](?renderer=react), [Vue](?renderer=vue) and [Svelte](?renderer=svelte) projects, which use the [Vite builder](../builders/vite.mdx) (or the [Next.js framework](../get-started/frameworks/nextjs.mdx)). + The Test addon is currently only supported in [React](?renderer=react), [Vue](?renderer=vue) and [Svelte](?renderer=svelte) projects, which use the [Vite builder](../builders/vite.mdx) (or the [Next.js framework with Vite](../get-started/frameworks/nextjs.mdx#with-vite)). - If you are using a different renderer, you can use the [Storyboook test runner](./test-runner.mdx) to test your stories. + If you are using a different renderer (such as Angular) or the Webpack builder, you can use the [Storyboook test runner](./test-runner.mdx) to test your stories. {/* End non-supported renderers */} @@ -23,11 +23,11 @@ sidebar: While this addon is experimental, it is published as the `@storybook/experimental-addon-test` package and the API may change in future releases. We welcome feedback and contributions to help improve this feature. -Storybook's Test addon allows you to test your components directly inside Storybook. It does this by using a Vitest plugin to transform your [stories](../writing-stories/index.mdx) into [Vitest](https://vitest.dev) tests using [portable stories](../api/portable-stories/portable-stories-vitest.mdx). +Storybook's Test addon allows you to test your components directly inside Storybook. On its own, it transforms your [stories](../writing-stories/index.mdx) into [component tests](./component-testing.mdx), which test the rendering and behavior of your components in a real browser environment. It can also calculate project [coverage](./test-coverage.mdx) provided by your stories. -Stories are tested in two ways: a smoke test to ensure it renders and, if a [play function](../writing-tests/component-testing#write-a-component-test) is defined, that function is run and any [assertions made](../writing-tests/component-testing.mdx#assert-tests-with-vitests-apis) within it are validated. +If your project is using other testing addons, such as the [Visual tests addon](./visual-testing.mdx) or the [Accessibility addon](./accessibility-testing.mdx), you can run those tests alongside your component tests. -If a test fails, it will be marked as such in the sidebar and you can click on the story to see the failure. You can also run tests in watch mode, which will automatically re-run tests when you make changes to your components or stories. +When tests are run for a story, the status is shown in the sidebar. You can filter it down to only show failures and failing status indicators open a menu to debug the failure. You can also run tests in watch mode, which will automatically re-run tests when you make changes to your components or stories.