Skip to content

Commit

Permalink
More polish
Browse files Browse the repository at this point in the history
  • Loading branch information
kylegach committed Aug 26, 2024
1 parent 877e4a3 commit 8cdbbaf
Show file tree
Hide file tree
Showing 3 changed files with 70 additions and 32 deletions.
11 changes: 11 additions & 0 deletions docs/_snippets/addon-vitest-install.md
Original file line number Diff line number Diff line change
@@ -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
```
11 changes: 11 additions & 0 deletions docs/_snippets/addon-vitest-run-tests.md
Original file line number Diff line number Diff line change
@@ -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
```
80 changes: 48 additions & 32 deletions docs/writing-tests/test-runner-with-vitest.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -7,22 +7,25 @@ sidebar:

(⚠️ **Experimental**)

<Callout variant="warning" icon="🧪">
While this feature is experimental, it is published as the `@storybook/experimental-addon-vitest` package.
</Callout>

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.
<CodeSnippets path="storybook-upgrade.md" />

### 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
```
<CodeSnippets path="addon-vitest-install.md" />

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.

Expand Down Expand Up @@ -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:

Expand All @@ -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.

<details>
<summary>Example Vitest setup file</summary>
Expand Down Expand Up @@ -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

Expand All @@ -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
```
<CodeSnippets path="addon-vitest-run-tests.md" />

### 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

Expand All @@ -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:
Expand All @@ -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
Expand All @@ -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.
Expand All @@ -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?
Expand Down

0 comments on commit 8cdbbaf

Please sign in to comment.