mirror of
https://github.com/storybookjs/storybook.git
synced 2025-04-06 07:21:16 +08:00
Split into three separate pages
- Organizational and prose improvements - Remove Cypress, for now
This commit is contained in:
Kyle Gach
parent
8355abdf3c
commit
e09480aefb
288
docs/api/portable-stories-jest.md
Normal file
288
docs/api/portable-stories-jest.md
Normal file
@ -0,0 +1,288 @@
|
||||
---
|
||||
title: 'Portable stories in Jest'
|
||||
---
|
||||
|
||||
export const SUPPORTED_RENDERERS = ['react', 'vue'];
|
||||
|
||||
<If notRenderer={SUPPORTED_RENDERERS}>
|
||||
|
||||
<Callout variant="info">
|
||||
|
||||
Portable stories in Jest are currently only supported in [React](?renderer=react) and [Vue](?renderer=vue) projects.
|
||||
|
||||
</Callout>
|
||||
|
||||
<!-- End non-supported renderers -->
|
||||
|
||||
</If>
|
||||
|
||||
<If renderer={SUPPORTED_RENDERERS}>
|
||||
|
||||
Portable stories are Storybook [stories](../writing-stories/index.md) which can be used in external environments, such as [Jest](https://jestjs.io).
|
||||
|
||||
Normally, Storybok composes a story and its [annotations](#annotations) automatically, as part of the [story pipeline](#story-pipeline). When using stories in Jest tests, you must handle the story pipeline yourself, which is what the [`composeStories`](#composestories) and [`composeStory`](#composestory) functions enable.
|
||||
|
||||
## composeStories
|
||||
|
||||
`composeStories` will process the component's stories you specify, compose each of them with the necessary [annotations](#annotations), and return an object containing the composed stories.
|
||||
|
||||
By default, the composed story will render the component with the [args](../writing-stories/args.md) that are defined in the story. You can also pass any props to the component in your test and those props will override the values passed in the story's args.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
<CodeSnippets
|
||||
paths={[
|
||||
'react/portable-stories-jest-compose-stories.ts.mdx',
|
||||
'vue/portable-stories-jest-compose-stories.ts.mdx',
|
||||
]}
|
||||
/>
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
### Type
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
```ts
|
||||
(
|
||||
csfExports: CSF file exports,
|
||||
projectAnnotations?: ProjectAnnotations
|
||||
) => Record<string, ComposedStoryFn>
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
### Parameters
|
||||
|
||||
#### `csfExports`
|
||||
|
||||
(**Required**)
|
||||
|
||||
Type: CSF file exports
|
||||
|
||||
Specifies which component's stories you want to compose. Pass the **full set of exports** from the CSF file (not the default export!). E.g. `import * as stories from './Button.stories'`
|
||||
|
||||
#### `projectAnnotations`
|
||||
|
||||
Type: `ProjectAnnotation | ProjectAnnotation[]`
|
||||
|
||||
Specifies the project annotations to be applied to the composed stories.
|
||||
|
||||
This parameter is provided for convenience. You should likely use [`setProjectAnnotations`](#setprojectannotations) instead. Details about the `ProjectAnnotation` type can be found in that function's [`projectAnnotations`](#projectannotations-2) parameter.
|
||||
|
||||
This parameter can be used to [override](#overriding-globals) the project annotations applied via `setProjectAnnotations`.
|
||||
|
||||
### Return
|
||||
|
||||
Type: `Record<string, ComposedStoryFn>`
|
||||
|
||||
An object where the keys are the names of the stories and the values are the composed stories.
|
||||
|
||||
Additionally, the composed story will have the following properties:
|
||||
|
||||
| Property | Type | Description |
|
||||
| ---------- | ----------------------------------------- | --------------------------------------------------------------- |
|
||||
| storyName | `string` | The story's name |
|
||||
| args | `Record<string, any>` | The story's [args](../writing-stories/args.md) |
|
||||
| argTypes | `ArgType` | The story's [argTypes](./arg-types.md) |
|
||||
| id | `string` | The story's id |
|
||||
| parameters | `Record<string, any>` | The story's [parameters](./parameters.md) |
|
||||
| load | `() => Promise<void>` | Executes all the [loaders](#2-load-optional) for a given story |
|
||||
| play | `(context) => Promise<void> \| undefined` | Executes the [play function](#4-play-optional) of a given story |
|
||||
|
||||
## composeStory
|
||||
|
||||
You can use `composeStory` if you wish to compose a single story for a component.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
<CodeSnippets
|
||||
paths={[
|
||||
'react/portable-stories-jest-compose-story.ts.mdx',
|
||||
'vue/portable-stories-jest-compose-story.ts.mdx',
|
||||
]}
|
||||
/>
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
### Type
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
```ts
|
||||
(
|
||||
story: Story export,
|
||||
componentAnnotations: Meta,
|
||||
projectAnnotations?: ProjectAnnotations,
|
||||
exportsName?: string
|
||||
) => ComposedStoryFn
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
### Parameters
|
||||
|
||||
#### `story`
|
||||
|
||||
(**Required**)
|
||||
|
||||
Type: `Story export`
|
||||
|
||||
Specifies which story you want to compose.
|
||||
|
||||
#### `componentAnnotations`
|
||||
|
||||
(**Required**)
|
||||
|
||||
Type: `Meta`
|
||||
|
||||
The default export from the stories file containing the [`story`](#story).
|
||||
|
||||
#### `projectAnnotations`
|
||||
|
||||
Type: `ProjectAnnotation | ProjectAnnotation[]`
|
||||
|
||||
Specifies the project annotations to be applied to the composed story.
|
||||
|
||||
This parameter is provided for convenience. You should likely use [`setProjectAnnotations`](#setprojectannotations) instead. Details about the `ProjectAnnotation` type can be found in that function's [`projectAnnotations`](#projectannotations-2) parameter.
|
||||
|
||||
This parameter can be used to [override](#overriding-globals) the project annotations applied via `setProjectAnnotations`.
|
||||
|
||||
#### `exportsName`
|
||||
|
||||
Type: `string`
|
||||
|
||||
You probably don't need this. Because `composeStory` accepts a single story, it does not have access to the name of that story's export in the file (like `composeStories` does). If you must ensure unique story names in your tests and you cannot use `composeStories`, you can pass the name of the story's export here.
|
||||
|
||||
### Return
|
||||
|
||||
Type: `ComposedStoryFn`
|
||||
|
||||
A single [composed story](#return).
|
||||
|
||||
## setProjectAnnotations
|
||||
|
||||
This API should be called once, before the tests run, typically in a [setup file](https://jestjs.io/docs/configuration#setupfiles-array). This will make sure that whenever `composeStories` or `composeStory` are called, the project annotations are taken into account as well.
|
||||
|
||||
```ts
|
||||
// setup-portable-stories.ts
|
||||
// Replace <your-renderer> with your renderer, e.g. react, vue3
|
||||
import { setProjectAnnotations } from '@storybook/<your-renderer>';
|
||||
import * as addonAnnotations from 'my-addon/preview';
|
||||
import * as previewAnnotations from './.storybook/preview';
|
||||
|
||||
setProjectAnnotations([previewAnnotations, addonAnnotations]);
|
||||
```
|
||||
|
||||
<Callout variant="warning">
|
||||
|
||||
Sometimes a story can require an addon's [decorator](../writing-stories/decorators.md) to render properly. For example, an addon can apply a decorator that wraps your story in the necessary router context. In this case, you must include that addon's `preview` export in the project annotations set.
|
||||
|
||||
</Callout>
|
||||
|
||||
### Type
|
||||
|
||||
```ts
|
||||
(projectAnnotations: ProjectAnnotation | ProjectAnnotation[]) => void
|
||||
```
|
||||
|
||||
### Parameters
|
||||
|
||||
#### `projectAnnotations`
|
||||
|
||||
(**Required**)
|
||||
|
||||
Type: `ProjectAnnotation | ProjectAnnotation[]`
|
||||
|
||||
A set of project [annotations](#annotations) (those defined in `.storybook/preview.js|ts`) or an array of sets of project annotations, which will be applied to all composed stories.
|
||||
|
||||
## Annotations
|
||||
|
||||
Annotations are the metadata applied to a story, like [args](../writing-stories/args.md), [decorators](../writing-stories/decorators.md), [loaders](../writing-stories/loaders.md), and [play functions](../writing-stories/play-function.md). They can be defined for a specific story, all stories for a component, or all stories in the project.
|
||||
|
||||
## Story pipeline
|
||||
|
||||
To preview your stories, Storybook runs a story pipeline, which includes applying project annotations, loading data, rendering the story, and playing interactions. This is a simplified version of the pipeline:
|
||||
|
||||
|
||||
|
||||
When you want to reuse a story in a different environment, however, it's crucial to understand that all these steps make a story. The portable stories API provides you with the mechanism to recreate that story pipeline in your external environment:
|
||||
|
||||
### 1. Apply project-level annotations
|
||||
|
||||
[Annotations](#annotations) come from the story itself, that story's component, and the project. The project-level annotatations are those defined in your `.storybook/preview.js` file and by addons you're using. In portable stories, these annotations are not applied automatically—you must apply them yourself.
|
||||
|
||||
👉 For this, you use the [`setProjectAnnotations`](#setprojectannotations) API.
|
||||
|
||||
### 2. Prepare
|
||||
|
||||
The story is prepared by running [`composeStories`](#composestories) or [`composeStory`](#composestory). You do not need to do anything for this step.
|
||||
|
||||
### 3. Load
|
||||
|
||||
**(optional)**
|
||||
|
||||
Stories can prepare data they need (e.g. setting up some mocks or fetching data) before rendering by defining [loaders](../writing-stories/loaders.md). In portable stories, the loaders are not applied automatically—you have to apply them yourself.
|
||||
|
||||
👉 For this, you use the [`composeStories`](#composestories) or [`composeStory`](#composestory) API. The composed story will return a `load` method to be called **before** it is rendered.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
<CodeSnippets
|
||||
paths={[
|
||||
'react/portable-stories-jest-with-loaders.ts.mdx',
|
||||
'vue/portable-stories-jest-with-loaders.ts.mdx',
|
||||
]}
|
||||
/>
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
### 4. Render
|
||||
|
||||
At this point, the story has been prepared and can be rendered. You pass it into the
|
||||
|
||||
The story has been prepared and can be rendered. To render, you pass it into the rendering mechanism of your choice (e.g. Testing Library render function, Vue test utils mount function, etc).
|
||||
|
||||
👉 For this, you use the [`composeStories`](#composestories) or [`composeStory`](#composestory) API. The composed Story is a renderable component that can be passed to your rendering mechanism.
|
||||
|
||||
### 5. Play
|
||||
|
||||
**(optional)**
|
||||
|
||||
Finally, stories can define a [play function](../essentials/interactions.md#play-function-for-interactions) to interact with the story and assert on details after it has rendered. In portable stories, the play function does not run automatically—you have to call it yourself.
|
||||
|
||||
👉 For this, you use the [`composeStories`](#composestories) or [`composeStory`](#composestory) API. The composed Story will return a `play` method to be called **after** it has rendered.
|
||||
|
||||
The play function needs a `canvasElement`, which should be passed by you. A `canvasElement` is the HTML element which wraps your component. Each testing utility provides different ways to retrieve such element, but here's how to do it with Testing Library:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
<CodeSnippets
|
||||
paths={[
|
||||
'react/portable-stories-jest-with-play-function.ts.mdx',
|
||||
'vue/portable-stories-jest-with-play-function.ts.mdx',
|
||||
]}
|
||||
/>
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
<Callout variant="info">
|
||||
|
||||
If your play function contains assertions (e.g. `expect` calls), your test will fail when those assertions fail.
|
||||
|
||||
</Callout>
|
||||
|
||||
## Overriding globals
|
||||
|
||||
If your stories behave differently based on [globals](../essentials/toolbars-and-globals.md#globals) (e.g. rendering text in English or Spanish), you can define those global values in portable stories by overriding project annotations when composing a story:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
<CodeSnippets
|
||||
paths={[
|
||||
'react/portable-stories-jest-override-globals.ts.mdx',
|
||||
'vue/portable-stories-jest-override-globals.ts.mdx',
|
||||
]}
|
||||
/>
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
<!-- End supported renderers -->
|
||||
|
||||
</If>
|
||||
183
docs/api/portable-stories-playwright.md
Normal file
183
docs/api/portable-stories-playwright.md
Normal file
@ -0,0 +1,183 @@
|
||||
---
|
||||
title: 'Portable stories in Playwright'
|
||||
---
|
||||
|
||||
export const SUPPORTED_RENDERERS = ['react', 'vue'];
|
||||
|
||||
(⚠️ **Experimental**)
|
||||
|
||||
<If notRenderer={SUPPORTED_RENDERERS}>
|
||||
|
||||
<Callout variant="info">
|
||||
|
||||
Portable stories are currently only supported in [React](?renderer=react) and [Vue](?renderer=vue) projects.
|
||||
|
||||
</Callout>
|
||||
|
||||
<!-- End non-supported renderers -->
|
||||
|
||||
</If>
|
||||
|
||||
<If renderer={SUPPORTED_RENDERERS}>
|
||||
|
||||
Portable stories are Storybook [stories](../writing-stories/index.md) which can be used in external environments, such as [Playwright Component Tests (CT)](https://playwright.dev/docs/test-components).
|
||||
|
||||
Normally, Storybok composes a story and its [annotations](#annotations) automatically, as part of the [story pipeline](#story-pipeline). When using stories in Playwright CT, you can use the [`createTest`](#createtest) function, which extends Playwright's test functionality to add a custom `mount` mechanism, to take care of the story pipeline for you.
|
||||
|
||||
## createTest
|
||||
|
||||
(⚠️ **Experimental**)
|
||||
|
||||
Instead of using Playwright's own `test` function, you can use Storybook's special `createTest` function which will extend Playwright's test functionality to add a custom `mount` mechanism which will load, render, and play the story. This function is experimental and is subject to changes.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
<CodeSnippets
|
||||
paths={[
|
||||
'react/portable-stories-playwright-ct.ts.mdx',
|
||||
'vue/portable-stories-playwright-ct.ts.mdx',
|
||||
]}
|
||||
/>
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
<Callout variant="warning">
|
||||
|
||||
Please note the [limitations of importing stories in Playwright CT](#importing-stories-in-playwright-ct).
|
||||
|
||||
</Callout>
|
||||
|
||||
### Type
|
||||
|
||||
```ts
|
||||
createTest(
|
||||
baseTest: TK
|
||||
) => TK
|
||||
```
|
||||
|
||||
### Parameters
|
||||
|
||||
#### `baseTest`
|
||||
|
||||
(**Required**)
|
||||
|
||||
Type: `TK`
|
||||
|
||||
The base test function to use, e.g. `test` from Playwright.
|
||||
|
||||
### Return
|
||||
|
||||
Type: `TK`
|
||||
|
||||
A Storybook-specific test function with the custom `mount` mechanism.
|
||||
|
||||
## setProjectAnnotations
|
||||
|
||||
This API should be called once, before the tests run, in [`playwright/index.ts`](https://playwright.dev/docs/test-components#step-1-install-playwright-test-for-components-for-your-respective-framework). This will make sure that when `mount` is called, the project annotations are taken into account as well.
|
||||
|
||||
```ts
|
||||
// playwright/index.ts
|
||||
// Replace <your-renderer> with your renderer, e.g. react, vue3
|
||||
import { setProjectAnnotations } from '@storybook/<your-renderer>';
|
||||
import * as addonAnnotations from 'my-addon/preview';
|
||||
import sbAnnotations from '../.storybook/preview';
|
||||
|
||||
setProjectAnnotations([sbAnnotations, addonAnnotations]);
|
||||
```
|
||||
|
||||
<Callout variant="warning">
|
||||
|
||||
Sometimes a story can require an addon's [decorator](../writing-stories/decorators.md) to render properly. For example, an addon can apply a decorator that wraps your story in the necessary router context. In this case, you must include that addon's `preview` export in the project annotations set.
|
||||
|
||||
</Callout>
|
||||
|
||||
### Type
|
||||
|
||||
```ts
|
||||
(projectAnnotations: ProjectAnnotation | ProjectAnnotation[]) => void
|
||||
```
|
||||
|
||||
### Parameters
|
||||
|
||||
#### `projectAnnotations`
|
||||
|
||||
(**Required**)
|
||||
|
||||
Type: `ProjectAnnotation | ProjectAnnotation[]`
|
||||
|
||||
A set of project [annotations](#annotations) (those defined in `.storybook/preview.js|ts`) or an array of sets of project annotations, which will be applied to all composed stories.
|
||||
|
||||
## Annotations
|
||||
|
||||
Annotations are the metadata applied to a story, like [args](../writing-stories/args.md), [decorators](../writing-stories/decorators.md), [loaders](../writing-stories/loaders.md), and [play functions](../writing-stories/play-function.md). They can be defined for a specific story, all stories for a component, or all stories in the project.
|
||||
|
||||
## Importing stories in Playwright CT
|
||||
|
||||
The code which you write in your Playwright test file is transformed and orchestrated by Playwright, where part of the code executes in Node, while other parts execute in the browser.
|
||||
|
||||
Because of this, you have to compose the stories _in a separate file than your own test file_:
|
||||
|
||||
```ts
|
||||
// Button.portable.ts
|
||||
// Replace <your-renderer> with your renderer, e.g. react, vue3
|
||||
import { composeStories } from '@storybook/<your-renderer>';
|
||||
|
||||
import * as stories from './Button.stories';
|
||||
|
||||
// This function will be executed in the browser
|
||||
// and compose all stories, exporting them in a single object
|
||||
export default composeStories(stories);
|
||||
```
|
||||
|
||||
You can then import the composed stories in your Playwright test file, as in the [example above](#createtest).
|
||||
|
||||
<Callout variant="info">
|
||||
|
||||
[Read more about Playwright's component testing](https://playwright.dev/docs/test-components#test-stories).
|
||||
|
||||
</Callout>
|
||||
|
||||
## Story pipeline
|
||||
|
||||
To preview your stories, Storybook runs a story pipeline, which includes applying project annotations, loading data, rendering the story, and playing interactions. This is a simplified version of the pipeline:
|
||||
|
||||
|
||||
|
||||
When you want to reuse a story in a different environment, however, it's crucial to understand that all these steps make a story. The portable stories API provides you with the mechanism to recreate that story pipeline in your external environment:
|
||||
|
||||
### 1. Apply project-level annotations
|
||||
|
||||
[Annotations](#annotations) come from the story itself, that story's component, and the project. The project-level annotatations are those defined in your `.storybook/preview.js` file and by addons you're using. In portable stories, these annotations are not applied automatically—you must apply them yourself.
|
||||
|
||||
👉 For this, you use the [`setProjectAnnotations`](#setprojectannotations) API.
|
||||
|
||||
### 2. Prepare, load, render, and play
|
||||
|
||||
The story pipeline includes preparing the story, [loading data](../writing-stories/loaders.md), rendering the story, and [playing interactions](../essentials/interactions.md#play-function-for-interactions). In portable stories within Playwright CT, the `mount` function takes care of these steps for you.
|
||||
|
||||
👉 For this, you use the [`createTest`](#createtest) API.
|
||||
|
||||
<Callout variant="info">
|
||||
|
||||
If your play function contains assertions (e.g. `expect` calls), your test will fail when those assertions fail.
|
||||
|
||||
</Callout>
|
||||
|
||||
## Overriding globals
|
||||
|
||||
If your stories behave differently based on [globals](../essentials/toolbars-and-globals.md#globals) (e.g. rendering text in English or Spanish), you can define those global values in portable stories by overriding project annotations when composing a story:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
<CodeSnippets
|
||||
paths={[
|
||||
'react/portable-stories-override-globals.ts.mdx',
|
||||
'vue/portable-stories-override-globals.ts.mdx',
|
||||
]}
|
||||
/>
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
<!-- End supported renderers -->
|
||||
|
||||
</If>
|
||||
288
docs/api/portable-stories-vitest.md
Normal file
288
docs/api/portable-stories-vitest.md
Normal file
@ -0,0 +1,288 @@
|
||||
---
|
||||
title: 'Portable stories in Vitest'
|
||||
---
|
||||
|
||||
export const SUPPORTED_RENDERERS = ['react', 'vue'];
|
||||
|
||||
<If notRenderer={SUPPORTED_RENDERERS}>
|
||||
|
||||
<Callout variant="info">
|
||||
|
||||
Portable stories in Vitest are currently only supported in [React](?renderer=react) and [Vue](?renderer=vue) projects.
|
||||
|
||||
</Callout>
|
||||
|
||||
<!-- End non-supported renderers -->
|
||||
|
||||
</If>
|
||||
|
||||
<If renderer={SUPPORTED_RENDERERS}>
|
||||
|
||||
Portable stories are Storybook [stories](../writing-stories/index.md) which can be used in external environments, such as [Vitest](https://vitest.dev).
|
||||
|
||||
Normally, Storybok composes a story and its [annotations](#annotations) automatically, as part of the [story pipeline](#story-pipeline). When using stories in Vitest tests, you must handle the story pipeline yourself, which is what the [`composeStories`](#composestories) and [`composeStory`](#composestory) functions enable.
|
||||
|
||||
## composeStories
|
||||
|
||||
`composeStories` will process the component's stories you specify, compose each of them with the necessary [annotations](#annotations), and return an object containing the composed stories.
|
||||
|
||||
By default, the composed story will render the component with the [args](../writing-stories/args.md) that are defined in the story. You can also pass any props to the component in your test and those props will override the values passed in the story's args.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
<CodeSnippets
|
||||
paths={[
|
||||
'react/portable-stories-vitest-compose-stories.ts.mdx',
|
||||
'vue/portable-stories-vitest-compose-stories.ts.mdx',
|
||||
]}
|
||||
/>
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
### Type
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
```ts
|
||||
(
|
||||
csfExports: CSF file exports,
|
||||
projectAnnotations?: ProjectAnnotations
|
||||
) => Record<string, ComposedStoryFn>
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
### Parameters
|
||||
|
||||
#### `csfExports`
|
||||
|
||||
(**Required**)
|
||||
|
||||
Type: CSF file exports
|
||||
|
||||
Specifies which component's stories you want to compose. Pass the **full set of exports** from the CSF file (not the default export!). E.g. `import * as stories from './Button.stories'`
|
||||
|
||||
#### `projectAnnotations`
|
||||
|
||||
Type: `ProjectAnnotation | ProjectAnnotation[]`
|
||||
|
||||
Specifies the project annotations to be applied to the composed stories.
|
||||
|
||||
This parameter is provided for convenience. You should likely use [`setProjectAnnotations`](#setprojectannotations) instead. Details about the `ProjectAnnotation` type can be found in that function's [`projectAnnotations`](#projectannotations-2) parameter.
|
||||
|
||||
This parameter can be used to [override](#overriding-globals) the project annotations applied via `setProjectAnnotations`.
|
||||
|
||||
### Return
|
||||
|
||||
Type: `Record<string, ComposedStoryFn>`
|
||||
|
||||
An object where the keys are the names of the stories and the values are the composed stories.
|
||||
|
||||
Additionally, the composed story will have the following properties:
|
||||
|
||||
| Property | Type | Description |
|
||||
| ---------- | ----------------------------------------- | --------------------------------------------------------------- |
|
||||
| storyName | `string` | The story's name |
|
||||
| args | `Record<string, any>` | The story's [args](../writing-stories/args.md) |
|
||||
| argTypes | `ArgType` | The story's [argTypes](./arg-types.md) |
|
||||
| id | `string` | The story's id |
|
||||
| parameters | `Record<string, any>` | The story's [parameters](./parameters.md) |
|
||||
| load | `() => Promise<void>` | Executes all the [loaders](#2-load-optional) for a given story |
|
||||
| play | `(context) => Promise<void> \| undefined` | Executes the [play function](#4-play-optional) of a given story |
|
||||
|
||||
## composeStory
|
||||
|
||||
You can use `composeStory` if you wish to compose a single story for a component.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
<CodeSnippets
|
||||
paths={[
|
||||
'react/portable-stories-vitest-compose-story.ts.mdx',
|
||||
'vue/portable-stories-vitest-compose-story.ts.mdx',
|
||||
]}
|
||||
/>
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
### Type
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
```ts
|
||||
(
|
||||
story: Story export,
|
||||
componentAnnotations: Meta,
|
||||
projectAnnotations?: ProjectAnnotations,
|
||||
exportsName?: string
|
||||
) => ComposedStoryFn
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
### Parameters
|
||||
|
||||
#### `story`
|
||||
|
||||
(**Required**)
|
||||
|
||||
Type: `Story export`
|
||||
|
||||
Specifies which story you want to compose.
|
||||
|
||||
#### `componentAnnotations`
|
||||
|
||||
(**Required**)
|
||||
|
||||
Type: `Meta`
|
||||
|
||||
The default export from the stories file containing the [`story`](#story).
|
||||
|
||||
#### `projectAnnotations`
|
||||
|
||||
Type: `ProjectAnnotation | ProjectAnnotation[]`
|
||||
|
||||
Specifies the project annotations to be applied to the composed story.
|
||||
|
||||
This parameter is provided for convenience. You should likely use [`setProjectAnnotations`](#setprojectannotations) instead. Details about the `ProjectAnnotation` type can be found in that function's [`projectAnnotations`](#projectannotations-2) parameter.
|
||||
|
||||
This parameter can be used to [override](#overriding-globals) the project annotations applied via `setProjectAnnotations`.
|
||||
|
||||
#### `exportsName`
|
||||
|
||||
Type: `string`
|
||||
|
||||
You probably don't need this. Because `composeStory` accepts a single story, it does not have access to the name of that story's export in the file (like `composeStories` does). If you must ensure unique story names in your tests and you cannot use `composeStories`, you can pass the name of the story's export here.
|
||||
|
||||
### Return
|
||||
|
||||
Type: `ComposedStoryFn`
|
||||
|
||||
A single [composed story](#return).
|
||||
|
||||
## setProjectAnnotations
|
||||
|
||||
This API should be called once, before the tests run, typically in a [setup file](https://vitest.dev/config/#setupfiles). This will make sure that whenever `composeStories` or `composeStory` are called, the project annotations are taken into account as well.
|
||||
|
||||
```ts
|
||||
// setup-portable-stories.ts
|
||||
// Replace <your-renderer> with your renderer, e.g. react, vue3
|
||||
import { setProjectAnnotations } from '@storybook/<your-renderer>';
|
||||
import * as addonAnnotations from 'my-addon/preview';
|
||||
import * as previewAnnotations from './.storybook/preview';
|
||||
|
||||
setProjectAnnotations([previewAnnotations, addonAnnotations]);
|
||||
```
|
||||
|
||||
<Callout variant="warning">
|
||||
|
||||
Sometimes a story can require an addon's [decorator](../writing-stories/decorators.md) to render properly. For example, an addon can apply a decorator that wraps your story in the necessary router context. In this case, you must include that addon's `preview` export in the project annotations set.
|
||||
|
||||
</Callout>
|
||||
|
||||
### Type
|
||||
|
||||
```ts
|
||||
(projectAnnotations: ProjectAnnotation | ProjectAnnotation[]) => void
|
||||
```
|
||||
|
||||
### Parameters
|
||||
|
||||
#### `projectAnnotations`
|
||||
|
||||
(**Required**)
|
||||
|
||||
Type: `ProjectAnnotation | ProjectAnnotation[]`
|
||||
|
||||
A set of project [annotations](#annotations) (those defined in `.storybook/preview.js|ts`) or an array of sets of project annotations, which will be applied to all composed stories.
|
||||
|
||||
## Annotations
|
||||
|
||||
Annotations are the metadata applied to a story, like [args](../writing-stories/args.md), [decorators](../writing-stories/decorators.md), [loaders](../writing-stories/loaders.md), and [play functions](../writing-stories/play-function.md). They can be defined for a specific story, all stories for a component, or all stories in the project.
|
||||
|
||||
## Story pipeline
|
||||
|
||||
To preview your stories, Storybook runs a story pipeline, which includes applying project annotations, loading data, rendering the story, and playing interactions. This is a simplified version of the pipeline:
|
||||
|
||||
|
||||
|
||||
When you want to reuse a story in a different environment, however, it's crucial to understand that all these steps make a story. The portable stories API provides you with the mechanism to recreate that story pipeline in your external environment:
|
||||
|
||||
### 1. Apply project-level annotations
|
||||
|
||||
[Annotations](#annotations) come from the story itself, that story's component, and the project. The project-level annotatations are those defined in your `.storybook/preview.js` file and by addons you're using. In portable stories, these annotations are not applied automatically—you must apply them yourself.
|
||||
|
||||
👉 For this, you use the [`setProjectAnnotations`](#setprojectannotations) API.
|
||||
|
||||
### 2. Prepare
|
||||
|
||||
The story is prepared by running [`composeStories`](#composestories) or [`composeStory`](#composestory). You do not need to do anything for this step.
|
||||
|
||||
### 3. Load
|
||||
|
||||
**(optional)**
|
||||
|
||||
Stories can prepare data they need (e.g. setting up some mocks or fetching data) before rendering by defining [loaders](../writing-stories/loaders.md). In portable stories, the loaders are not applied automatically—you have to apply them yourself.
|
||||
|
||||
👉 For this, you use the [`composeStories`](#composestories) or [`composeStory`](#composestory) API. The composed story will return a `load` method to be called **before** it is rendered.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
<CodeSnippets
|
||||
paths={[
|
||||
'react/portable-stories-vitest-with-loaders.ts.mdx',
|
||||
'vue/portable-stories-vitest-with-loaders.ts.mdx',
|
||||
]}
|
||||
/>
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
### 4. Render
|
||||
|
||||
At this point, the story has been prepared and can be rendered. You pass it into the
|
||||
|
||||
The story has been prepared and can be rendered. To render, you pass it into the rendering mechanism of your choice (e.g. Testing Library render function, Vue test utils mount function, etc).
|
||||
|
||||
👉 For this, you use the [`composeStories`](#composestories) or [`composeStory`](#composestory) API. The composed Story is a renderable component that can be passed to your rendering mechanism.
|
||||
|
||||
### 5. Play
|
||||
|
||||
**(optional)**
|
||||
|
||||
Finally, stories can define a [play function](../essentials/interactions.md#play-function-for-interactions) to interact with the story and assert on details after it has rendered. In portable stories, the play function does not run automatically—you have to call it yourself.
|
||||
|
||||
👉 For this, you use the [`composeStories`](#composestories) or [`composeStory`](#composestory) API. The composed Story will return a `play` method to be called **after** it has rendered.
|
||||
|
||||
The play function needs a `canvasElement`, which should be passed by you. A `canvasElement` is the HTML element which wraps your component. Each testing utility provides different ways to retrieve such element, but here's how to do it with Testing Library:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
<CodeSnippets
|
||||
paths={[
|
||||
'react/portable-stories-vitest-with-play-function.ts.mdx',
|
||||
'vue/portable-stories-vitest-with-play-function.ts.mdx',
|
||||
]}
|
||||
/>
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
<Callout variant="info">
|
||||
|
||||
If your play function contains assertions (e.g. `expect` calls), your test will fail when those assertions fail.
|
||||
|
||||
</Callout>
|
||||
|
||||
## Overriding globals
|
||||
|
||||
If your stories behave differently based on [globals](../essentials/toolbars-and-globals.md#globals) (e.g. rendering text in English or Spanish), you can define those global values in portable stories by overriding project annotations when composing a story:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
<CodeSnippets
|
||||
paths={[
|
||||
'react/portable-stories-vitest-override-globals.ts.mdx',
|
||||
'vue/portable-stories-vitest-override-globals.ts.mdx',
|
||||
]}
|
||||
/>
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
<!-- End supported renderers -->
|
||||
|
||||
</If>
|
||||
@ -1,376 +0,0 @@
|
||||
---
|
||||
title: 'Portable stories'
|
||||
---
|
||||
|
||||
export const SUPPORTED_RENDERERS = ['react', 'vue'];
|
||||
|
||||
<If notRenderer={SUPPORTED_RENDERERS}>
|
||||
|
||||
<Callout variant="info">
|
||||
|
||||
Portable stories are currently only supported in [React](?renderer=react) and [Vue](?renderer=vue) projects.
|
||||
|
||||
</Callout>
|
||||
|
||||
</If>
|
||||
{/* End non-supported renderers */}
|
||||
|
||||
<If renderer={SUPPORTED_RENDERERS}>
|
||||
|
||||
Portable stories are Storybook [stories](../writing-stories/index.md) which can be used in external environments such as in a test (with Vitest, for instance). You can use the [`composeStories`](#composestories) and [`composeStory`](#composestory) functions to compose stories and their [annotations](#annotations), making them portable.
|
||||
|
||||
Normally, Storybok composes a story and its annotations automatically, as part of the [story pipeline](#story-pipeline). When using stories outside of Storybook, you must handle the story pipeline yourself.
|
||||
|
||||
## composeStories
|
||||
|
||||
`composeStories` will process all stories from the component's stories you specify, compose args/decorators in all of them and return an object containing the composed stories.
|
||||
|
||||
If you use the composed story (e.g. Primary button), the component will render with the args that are passed in the story. However, you are free to pass any props on top of the component, and those props will override the default values passed in the story's args.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
<CodeSnippets
|
||||
paths={[
|
||||
'react/portable-stories-compose-stories.ts.mdx',
|
||||
'vue/portable-stories-compose-stories.ts.mdx',
|
||||
]}
|
||||
/>
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
### Type
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
```ts
|
||||
(
|
||||
csfExports: CSF file exports,
|
||||
projectAnnotations?: ProjectAnnotations
|
||||
) => Record<string, ComposedStoryFn>
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
### Parameters
|
||||
|
||||
#### `csfExports`
|
||||
|
||||
(**Required**)
|
||||
|
||||
Type: CSF file exports
|
||||
|
||||
Specifies which component's stories you want to compose. Pass the **full set of exports** from the CSF file (not the default export!). E.g. `import * as stories from './Button.stories'`
|
||||
|
||||
#### `projectAnnotations`
|
||||
|
||||
Type: `ProjectAnnotation | ProjectAnnotation[]`
|
||||
|
||||
This parameter is provided for convenience. You should likely use [`setProjectAnnotations`](#setprojectannotations) instead. Details about the `ProjectAnnotation` type can be found in that function's [`projectAnnotations`](#projectannotations-2) parameter.
|
||||
|
||||
This parameter can be used to [override](#overriding-globals) the project annotations applied via `setProjectAnnotations`.
|
||||
|
||||
### Return
|
||||
|
||||
Type: `Record<string, ComposedStoryFn>`
|
||||
|
||||
An object where the keys are the names of the stories and the values are the composed stories.
|
||||
|
||||
Additionally, the composed story will have the following properties:
|
||||
|
||||
| Property | Type | Description |
|
||||
| ---------- | ----------------------------------------- | --------------------------------------------------------------- |
|
||||
| storyName | `string` | The story's name |
|
||||
| args | `Record<string, any>` | The story's [args](../writing-stories/args.md) |
|
||||
| argTypes | `ArgType` | The story's [argTypes](./arg-types.md) |
|
||||
| id | `string` | The story's id |
|
||||
| parameters | `Record<string, any>` | The story's [parameters](./parameters.md) |
|
||||
| load | `() => Promise<void>` | Executes all the [loaders](#2-load-optional) for a given story |
|
||||
| play | `(context) => Promise<void> \| undefined` | Executes the [play function](#4-play-optional) of a given story |
|
||||
|
||||
## composeStory
|
||||
|
||||
You can use `composeStory` if you wish to compose a single story for a component.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
<CodeSnippets
|
||||
paths={[
|
||||
'react/portable-stories-compose-story.ts.mdx',
|
||||
'vue/portable-stories-compose-story.ts.mdx',
|
||||
]}
|
||||
/>
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
### Type
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
```ts
|
||||
(
|
||||
story: Story export,
|
||||
componentAnnotations: Meta,
|
||||
projectAnnotations?: ProjectAnnotations,
|
||||
exportsName?: string
|
||||
) => ComposedStoryFn
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
### Parameters
|
||||
|
||||
#### `story`
|
||||
|
||||
(**Required**)
|
||||
|
||||
Type: `Story export`
|
||||
|
||||
Specifies which story you want to compose.
|
||||
|
||||
#### `componentAnnotations`
|
||||
|
||||
(**Required**)
|
||||
|
||||
Type: `Meta`
|
||||
|
||||
The default export from the stories file containing the [`story`](#story).
|
||||
|
||||
#### `projectAnnotations`
|
||||
|
||||
Type: `ProjectAnnotation | ProjectAnnotation[]`
|
||||
|
||||
This parameter is provided for convenience. You should likely use [`setProjectAnnotations`](#setprojectannotations) instead. Details about the `ProjectAnnotation` type can be found in that function's [`projectAnnotations`](#projectannotations-2) parameter.
|
||||
|
||||
This parameter can be used to [override](#overriding-globals) the project annotations applied via `setProjectAnnotations`.
|
||||
|
||||
#### `exportsName`
|
||||
|
||||
Type: `string`
|
||||
|
||||
You probably don't need this. Because `composeStory` accepts a single story, it does not have access to the name of that story's export in the file (like `composeStories` does). If you must ensure unique story names in your tests and you cannot use `composeStories`, you can pass the name of the story's export here.
|
||||
|
||||
### Return
|
||||
|
||||
Type: `ComposedStoryFn`
|
||||
|
||||
A single [composed story](#return).
|
||||
|
||||
## setProjectAnnotations
|
||||
|
||||
This API should be called once and before the tests run, typically in your testing tool's setup file. This will make sure that whenever `composeStories` or `composeStory` are used, the project annotations are taken into account as well.
|
||||
|
||||
```ts
|
||||
// setup-tests.ts
|
||||
// Replace <your-renderer> with your renderer, e.g. react, vue3
|
||||
import { setProjectAnnotations } from '@storybook/<your-renderer>';
|
||||
import * as addonAnnotations from 'my-addon/preview';
|
||||
import * as previewAnnotations from './.storybook/preview';
|
||||
|
||||
setProjectAnnotations([previewAnnotations, addonAnnotations]);
|
||||
```
|
||||
|
||||
### Type
|
||||
|
||||
```ts
|
||||
(projectAnnotations: ProjectAnnotation | ProjectAnnotation[]) => void
|
||||
```
|
||||
|
||||
### Parameters
|
||||
|
||||
#### `projectAnnotations`
|
||||
|
||||
(**Required**)
|
||||
|
||||
Type: `ProjectAnnotation | ProjectAnnotation[]`
|
||||
|
||||
A set of project [annotations](#annotations) (those defined in `.storybook/preview.js|ts`) or an array of sets of project annotations, which will be applied to all composed stories.
|
||||
|
||||
## Annotations
|
||||
|
||||
Annotations are the metadata like [args](../writing-stories/args.md), [decorators](../writing-stories/decorators.md), [loaders](../writing-stories/loaders.md), and [play functions](../writing-stories/play-function.md) that are applied to a story. They can be defined for a specific story, all stories for a component, or for all stories in the project.
|
||||
|
||||
## Story pipeline
|
||||
|
||||
Storybook has a "pipeline of steps", which occur from loading Storybook up until rendering the component in the browser:
|
||||
|
||||
|
||||
|
||||
When accessing a story in Storybook, you don't need to think about these steps, but it does help a lot in understanding how things work.
|
||||
|
||||
When you want to reuse a story in a different environment, however, it's crucial to understand that all these steps make a story. The portable stories API provides you with the mechanism to recreate that “pipeline” on your external environment.
|
||||
|
||||
By using portable stories, you will have to deal with things separately, and handle them in your testing environment mechanisms:
|
||||
|
||||
### 1. Prepare
|
||||
|
||||
You combine the annotations you need in your project so your components render correctly. That's the global config you set up in your `.storybook/preview.js` file, such as:
|
||||
|
||||
- global CSS
|
||||
- global decorators
|
||||
- global args
|
||||
- global loaders
|
||||
|
||||
👉 For this, you use the [`setProjectAnnotations`](#setprojectannotations) API.
|
||||
|
||||
### 2. Load (optional)
|
||||
|
||||
You execute the loaders for a given story, and pass the data down to it. This only applies to stories that use the [loader concept](../writing-stories/loaders.md)
|
||||
|
||||
👉 For this, you use the [`composeStories`](#composestories) or [`composeStory`](#composestory) API. The composed Story will return a `load` method to be called **before** it is rendered.
|
||||
|
||||
For example, your story might have a loader that prepares data for your story, such as setting up some mocks or fetching data which is available via the `loaded` property in the story context. In portable stories, the loaders are not applied automatically – you have to apply them yourself. To do so, you call the `load` method from your composed story before rendering your story.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
<CodeSnippets
|
||||
paths={[
|
||||
'react/portable-stories-with-loaders.ts.mdx',
|
||||
'vue/portable-stories-with-loaders.ts.mdx',
|
||||
]}
|
||||
/>
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
### 3. Render
|
||||
|
||||
The story has been prepared and can be rendered. You pass it into the rendering mechanism of your choice (e.g. Testing Library render function, Vue test utils mount function, etc.)
|
||||
|
||||
👉 For this, you use the [`composeStories`](#composestories) or [`composeStory`](#composestory) API. The composed Story is a renderable component that can be passed to your rendering mechanism.
|
||||
|
||||
### 4. Play (optional)
|
||||
|
||||
Once the component is rendered, you execute the play function which will contain interactions and assertions. This only applies for stories that use the [play function](../essentials/interactions.md#play-function-for-interactions).
|
||||
|
||||
👉 For this, you use the [`composeStories`](#composestories) or [`composeStory`](#composestory) API. The composed Story will return a `play` method to be called **after** it has rendered.
|
||||
|
||||
For example, your story might have a play function that prepares your component's desired state: in this case, clicking on a button to display a modal. In portable stories, the play function does not run automatically – you have to call it yourself. The play function needs a `canvasElement`, which should be passed by you. A `canvasElement` is the HTML element which wraps your component. Each testing utility provides different ways to retrieve such element, but here's how to do it with Testing Library:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
<CodeSnippets
|
||||
paths={[
|
||||
'react/portable-stories-with-play-function.ts.mdx',
|
||||
'vue/portable-stories-with-play-function.ts.mdx',
|
||||
]}
|
||||
/>
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
<Callout variant="info">
|
||||
|
||||
If your play function contains assertions (e.g. `expect` calls), your test will fail when those assertions fail.
|
||||
|
||||
</Callout>
|
||||
|
||||
## Overriding globals
|
||||
|
||||
If your stories behave differently based on [globals](../essentials/toolbars-and-globals.md#globals), such as they render text in English or Spanish, and such behavior can be changed via the toolbar items, you can achieve similar functionality in portable stories by overriding project annotations when composing a story:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
<CodeSnippets
|
||||
paths={[
|
||||
'react/portable-stories-override-globals.ts.mdx',
|
||||
'vue/portable-stories-override-globals.ts.mdx',
|
||||
]}
|
||||
/>
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
## Component testing integrations
|
||||
|
||||
### Playwright CT
|
||||
|
||||
Portable stories work in [Playwright CT](https://playwright.dev/docs/test-components), although with a few modifications, as well as different mounting mechanism.
|
||||
|
||||
To set the annotations, you use the `playwright/index.ts` file:
|
||||
|
||||
```ts
|
||||
// playwright/index.ts
|
||||
// Replace <your-renderer> with your renderer, e.g. react, vue3
|
||||
import { setProjectAnnotations } from '@storybook/<your-renderer>';
|
||||
import sbAnnotations from '../.storybook/preview';
|
||||
|
||||
setProjectAnnotations(sbAnnotations);
|
||||
```
|
||||
|
||||
To compose stories, however, due to Playwright's limitations\*, you have to compose the stories _in a separate file than your own test file_:
|
||||
|
||||
```ts
|
||||
// Button.playwright.stories.ts
|
||||
// Replace <your-renderer> with your renderer, e.g. react, vue3
|
||||
import { composeStories } from '@storybook/<your-renderer>';
|
||||
|
||||
import * as stories from './Button.stories';
|
||||
|
||||
// This function will be executed in the browser
|
||||
// and compose all stories, exporting them in a single object
|
||||
export default composeStories(stories);
|
||||
```
|
||||
|
||||
<Callout variant="warning">
|
||||
|
||||
\* The code which you write in your Playwright test file is transformed and orchestrated by Playwright, where part of the code executes in Node, while other parts execute in the browser.
|
||||
|
||||
[Read more about Playwright's component testing](https://playwright.dev/docs/test-components#test-stories).
|
||||
|
||||
</Callout>
|
||||
|
||||
When writing tests, instead of using Playwright's own `test` function, you can use Storybook's special `createTest` function which will extend Playwright's test functionality to add a custom `mount` mechanism which will load, render and play the story. This function is experimental and is subject to changes.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
<CodeSnippets
|
||||
paths={[
|
||||
'react/portable-stories-playwright-ct.ts.mdx',
|
||||
'vue/portable-stories-playwright-ct.ts.mdx',
|
||||
]}
|
||||
/>
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
### Cypress CT
|
||||
|
||||
Portable stories work in [Cypress CT](https://docs.cypress.io/guides/component-testing/overview), however there are currently some issues with loaders and play function which we need to investigate further.
|
||||
|
||||
To set the annotations, you use the `cypress/support/component.ts` file:
|
||||
|
||||
```ts
|
||||
// cypress/support/component.ts
|
||||
// Replace <your-renderer> with your renderer, e.g. react, vue3
|
||||
import { setProjectAnnotations } from '@storybook/<your-renderer>';
|
||||
import sbAnnotations from '../.storybook/preview';
|
||||
|
||||
setProjectAnnotations(sbAnnotations);
|
||||
```
|
||||
|
||||
You can compose stories in your Cypress test file pretty much the same way as in Vitest/Jest:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
<CodeSnippets
|
||||
paths={[
|
||||
'react/portable-stories-cypress-ct.ts.mdx',
|
||||
'vue/portable-stories-cypress-ct.ts.mdx',
|
||||
]}
|
||||
/>
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
The same goes for loaders/play function, you'd have to manually invoke them as such.
|
||||
|
||||
<Callout variant="warning">
|
||||
|
||||
Cypress doesn't use a normal Promise mechanism so we need to use `cy.then` in order to apply async await for loaders and play function.
|
||||
|
||||
</Callout>
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
<CodeSnippets
|
||||
paths={[
|
||||
'react/portable-stories-cypress-ct-async.ts.mdx',
|
||||
'vue/portable-stories-cypress-ct-async.ts.mdx',
|
||||
]}
|
||||
/>
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
</If>
|
||||
{/* End supported renderers */}
|
||||
BIN
docs/api/story-pipeline-playwright-ct.png
Normal file
BIN
docs/api/story-pipeline-playwright-ct.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 303 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 301 KiB After Width: | Height: | Size: 423 KiB |
@ -1,26 +0,0 @@
|
||||
```tsx
|
||||
// Button.test.tsx
|
||||
import { composeStories } from '@storybook/react';
|
||||
|
||||
import * as stories from './Button.stories';
|
||||
|
||||
const { CSF3Primary } = composeStories(stories);
|
||||
|
||||
describe('<Button />', () => {
|
||||
it('renders with loaders and play function', () => {
|
||||
cy.then(async () => {
|
||||
await CSF3Primary.load();
|
||||
});
|
||||
|
||||
cy.mount(<CSF3Primary />);
|
||||
|
||||
cy.then(async () => {
|
||||
await CSF3Primary.play({
|
||||
// data-cy-root is Cypress "App". The top-most wrapping element
|
||||
canvasElement: document.querySelector('[data-cy-root]'),
|
||||
});
|
||||
// Cypress assertions happen inside of this scope, after play
|
||||
});
|
||||
});
|
||||
});
|
||||
```
|
||||
@ -1,14 +0,0 @@
|
||||
```tsx
|
||||
// Button.test.tsx
|
||||
import { composeStories } from '@storybook/react';
|
||||
|
||||
import * as stories from './Button.stories';
|
||||
|
||||
const { CSF3Primary } = composeStories(stories);
|
||||
|
||||
describe('<Button />', () => {
|
||||
it('renders primary button', async () => {
|
||||
cy.mount(<CSF3Primary />);
|
||||
});
|
||||
});
|
||||
```
|
||||
@ -0,0 +1,26 @@
|
||||
```tsx
|
||||
// Button.test.tsx
|
||||
import { test, expect } from 'jest';
|
||||
import { render, screen } from '@testing-library/react';
|
||||
import { composeStories } from '@storybook/react';
|
||||
|
||||
// Import all stories and the component annotations from the stories file
|
||||
import * as stories from './Button.stories';
|
||||
|
||||
// Every component that is returned maps 1:1 with the stories,
|
||||
// but they already contain all annotations from story, meta, and project levels
|
||||
const { Primary, Secondary } = composeStories(stories);
|
||||
|
||||
test('renders primary button with default args', () => {
|
||||
render(<Primary />);
|
||||
const buttonElement = screen.getByText('Text coming from args in stories file!');
|
||||
expect(buttonElement).not.toBeNull();
|
||||
});
|
||||
|
||||
test('renders primary button with overriden props', () => {
|
||||
// You can override props and they will get merged with values from the story's args
|
||||
render(<Primary>Hello world</Primary>);
|
||||
const buttonElement = screen.getByText(/Hello world/i);
|
||||
expect(buttonElement).not.toBeNull();
|
||||
});
|
||||
```
|
||||
@ -0,0 +1,19 @@
|
||||
```tsx
|
||||
// Button.test.tsx
|
||||
import { jest, test, expect } from 'jest';
|
||||
import { render, screen } from '@testing-library/react';
|
||||
import { composeStory } from '@storybook/react';
|
||||
|
||||
import meta, { Primary } from './Button.stories';
|
||||
|
||||
test('onclick handler is called', () => {
|
||||
// Returns a story which already contains all annotations from story, meta and global levels
|
||||
const PrimaryStory = composeStory(Primary, meta);
|
||||
|
||||
const onClickSpy = jest.fn();
|
||||
render(<PrimaryStory onClick={onClickSpy} />);
|
||||
const buttonElement = screen.getByRole('button');
|
||||
buttonElement.click();
|
||||
expect(onClickSpy).toHaveBeenCalled();
|
||||
});
|
||||
```
|
||||
@ -0,0 +1,24 @@
|
||||
```tsx
|
||||
// Button.test.tsx
|
||||
import { test } from 'jest';
|
||||
import { render } from '@testing-library/react';
|
||||
import { composeStory } from '@storybook/react';
|
||||
|
||||
import meta, { Primary } from './Button.stories';
|
||||
|
||||
test('renders in English', async () => {
|
||||
const PrimaryStory = composeStory(
|
||||
Primary,
|
||||
meta,
|
||||
{ globalTypes: { locale: 'en' } } // 👈 Project annotations to override the locale
|
||||
);
|
||||
|
||||
render(<PrimaryStory />);
|
||||
});
|
||||
|
||||
test('renders in Spanish', async () => {
|
||||
const PrimaryStory = composeStory(Primary, meta, { globalTypes: { locale: 'es' } });
|
||||
|
||||
render(<PrimaryStory />);
|
||||
});
|
||||
```
|
||||
@ -0,0 +1,18 @@
|
||||
```tsx
|
||||
// Button.test.tsx
|
||||
import { test } from 'jest';
|
||||
import { render } from '@testing-library/react';
|
||||
import { composeStory } from '@storybook/react';
|
||||
|
||||
import meta, { Primary } from './Button.stories';
|
||||
|
||||
test('applies the loaders and renders', async () => {
|
||||
const PrimaryStory = composeStory(Primary, meta);
|
||||
|
||||
// First, load the data for the story
|
||||
await PrimaryStory.load();
|
||||
|
||||
// Then, render the story
|
||||
render(<PrimaryStory />);
|
||||
});
|
||||
```
|
||||
@ -9,7 +9,10 @@ import meta, { Primary } from './Button.stories';
|
||||
test('renders and executes the play function', async () => {
|
||||
const PrimaryStory = composeStory(Primary, meta);
|
||||
|
||||
// First, render the story
|
||||
const { container } = render(<PrimaryStory />);
|
||||
|
||||
// Then, execute the play function
|
||||
await PrimaryStory.play({ canvasElement: container });
|
||||
});
|
||||
```
|
||||
@ -10,6 +10,6 @@ const test = createTest(base);
|
||||
test('renders primary button', async ({ mount }) => {
|
||||
// The mount function will execute all the necessary steps in the story,
|
||||
// such as loaders, render, and play function
|
||||
await mount(<stories.CSF3Primary />);
|
||||
await mount(<stories.Primary />);
|
||||
});
|
||||
```
|
||||
|
||||
@ -4,11 +4,11 @@ import { test, expect } from 'vitest';
|
||||
import { render, screen } from '@testing-library/react';
|
||||
import { composeStories } from '@storybook/react';
|
||||
|
||||
// import all stories from the stories file
|
||||
// Import all stories and the component annotations from the stories file
|
||||
import * as stories from './Button.stories';
|
||||
|
||||
// Every component that is returned maps 1:1 with the stories,
|
||||
// but they already contain all decorators from story level, meta level and project level.
|
||||
// but they already contain all annotations from story, meta, and project levels
|
||||
const { Primary, Secondary } = composeStories(stories);
|
||||
|
||||
test('renders primary button with default args', () => {
|
||||
@ -18,7 +18,7 @@ test('renders primary button with default args', () => {
|
||||
});
|
||||
|
||||
test('renders primary button with overriden props', () => {
|
||||
// You can override props and they will get merged with values from the Story's args
|
||||
// You can override props and they will get merged with values from the story's args
|
||||
render(<Primary>Hello world</Primary>);
|
||||
const buttonElement = screen.getByText(/Hello world/i);
|
||||
expect(buttonElement).not.toBeNull();
|
||||
@ -7,7 +7,7 @@ import { composeStory } from '@storybook/react';
|
||||
import meta, { Primary } from './Button.stories';
|
||||
|
||||
test('onclick handler is called', () => {
|
||||
// Returns a component that already contain all decorators from story level, meta level and global level.
|
||||
// Returns a story which already contains all annotations from story, meta and global levels
|
||||
const PrimaryStory = composeStory(Primary, meta);
|
||||
|
||||
const onClickSpy = vi.fn();
|
||||
@ -9,7 +9,10 @@ import meta, { Primary } from './Button.stories';
|
||||
test('applies the loaders and renders', async () => {
|
||||
const PrimaryStory = composeStory(Primary, meta);
|
||||
|
||||
// First, load the data for the story
|
||||
await PrimaryStory.load();
|
||||
|
||||
// Then, render the story
|
||||
render(<PrimaryStory />);
|
||||
});
|
||||
```
|
||||
@ -0,0 +1,18 @@
|
||||
```tsx
|
||||
// Button.test.tsx
|
||||
import { test } from 'vitest';
|
||||
import { render } from '@testing-library/react';
|
||||
import { composeStory } from '@storybook/react';
|
||||
|
||||
import meta, { Primary } from './Button.stories';
|
||||
|
||||
test('renders and executes the play function', async () => {
|
||||
const PrimaryStory = composeStory(Primary, meta);
|
||||
|
||||
// First, render the story
|
||||
const { container } = render(<PrimaryStory />);
|
||||
|
||||
// Then, execute the play function
|
||||
await PrimaryStory.play({ canvasElement: container });
|
||||
});
|
||||
```
|
||||
@ -1,26 +0,0 @@
|
||||
```ts
|
||||
// Button.test.ts
|
||||
import { composeStories } from '@storybook/vue3';
|
||||
|
||||
import * as stories from './Button.stories';
|
||||
|
||||
const { CSF3Primary } = composeStories(stories);
|
||||
|
||||
describe('<Button />', () => {
|
||||
it('renders with loaders and play function', () => {
|
||||
cy.then(async () => {
|
||||
await CSF3Primary.load();
|
||||
});
|
||||
|
||||
cy.mount(CSF3Primary());
|
||||
|
||||
cy.then(async () => {
|
||||
await CSF3Primary.play({
|
||||
// data-cy-root is Cypress "App". The top-most wrapping element
|
||||
canvasElement: document.querySelector('[data-cy-root]'),
|
||||
});
|
||||
// Cypress assertions happen inside of this scope, after play
|
||||
});
|
||||
});
|
||||
});
|
||||
```
|
||||
@ -1,14 +0,0 @@
|
||||
```ts
|
||||
// Button.test.ts
|
||||
import { composeStories } from '@storybook/vue3';
|
||||
|
||||
import * as stories from './Button.stories';
|
||||
|
||||
const { CSF3Primary } = composeStories(stories);
|
||||
|
||||
describe('<Button />', () => {
|
||||
it('renders primary button', async () => {
|
||||
cy.mount(CSF3Primary());
|
||||
});
|
||||
});
|
||||
```
|
||||
@ -0,0 +1,26 @@
|
||||
```ts
|
||||
// Button.test.ts
|
||||
import { test, expect } from 'jest';
|
||||
import { render, screen } from '@testing-library/vue';
|
||||
import { composeStories } from '@storybook/vue3';
|
||||
|
||||
// Import all stories and the component annotations from the stories file
|
||||
import * as stories from './Button.stories';
|
||||
|
||||
// Every component that is returned maps 1:1 with the stories,
|
||||
// but they already contain all annotations from story, meta, and project levels
|
||||
const { Primary, Secondary } = composeStories(stories);
|
||||
|
||||
test('renders primary button with default args', () => {
|
||||
render(Primary());
|
||||
const buttonElement = screen.getByText('Text coming from args in stories file!');
|
||||
expect(buttonElement).not.toBeNull();
|
||||
});
|
||||
|
||||
test('renders primary button with overriden props', () => {
|
||||
// You can override props and they will get merged with values from the story's args
|
||||
render(Primary({ label: 'Hello world' }));
|
||||
const buttonElement = screen.getByText(/Hello world/i);
|
||||
expect(buttonElement).not.toBeNull();
|
||||
});
|
||||
```
|
||||
19
docs/snippets/vue/portable-stories-jest-compose-story.ts.mdx
Normal file
19
docs/snippets/vue/portable-stories-jest-compose-story.ts.mdx
Normal file
@ -0,0 +1,19 @@
|
||||
```ts
|
||||
// Button.test.ts
|
||||
import { jest, test, expect } from 'jest';
|
||||
import { render, screen } from '@testing-library/vue';
|
||||
import { composeStory } from '@storybook/vue3';
|
||||
|
||||
import meta, { Primary } from './Button.stories';
|
||||
|
||||
test('onclick handler is called', () => {
|
||||
// Returns a story which already contains all annotations from story, meta and global levels
|
||||
const PrimaryStory = composeStory(Primary, meta);
|
||||
|
||||
const onClickSpy = jest.fn();
|
||||
render(Primary({ onClick: onClickSpy }));
|
||||
const buttonElement = screen.getByRole('button');
|
||||
buttonElement.click();
|
||||
expect(onClickSpy).toHaveBeenCalled();
|
||||
});
|
||||
```
|
||||
@ -9,7 +9,10 @@ import meta, { Primary } from './Button.stories';
|
||||
test('applies the loaders and renders', async () => {
|
||||
const PrimaryStory = composeStory(Primary, meta);
|
||||
|
||||
// First, load the data for the story
|
||||
await PrimaryStory.load();
|
||||
|
||||
// Then, render the story
|
||||
render(PrimaryStory());
|
||||
});
|
||||
```
|
||||
@ -9,7 +9,10 @@ import meta, { Primary } from './Button.stories';
|
||||
test('renders and executes the play function', async () => {
|
||||
const PrimaryStory = composeStory(Primary, meta);
|
||||
|
||||
// First, render the story
|
||||
const { container } = render(PrimaryStory());
|
||||
|
||||
// Then, execute the play function
|
||||
await PrimaryStory.play({ canvasElement: container });
|
||||
});
|
||||
```
|
||||
@ -10,6 +10,6 @@ const test = createTest(base);
|
||||
test('renders primary button', async ({ mount }) => {
|
||||
// The mount function will execute all the necessary steps in the story,
|
||||
// such as loaders, render, and play function
|
||||
await mount(stories.CSF3Primary());
|
||||
await mount(stories.Primary());
|
||||
});
|
||||
```
|
||||
|
||||
@ -4,11 +4,11 @@ import { test, expect } from 'vitest';
|
||||
import { render, screen } from '@testing-library/vue';
|
||||
import { composeStories } from '@storybook/vue3';
|
||||
|
||||
// import all stories from the stories file
|
||||
// Import all stories and the component annotations from the stories file
|
||||
import * as stories from './Button.stories';
|
||||
|
||||
// Every component that is returned maps 1:1 with the stories,
|
||||
// but they already contain all decorators from story level, meta level and project level.
|
||||
// but they already contain all annotations from story, meta, and project levels
|
||||
const { Primary, Secondary } = composeStories(stories);
|
||||
|
||||
test('renders primary button with default args', () => {
|
||||
@ -18,7 +18,7 @@ test('renders primary button with default args', () => {
|
||||
});
|
||||
|
||||
test('renders primary button with overriden props', () => {
|
||||
// You can override props and they will get merged with values from the Story's args
|
||||
// You can override props and they will get merged with values from the story's args
|
||||
render(Primary({ label: 'Hello world' }));
|
||||
const buttonElement = screen.getByText(/Hello world/i);
|
||||
expect(buttonElement).not.toBeNull();
|
||||
@ -7,7 +7,7 @@ import { composeStory } from '@storybook/vue3';
|
||||
import meta, { Primary } from './Button.stories';
|
||||
|
||||
test('onclick handler is called', () => {
|
||||
// Returns a component that already contain all decorators from story level, meta level and global level.
|
||||
// Returns a story which already contains all annotations from story, meta and global levels
|
||||
const PrimaryStory = composeStory(Primary, meta);
|
||||
|
||||
const onClickSpy = vi.fn();
|
||||
@ -0,0 +1,24 @@
|
||||
```ts
|
||||
// Button.test.ts
|
||||
import { test } from 'vitest';
|
||||
import { render } from '@testing-library/vue';
|
||||
import { composeStory } from '@storybook/vue3';
|
||||
|
||||
import meta, { Primary } from './Button.stories';
|
||||
|
||||
test('renders in English', async () => {
|
||||
const PrimaryStory = composeStory(
|
||||
Primary,
|
||||
meta,
|
||||
{ globalTypes: { locale: 'en' } } // 👈 Project annotations to override the locale
|
||||
);
|
||||
|
||||
render(PrimaryStory());
|
||||
});
|
||||
|
||||
test('renders in Spanish', async () => {
|
||||
const PrimaryStory = composeStory(Primary, meta, { globalTypes: { locale: 'es' } });
|
||||
|
||||
render(PrimaryStory());
|
||||
});
|
||||
```
|
||||
@ -0,0 +1,18 @@
|
||||
```ts
|
||||
// Button.test.ts
|
||||
import { test } from 'vitest';
|
||||
import { render } from '@testing-library/vue';
|
||||
import { composeStory } from '@storybook/vue3';
|
||||
|
||||
import meta, { Primary } from './Button.stories';
|
||||
|
||||
test('applies the loaders and renders', async () => {
|
||||
const PrimaryStory = composeStory(Primary, meta);
|
||||
|
||||
// First, load the data for the story
|
||||
await PrimaryStory.load();
|
||||
|
||||
// Then, render the story
|
||||
render(PrimaryStory());
|
||||
});
|
||||
```
|
||||
@ -0,0 +1,18 @@
|
||||
```ts
|
||||
// Button.test.ts
|
||||
import { test } from 'vitest';
|
||||
import { render } from '@testing-library/vue';
|
||||
import { composeStory } from '@storybook/vue3';
|
||||
|
||||
import meta, { Primary } from './Button.stories';
|
||||
|
||||
test('renders and executes the play function', async () => {
|
||||
const PrimaryStory = composeStory(Primary, meta);
|
||||
|
||||
// First, render the story
|
||||
const { container } = render(PrimaryStory());
|
||||
|
||||
// Then, execute the play function
|
||||
await PrimaryStory.play({ canvasElement: container });
|
||||
});
|
||||
```
|
||||
22
docs/toc.js
22
docs/toc.js
@ -692,10 +692,28 @@ module.exports = {
|
||||
],
|
||||
},
|
||||
{
|
||||
pathSegment: 'portable-stories',
|
||||
title: 'Portable stories',
|
||||
type: 'link',
|
||||
pathSegment: '',
|
||||
type: 'menu',
|
||||
children: [
|
||||
{
|
||||
pathSegment: 'portable-stories-jest',
|
||||
title: 'Jest',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'portable-stories-playwright',
|
||||
title: 'Playwright',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'portable-stories-vitest',
|
||||
title: 'Vitest',
|
||||
type: 'link',
|
||||
},
|
||||
],
|
||||
},
|
||||
|
||||
{
|
||||
pathSegment: 'new-frameworks',
|
||||
title: 'Frameworks',
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user