diff --git a/docs/_snippets/addon-vitest-install.md b/docs/_snippets/addon-vitest-install.md
new file mode 100644
index 000000000000..d54a74ca17d1
--- /dev/null
+++ b/docs/_snippets/addon-vitest-install.md
@@ -0,0 +1,11 @@
+```shell renderer="common" language="js" packageManager="npx"
+npx storybook@latest add @storybook/experimental-addon-vitest
+```
+
+```shell renderer="common" language="js" packageManager="pnpm"
+pnpm dlx storybook@latest add @storybook/experimental-addon-vitest
+```
+
+```shell renderer="common" language="js" packageManager="yarn"
+yarn dlx storybook@latest add @storybook/experimental-addon-vitest
+```
diff --git a/docs/_snippets/addon-vitest-run-tests.md b/docs/_snippets/addon-vitest-run-tests.md
new file mode 100644
index 000000000000..3b91e2d284ea
--- /dev/null
+++ b/docs/_snippets/addon-vitest-run-tests.md
@@ -0,0 +1,11 @@
+```shell renderer="common" language="js" packageManager="npm"
+npm run test
+```
+
+```shell renderer="common" language="js" packageManager="pnpm"
+pnpm run test
+```
+
+```shell renderer="common" language="js" packageManager="yarn"
+yarn test
+```
diff --git a/docs/writing-tests/test-runner-with-vitest.mdx b/docs/writing-tests/test-runner-with-vitest.mdx
index ba8b3f46517d..343a20555535 100644
--- a/docs/writing-tests/test-runner-with-vitest.mdx
+++ b/docs/writing-tests/test-runner-with-vitest.mdx
@@ -7,22 +7,25 @@ sidebar:
(⚠️ **Experimental**)
+
+ While this feature is experimental, it is published as the `@storybook/experimental-addon-vitest` package.
+
+
Storybook's test runner with Vitest uses a Vitest plugin to transform your [stories](../writing-stories/index.mdx) into tests. You can then run those tests just like any other in Vitest, which will check that the story renders without errors and, if a [play function](../writing-stories/play-function.mdx) is defined, that it runs as expected and any [assertions made](../writing-tests/interaction-testing.mdx#assert-tests-with-vitests-apis) within it are validated.
By using Vitest's browser mode, those tests are run in a real browser environment, which gives you more reliable results for UI components that commonly rely on browser APIs or features.
-## Setup
+## Install and set up
+
+Get started by upgrading to at least Storybook 8.3, then installing and configuring the plugin in your project.
-Get started by installing and configuring the plugin in your project.
+
-### Automatic
+### Automatic setup
Run the following command to install and configure the addon, which contains the plugin to run your stories as tests using Vitest:
-{/* TODO: Snippetize */}
-```sh
-npx storybook@latest add @storybook/experimental-addon-vitest
-```
+
That command will install and register the Vitest addon. It will also inspect your project's Vite and Vitest setup, and install and configure them if necessary.
@@ -52,7 +55,7 @@ export default defineConfig({
The configuration produced by the `add` command will attempt to set some sensible defaults for your project. However, you may need to adjust the configuration to fit your project's needs. The full configuration options can be found in the [API section](#options), below.
-### Manual
+### Manual setup
For some project setups, the `add` command may be unable to automate the plugin setup and ask you to complete additional setup steps. Here's what to do:
@@ -66,7 +69,7 @@ For some project setups, the `add` command may be unable to automate the plugin
### Example configuration files
-Here are configuration files generated by the `add` command. You can use these as a reference when setting up your project.
+Here are example configuration files generated by the `add` command. You can use these as a reference when setting up your project.
Example Vitest setup file
@@ -171,7 +174,7 @@ While the plugin does not require Storybook to run when testing, you may still w
You can also provide a [`storybookUrl` option](#storybookurl) to the plugin configuration. When you're not using watch mode and tests fail, the plugin will provide a link to the story using this URL in the output. This is useful when [running tests in CI](#in-ci) or other environments where Storybook is not already running.
-TK - Screenshot of test output with links to SB
+[TK - Screenshot of test output with links to SB]
## Usage
@@ -181,16 +184,13 @@ There are three primary ways to run tests using the Vitest plugin:
The plugin transforms your stories into real Vitest tests, so you run those tests just like you run any other Vitest tests in your project. Typically, you will have a `test` script in your `package.json` that runs Vitest. When you run that script, the addon will find and run your story-based tests. Here's an example of running your tests (in [watch mode](https://vitest.dev/guide/cli.html#vitest-watch), by default) using the Vitest CLI:
-{/* TODO: Snippetize */}
-```sh
-npm run test
-```
+
### Editor extension
Transforming your stories into Vitest tests with the plugin also enables you to run and debug tests using Vitest [IDE integrations](https://vitest.dev/guide/ide.html). This allows you to run tests directly from your editor, such as VSCode and JetBrains IDE.
-TK - Screenshot of VS Code
+[TK - Screenshot of VS Code]
### In CI
@@ -200,7 +200,7 @@ Here's an example using GitHub Actions. The steps are similar for other CI provi
When actions for services like Vercel, Netlify and others run a deployment job, they follow a pattern of emitting a `deployment_status` event containing the newly generated URL under `deployment_status.target_url`. This is the URL to the published Storybook instance. We then pass that URL to the plugin configuration using an environment variable, `SB_URL`. Finally, we update the plugin configuration to use that environment variable in the `storybookUrl` option.
-```yaml
+```yaml title=".github/workflows/test-storybook.yml"
name: Storybook Tests
on: deployment_status
jobs:
@@ -222,10 +222,20 @@ jobs:
```
```js title="vitest.workspace.ts"
-storybookTest({
- storybookScript: 'yarn storybook --ci',
- storybookUrl: process.env.SB_URL
-}),
+export default defineWorkspace([
+ // ...
+ {
+ // ...
+ {
+ plugins: [
+ storybookTest({
+ storybookScript: 'yarn storybook --ci',
+ storybookUrl: process.env.SB_URL
+ }),
+ ],
+ },
+ },
+])
```
## Configuration
@@ -244,18 +254,24 @@ In this example, we'll apply the `stable` tag to all of the Button component's s
To connect those tags to our test behavior, we can adjust the plugin configuration to exclude the `experimental` tag:
-{/* TODO: Snippetize */}
```js title="vitest.workspace.ts"
-{
- plugins: [
- storybookTest({
- tags: {
- include: ['test'],
- exclude: ['experimental'],
- },
- }),
- ],
-}
+export default defineWorkspace([
+ // ...
+ {
+ // ...
+ {
+ plugins: [
+ storybookTest({
+ // ...
+ tags: {
+ include: ['test'],
+ exclude: ['experimental'],
+ },
+ }),
+ ],
+ },
+ },
+])
```
If the same tag is in both the `include` and `exclude` arrays, the `exclude` behavior takes precedence.
@@ -282,7 +298,7 @@ If the URLs are not working when running tests in CI, you should ensure the Stor
If you have custom operations defined in [`viteFinal`](../api/main-config/main-config-vite-final.mdx) in your `.storybook/main.js|ts` file, you will need to translate those into the Vitest configuration. This is because the plugin does not use the Storybook Vite configuration.
```ts
-TK
+TK - Is there a good example we could offer here?
```
### Why do we recommend browser mode?