GitHub/storybook
1
0
Fork 0
mirror of https://github.com/storybookjs/storybook.git synced 2025-04-05 08:01:20 +08:00
Code Issues Packages Projects Releases Wiki Activity

Snippetize examples

Browse Source
This commit is contained in:
Kyle Gach 2024-04-30 22:21:31 -06:00
parent 39689acb78
commit 1dca308bf4
55 changed files with 1368 additions and 498 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

238
docs/get-started/nextjs.md
View File

@ -728,47 +728,29 @@ How you mock other modules in Storybook depends on how you import the module int
With either approach, the first step is to [create a mock file](../writing-stories/mocking-modules.md#mock-files). Here's an example of a mock file for a module named `session`:
<!-- TODO: Snippetize -->
<!-- prettier-ignore-start -->
```ts
// lib/session.mock.ts
import { fn } from '@storybook/test';
import * as actual from './session';
<CodeSnippets
paths={[
'common/storybook-test-mock-file-example.ts.mdx',
]}
/>
export * from './session';
export const getUserFromSession = fn(actual.getUserFromSession);
```
<!-- prettier-ignore-end -->
#### With subpath imports
If you're using [subpath imports](#subpath-imports), you can adjust your configuration to apply [conditions](../writing-stories/mocking-modules.md#subpath-imports) so that the mocked module is used inside Storybook. The example below configures subpath imports for four internal modules, which are then mocked in Storybook:
<!-- TODO: Snippetize -->
<!-- prettier-ignore-start -->
```jsonc
// package.json
{
"imports": {
"#api": {
"storybook": "./api.mock.ts",
"default": "./api.ts"
},
"#app/actions": {
"storybook": "./app/actions.mock.ts",
"default": "./app/actions.ts"
},
"#lib/session": {
"storybook": "./lib/session.mock.ts",
"default": "./lib/session.ts"
},
"#lib/db": {
"storybook": "./lib/db.mock.ts",
"default": "./lib/db.ts"
},
"#*": ["./*", "./*.ts", "./*.tsx"]
}
}
```
<CodeSnippets
paths={[
'common/subpath-imports-config.json.mdx',
]}
/>
<!-- prettier-ignore-end -->
<Callout variant="info">
@ -780,27 +762,16 @@ Each subpath must begin with `#`, to differentiate it from a regular module path
If you're using [module aliases](#module-aliases), you can add a Webpack alias to your Storybook configuration to point to the mock file.
<!-- TODO: Snippetize -->
<!-- prettier-ignore-start -->
```ts
// .storybook/main.ts
webpackFinal: async (config) => {
if (config.resolve) {
config.resolve.alias = {
...config.resolve.alias,
// 👇 External module
'lodash': require.resolve('./lodash.mock'),
// 👇 Internal modules
'@/api$': path.resolve(__dirname, "./api.mock.ts"),
'@/app/actions$': path.resolve(__dirname, "./app/actions.mock.ts"),
'@/lib/session$': path.resolve(__dirname, "./lib/session.mock.ts"),
'@/lib/db$': path.resolve(__dirname, "./lib/db.mock.ts"),
}
}
<CodeSnippets
paths={[
'common/module-aliases-config.webpack.ts.mdx',
'common/module-aliases-config.webpack.js.mdx',
]}
/>
return config;
},
```
<!-- prettier-ignore-end -->
## Runtime config
@ -1061,35 +1032,16 @@ Type: `typeof import('next/cache')`
This module exports mocked implementations of the `next/cache` module's exports. You can use it to create your own mock implementations or assert on mock calls in a story's [play function](../writing-stories/play-function.md).
<!-- TODO: Snippetize -->
<!-- prettier-ignore-start -->
```ts
// MyForm.stories.ts
import { expect, userEvent, within } from '@storybook/test';
import { Meta, StoryObj } from '@storybook/react';
// 👇 Must use this import path to have mocks typed correctly
import { revalidatePath } from '@storybook/nextjs/cache.mock';
import MyForm from './my-form';
<CodeSnippets
paths={[
'react/nextjs-cache-mock.js.mdx',
'react/nextjs-cache-mock.ts.mdx'
]}
/>
const meta = {
component: MyForm,
} satisfies Meta<typeof MyForm>;
export default meta;
type Story = StoryObj<typeof meta>;
export const Submitted: Story = {
async play({ canvasElement }) {
const canvas = within(canvasElement);
const submitButton = canvas.getByRole('button', { name: /submit/i });
await userEvent.click(saveButton);
// 👇 Use any mock assertions on the function
await expect(revalidatePath).toHaveBeenCalledWith('/');
},
};
```
<!-- prettier-ignore-end -->
#### `@storybook/nextjs/headers.mock`
@ -1107,39 +1059,16 @@ For cookies, you can use the existing API to write them. E.g., `cookies().set('f
Because `headers()`, `cookies()` and their sub-functions are all mocks you can use any [mock utilities](https://vitest.dev/api/mock.html) in your stories, like `headers().getAll.mock.calls`.
<!-- TODO: Snippetize -->
<!-- prettier-ignore-start -->
```ts
// MyForm.stories.ts
import { expect, fireEvent, userEvent, within } from '@storybook/test';
import { Meta, StoryObj } from '@storybook/react';
// 👇 Must use this import path to have mocks typed correctly
import { cookies, headers } from '@storybook/nextjs/headers.mock';
import MyForm from './my-form';
<CodeSnippets
paths={[
'react/nextjs-headers-mock.js.mdx',
'react/nextjs-headers-mock.ts.mdx'
]}
/>
const meta = {
component: MyForm,
} satisfies Meta<typeof MyForm>;
export default meta;
type Story = StoryObj<typeof meta>;
export const LoggedInEurope: Story = {
async beforeEach() {
// 👇 Set mock cookies and headers ahead of rendering
cookies().set('username', 'Sol');
headers().set('timezone', 'Central European Summer Time');
},
async play() {
// 👇 Assert that your component called the mocks
await expect(cookies().get).toHaveBeenCalledOnce();
await expect(cookies().get).toHaveBeenCalledWith('username');
await expect(headers().get).toHaveBeenCalledOnce();
await expect(cookies().get).toHaveBeenCalledWith('timezone');
},
};
```
<!-- prettier-ignore-end -->
#### `@storybook/nextjs/navigation.mock`
@ -1147,48 +1076,16 @@ Type: `typeof import('next/navigation') & getRouter: () => ReturnType<typeof imp
This module exports mocked implementations of the `next/navigation` module's exports. It also exports a `getRouter` function that returns a mocked version of [Next.js's `router` object from `useRouter`](https://nextjs.org/docs/app/api-reference/functions/use-router#userouter), allowing the properties to be manipulated and asserted on. You can use it mock implementations or assert on mock calls in a story's [play function](../writing-stories/play-function.md).
<!-- TODO: Snippetize -->
<!-- prettier-ignore-start -->
```ts
// MyForm.stories.ts
import { expect, fireEvent, userEvent, within } from '@storybook/test';
import { Meta, StoryObj } from '@storybook/react';
// 👇 Must use this import path to have mocks typed correctly
import { redirect, getRouter } from '@storybook/nextjs/navigation.mock';
import MyForm from './my-form';
<CodeSnippets
paths={[
'react/nextjs-navigation-mock.js.mdx',
'react/nextjs-navigation-mock.ts.mdx'
]}
/>
const meta = {
component: MyForm,
parameters: {
nextjs: {
// 👇 As in the Next.js application, next/navigation only works using App Router
appDirectory: true,
},
},
} satisfies Meta<typeof MyForm>;
export default meta;
type Story = StoryObj<typeof meta>;
export const Unauthenticated: Story = {
async play() => {
// 👇 Assert that your component called redirect()
await expect(redirect).toHaveBeenCalledWith('/login', 'replace');
},
};
export const GoBack: Story = {
async play({ canvasElement }) {
const canvas = within(canvasElement);
const backBtn = await canvas.findByText('Go back');
await userEvent.click(backBtn);
// 👇 Assert that your component called back()
await expect(getRouter().back).toHaveBeenCalled();
},
};
```
<!-- prettier-ignore-end -->
#### `@storybook/nextjs/router.mock`
@ -1196,41 +1093,16 @@ Type: `typeof import('next/router') & getRouter: () => ReturnType<typeof import(
This module exports mocked implementations of the `next/router` module's exports. It also exports a `getRouter` function that returns a mocked version of [Next.js's `router` object from `useRouter`](https://nextjs.org/docs/pages/api-reference/functions/use-router#router-object), allowing the properties to be manipulated and asserted on. You can use it mock implementations or assert on mock calls in a story's [play function](../writing-stories/play-function.md).
<!-- TODO: Snippetize -->
<!-- prettier-ignore-start -->
```ts
// MyForm.stories.ts
import { expect, fireEvent, userEvent, within } from '@storybook/test';
import { Meta, StoryObj } from '@storybook/react';
// 👇 Must use this import path to have mocks typed correctly
import { getRouter } from '@storybook/nextjs/router.mock';
import MyForm from './my-form';
<CodeSnippets
paths={[
'react/nextjs-router-mock.js.mdx',
'react/nextjs-router-mock.ts.mdx'
]}
/>
const meta = {
component: MyForm,
parameters: {
nextjs: {
// 👇 As in the Next.js application, next/router only works using Pages Router
appDirectory: false,
},
},
} satisfies Meta<typeof MyForm>;
export default meta;
type Story = StoryObj<typeof meta>;
export const GoBack: Story = {
async play({ canvasElement }) {
const canvas = within(canvasElement);
const backBtn = await canvas.findByText('Go back');
await userEvent.click(backBtn);
// 👇 Assert that your component called back()
await expect(getRouter().back).toHaveBeenCalled();
},
};
```
<!-- prettier-ignore-end -->
### Options

31
docs/snippets/angular/before-each-in-meta-mock-date.ts.mdx Normal file
View File

@ -0,0 +1,31 @@
```ts
// Page.stories.ts
import { Meta, StoryObj } from '@storybook/angular';
import MockDate from 'mockdate';
// 👇 Must use this import path to have mocks typed correctly
import { getUserFromSession } from '#api/session.mock';
import { Page } from './Page';
const meta: Meta<Page> = {
component: Page,
// 👇 Set the value of Date for every story in the file
async beforeEach() {
MockDate.set('2024-02-14');
// 👇 Reset the Date after each story
return () => {
MockDate.reset();
};
},
};
export default meta;
type Story = StoryObj<Page>;
export const Default: Story = {
async play({ canvasElement }) {
// ... This will run with the mocked Date
},
};
```

36
docs/snippets/angular/storybook-test-fn-mock-spy.ts.mdx Normal file
View File

@ -0,0 +1,36 @@
```ts
// NoteUI.stories.ts
import { Meta, StoryObj } from '@storybook/angular';
import { expect, userEvent, within } from '@storybook/test';
// 👇 Must use this import path to have mocks typed correctly
import { saveNote } from '#app/actions.mock';
import { createNotes } from '#mocks/notes';
import NoteUI from './note-ui';
const meta: Meta<NoteUI> = {
title: 'Mocked/NoteUI',
component: NoteUI,
};
export default meta;
type Story = StoryObj<NoteUI>;
const notes = createNotes();
export const SaveFlow: Story = {
name: 'Save Flow ▶',
args: {
isEditing: true,
note: notes[0],
},
play: async ({ canvasElement, step }) => {
const canvas = within(canvasElement);
const saveButton = canvas.getByRole('menuitem', { name: /done/i });
await userEvent.click(saveButton);
// 👇 This is the mock function, so you can assert its behavior
await expect(saveNote).toHaveBeenCalled();
},
};
```

22
docs/snippets/angular/storybook-test-mock-return-value.ts.mdx Normal file
View File

@ -0,0 +1,22 @@
```ts
// Page.stories.ts
import type { Meta, StoryObj } from '@storybook/angular';
// 👇 Must use this import path to have mocks typed correctly
import { getUserFromSession } from '#api/session.mock';
import { Page } from './Page';
const meta: Meta<Page> = {
component: Page,
};
export default meta;
type Story = StoryObj<Page>;
export const Default: Story = {
async beforeEach() {
// 👇 Set the return value for the getUserFromSession function
getUserFromSession.mockReturnValue({ id: '1', name: 'Alice' });
},
};
```

26
docs/snippets/common/before-each-in-meta-mock-date.js.mdx Normal file
View File

@ -0,0 +1,26 @@
```ts
// Page.stories.ts
import MockDate from 'mockdate';
import { getUserFromSession } from '#api/session.mock';
import { Page } from './Page';
export default {
component: Page,
// 👇 Set the value of Date for every story in the file
async beforeEach() {
MockDate.set('2024-02-14');
// 👇 Reset the Date after each story
return () => {
MockDate.reset();
};
},
};
export const Default: Story = {
async play({ canvasElement }) {
// ... This will run with the mocked Date
},
};
```

32
docs/snippets/common/before-each-in-meta-mock-date.ts-4-9.mdx Normal file
View File

@ -0,0 +1,32 @@
```ts
// Page.stories.ts
// Replace your-renderer with the name of your renderer (e.g. react, vue3)
import type { Meta, StoryObj } from '@storybook/your-renderer';
import MockDate from 'mockdate';
// 👇 Must use this import path to have mocks typed correctly
import { getUserFromSession } from '#api/session.mock';
import { Page } from './Page';
const meta = {
component: Page,
// 👇 Set the value of Date for every story in the file
async beforeEach() {
MockDate.set('2024-02-14');
// 👇 Reset the Date after each story
return () => {
MockDate.reset();
};
},
} satisfies Meta<typeof Page>;
export default meta;
type Story = StoryObj<typeof meta>;
export const Default: Story = {
async play({ canvasElement }) {
// ... This will run with the mocked Date
},
};
```

32
docs/snippets/common/before-each-in-meta-mock-date.ts.mdx Normal file
View File

@ -0,0 +1,32 @@
```ts
// Page.stories.ts
// Replace your-renderer with the name of your renderer (e.g. react, vue3)
import type { Meta, StoryObj } from '@storybook/your-renderer';
import MockDate from 'mockdate';
// 👇 Must use this import path to have mocks typed correctly
import { getUserFromSession } from '#api/session.mock';
import { Page } from './Page';
const meta: Meta<typeof Page> = {
component: Page,
// 👇 Set the value of Date for every story in the file
async beforeEach() {
MockDate.set('2024-02-14');
// 👇 Reset the Date after each story
return () => {
MockDate.reset();
};
},
};
export default meta;
type Story = StoryObj<typeof Page>;
export const Default: Story = {
async play({ canvasElement }) {
// ... This will run with the mocked Date
},
};
```

25
docs/snippets/common/module-aliases-config.vite.js.mdx Normal file
View File

@ -0,0 +1,25 @@
```js
// .storybook/main.js
export default {
// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
framework: '@storybook/your-framework',
stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
viteFinal: async (config) => {
if (config.resolve) {
config.resolve.alias = {
...config.resolve?.alias,
// 👇 External module
'lodash': require.resolve('./lodash.mock'),
// 👇 Internal modules
'@/api': path.resolve(__dirname, "./api.mock.ts"),
'@/app/actions': path.resolve(__dirname, "./app/actions.mock.ts"),
'@/lib/session': path.resolve(__dirname, "./lib/session.mock.ts"),
'@/lib/db': path.resolve(__dirname, "./lib/db.mock.ts"),
}
}
return config;
},
};
```

29
docs/snippets/common/module-aliases-config.vite.ts.mdx Normal file
View File

@ -0,0 +1,29 @@
```ts
// .storybook/main.ts
// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
import type { StorybookConfig } from '@storybook/your-framework';
const config: StorybookConfig = {
framework: '@storybook/your-framework',
stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
viteFinal: async (config) => {
if (config.resolve) {
config.resolve.alias = {
...config.resolve?.alias,
// 👇 External module
'lodash': require.resolve('./lodash.mock'),
// 👇 Internal modules
'@/api': path.resolve(__dirname, "./api.mock.ts"),
'@/app/actions': path.resolve(__dirname, "./app/actions.mock.ts"),
'@/lib/session': path.resolve(__dirname, "./lib/session.mock.ts"),
'@/lib/db': path.resolve(__dirname, "./lib/db.mock.ts"),
}
}
return config;
},
};
export default config;
```

25
docs/snippets/common/module-aliases-config.webpack.js.mdx Normal file
View File

@ -0,0 +1,25 @@
```js
// .storybook/main.js
export default {
// Replace your-framework with the framework you are using (e.g., nextjs, vue3-vite)
framework: '@storybook/your-framework',
stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
webpackFinal: async (config) => {
if (config.resolve) {
config.resolve.alias = {
...config.resolve.alias,
// 👇 External module
'lodash': require.resolve('./lodash.mock'),
// 👇 Internal modules
'@/api$': path.resolve(__dirname, "./api.mock.ts"),
'@/app/actions$': path.resolve(__dirname, "./app/actions.mock.ts"),
'@/lib/session$': path.resolve(__dirname, "./lib/session.mock.ts"),
'@/lib/db$': path.resolve(__dirname, "./lib/db.mock.ts"),
}
}
return config;
},
};
```

29
docs/snippets/common/module-aliases-config.webpack.ts.mdx Normal file
View File

@ -0,0 +1,29 @@
```ts
// .storybook/main.ts
// Replace your-framework with the framework you are using (e.g., nextjs, vue3-vite)
import type { StorybookConfig } from '@storybook/your-framework';
const config: StorybookConfig = {
framework: '@storybook/your-framework',
stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
webpackFinal: async (config) => {
if (config.resolve) {
config.resolve.alias = {
...config.resolve.alias,
// 👇 External module
'lodash': require.resolve('./lodash.mock'),
// 👇 Internal modules
'@/api$': path.resolve(__dirname, "./api.mock.ts"),
'@/app/actions$': path.resolve(__dirname, "./app/actions.mock.ts"),
'@/lib/session$': path.resolve(__dirname, "./lib/session.mock.ts"),
'@/lib/db$': path.resolve(__dirname, "./lib/db.mock.ts"),
}
}
return config;
},
};
export default config;
```

3
docs/snippets/common/msw-addon-install.npm.js.mdx Normal file
View File

@ -0,0 +1,3 @@
```sh
npm install msw msw-storybook-addon --save-dev
```

3
docs/snippets/common/msw-addon-install.pnpm.js.mdx Normal file
View File

@ -0,0 +1,3 @@
```sh
pnpm add msw msw-storybook-addon --save-dev
```

3
docs/snippets/common/msw-addon-install.yarn.js.mdx Normal file
View File

@ -0,0 +1,3 @@
```sh
yarn add msw msw-storybook-addon --save-dev
```

3
docs/snippets/common/msw-install.npm.js.mdx
View File

@ -1,3 +0,0 @@
```sh
npm install msw --save-dev
```

3
docs/snippets/common/msw-install.pnpm.js.mdx
View File

@ -1,3 +0,0 @@
```sh
pnpm add msw --save-dev
```

3
docs/snippets/common/msw-install.yarn.js.mdx
View File

@ -1,3 +0,0 @@
```sh
yarn add msw --save-dev
```

31
docs/snippets/common/storybook-test-fn-mock-spy.js.mdx Normal file
View File

@ -0,0 +1,31 @@
```js
// NoteUI.stories.js
import { expect, userEvent, within } from '@storybook/test';
import { saveNote } from '#app/actions.mock';
import { createNotes } from '#mocks/notes';
import NoteUI from './note-ui';
export default {
title: 'Mocked/NoteUI',
component: NoteUI,
};
const notes = createNotes();
export const SaveFlow = {
name: 'Save Flow ▶',
args: {
isEditing: true,
note: notes[0],
},
play: async ({ canvasElement, step }) => {
const canvas = within(canvasElement);
const saveButton = canvas.getByRole('menuitem', { name: /done/i });
await userEvent.click(saveButton);
// 👇 This is the mock function, so you can assert its behavior
await expect(saveNote).toHaveBeenCalled();
},
};
```

37
docs/snippets/common/storybook-test-fn-mock-spy.ts-4-9.mdx Normal file
View File

@ -0,0 +1,37 @@
```ts
// NoteUI.stories.ts
// Replace your-renderer with the name of your renderer (e.g. react, vue3)
import type { Meta, StoryObj } from '@storybook/your-renderer';
import { expect, userEvent, within } from '@storybook/test';
// 👇 Must use this import path to have mocks typed correctly
import { saveNote } from '#app/actions.mock';
import { createNotes } from '#mocks/notes';
import NoteUI from './note-ui';
const meta = {
title: 'Mocked/NoteUI',
component: NoteUI,
} satisfies Meta<typeof NoteUI>;
export default meta;
type Story = StoryObj<typeof meta>;
const notes = createNotes();
export const SaveFlow: Story = {
name: 'Save Flow ▶',
args: {
isEditing: true,
note: notes[0],
},
play: async ({ canvasElement, step }) => {
const canvas = within(canvasElement);
const saveButton = canvas.getByRole('menuitem', { name: /done/i });
await userEvent.click(saveButton);
// 👇 This is the mock function, so you can assert its behavior
await expect(saveNote).toHaveBeenCalled();
},
};
```

37
docs/snippets/common/storybook-test-fn-mock-spy.ts.mdx Normal file
View File

@ -0,0 +1,37 @@
```ts
// NoteUI.stories.ts
// Replace your-renderer with the name of your renderer (e.g. react, vue3)
import type { Meta, StoryObj } from '@storybook/your-renderer';
import { expect, userEvent, within } from '@storybook/test';
// 👇 Must use this import path to have mocks typed correctly
import { saveNote } from '#app/actions.mock';
import { createNotes } from '#mocks/notes';
import NoteUI from './note-ui';
const meta: Meta<typeof NoteUI> = {
title: 'Mocked/NoteUI',
component: NoteUI,
};
export default meta;
type Story = StoryObj<typeof NoteUI>;
const notes = createNotes();
export const SaveFlow: Story = {
name: 'Save Flow ▶',
args: {
isEditing: true,
note: notes[0],
},
play: async ({ canvasElement, step }) => {
const canvas = within(canvasElement);
const saveButton = canvas.getByRole('menuitem', { name: /done/i });
await userEvent.click(saveButton);
// 👇 This is the mock function, so you can assert its behavior
await expect(saveNote).toHaveBeenCalled();
},
};
```

8
docs/snippets/common/storybook-test-mock-file-example.ts.mdx Normal file
View File

@ -0,0 +1,8 @@
```ts
// lib/session.mock.ts
import { fn } from '@storybook/test';
import * as actual from './session';
export * from './session';
export const getUserFromSession = fn(actual.getUserFromSession);
```

18
docs/snippets/common/storybook-test-mock-return-value.js.mdx Normal file
View File

@ -0,0 +1,18 @@
```js
// Page.stories.js
import { fn } from '@storybook/test';
import { getUserFromSession } from '#api/session.mock';
import { Page } from './Page';
export default {
component: Page,
};
export const Default = {
async beforeEach() {
// 👇 Set the return value for the getUserFromSession function
getUserFromSession.mockReturnValue({ id: '1', name: 'Alice' });
},
};
```

25
docs/snippets/common/storybook-test-mock-return-value.ts-4-9.mdx Normal file
View File

@ -0,0 +1,25 @@
```ts
// Page.stories.ts
// Replace your-renderer with the name of your renderer (e.g. react, vue3)
import type { Meta, StoryObj } from '@storybook/your-renderer';
import { fn } from '@storybook/test';
// 👇 Must use this import path to have mocks typed correctly
import { getUserFromSession } from '#api/session.mock';
import { Page } from './Page';
const meta = {
component: Page,
} satisfies Meta<typeof Page>;
export default meta;
type Story = StoryObj<typeof meta>;
export const Default: Story = {
async beforeEach() {
// 👇 Set the return value for the getUserFromSession function
getUserFromSession.mockReturnValue({ id: '1', name: 'Alice' });
},
};
```

24
docs/snippets/common/storybook-test-mock-return-value.ts.mdx Normal file
View File

@ -0,0 +1,24 @@
```ts
// Page.stories.ts
// Replace your-renderer with the name of your renderer (e.g. react, vue3)
import type { Meta, StoryObj } from '@storybook/your-renderer';
import { fn } from '@storybook/test';
// 👇 Must use this import path to have mocks typed correctly
import { getUserFromSession } from '#api/session.mock';
import { Page } from './Page';
const meta: Meta<typeof Page> = {
component: Page,
};
export default meta;
type Story = StoryObj<typeof Page>;
export const Default: Story = {
async beforeEach() {
// 👇 Set the return value for the getUserFromSession function
getUserFromSession.mockReturnValue({ id: '1', name: 'Alice' });
},
};
```

24
docs/snippets/common/subpath-imports-config.json.mdx Normal file
View File

@ -0,0 +1,24 @@
```jsonc
// package.json
{
"imports": {
"#api": {
"storybook": "./api.mock.ts",
"default": "./api.ts"
},
"#app/actions": {
"storybook": "./app/actions.mock.ts",
"default": "./app/actions.ts"
},
"#lib/session": {
"storybook": "./lib/session.mock.ts",
"default": "./lib/session.ts"
},
"#lib/db": {
"storybook": "./lib/db.mock.ts",
"default": "./lib/db.ts"
},
"#*": ["./*", "./*.ts", "./*.tsx"]
}
}
```

18
docs/snippets/react/configure-mock-provider-with-story-parameter.js.mdx Normal file
View File

@ -0,0 +1,18 @@
```js
// Button.stories.js
import { Button } from './Button';
export default {
component: Button,
};
// Wrapped in light theme
export const Default = {};
// Wrapped in dark theme
export const Dark = {
parameters: {
theme: 'dark',
},
};
```

23
docs/snippets/react/configure-mock-provider-with-story-parameter.ts-4-9.mdx Normal file
View File

@ -0,0 +1,23 @@
```ts
// Button.stories.ts
import { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';
const meta = {
component: Button,
} satisfies Meta<typeof Button>;
export default meta;
type Story = StoryObj<typeof meta>;
// Wrapped in light theme
export const Default: Story = {};
// Wrapped in dark theme
export const Dark: Story = {
parameters: {
theme: 'dark',
},
};
```

23
docs/snippets/react/configure-mock-provider-with-story-parameter.ts.mdx Normal file
View File

@ -0,0 +1,23 @@
```ts
// Button.stories.ts
import { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';
const meta: Meta<typeof Button> = {
component: Button,
};
export default meta;
type Story = StoryObj<typeof Button>;
// Wrapped in light theme
export const Default: Story = {};
// Wrapped in dark theme
export const Dark: Story = {
parameters: {
theme: 'dark',
},
};
```

28
docs/snippets/react/decorator-parameterized-in-preview.js.mdx Normal file
View File

@ -0,0 +1,28 @@
```ts
// .storybook/preview.tsx
import React from 'react';
export default {
decorators: [
// 👇 Defining the decorator in the preview file applies it to all stories
(Story, { parameters }) => {
// 👇 Make it configurable by reading from parameters
const { pageLayout } = parameters;
switch (pageLayout) {
case 'page':
return (
// Your page layout is probably a little more complex than this ;)
<div className="page-layout"><Story /></div>
);
case 'page-mobile':
return (
<div className="page-mobile-layout"><Story /></div>
);
case default:
// In the default case, don't apply a layout
return <Story />;
}
},
],
};
```

31
docs/snippets/react/decorator-parameterized-in-preview.ts.mdx Normal file
View File

@ -0,0 +1,31 @@
```ts
// .storybook/preview.tsx
import React from 'react';
import { Preview } from '@storybook/react';
const preview: Preview = {
decorators: [
// 👇 Defining the decorator in the preview file applies it to all stories
(Story, { parameters }) => {
// 👇 Make it configurable by reading from parameters
const { pageLayout } = parameters;
switch (pageLayout) {
case 'page':
return (
// Your page layout is probably a little more complex than this ;)
<div className="page-layout"><Story /></div>
);
case 'page-mobile':
return (
<div className="page-mobile-layout"><Story /></div>
);
case default:
// In the default case, don't apply a layout
return <Story />;
}
},
],
};
export default preview;
```

23
docs/snippets/react/mock-provider-in-preview.js.mdx Normal file
View File

@ -0,0 +1,23 @@
```jsx
// .storybook/preview.jsx
import React from 'react';
import { ThemeProvider } from 'styled-components';
// themes = { light, dark }
import * as themes from '../src/themes';
export default {
decorators: [
// 👇 Defining the decorator in the preview file applies it to all stories
(Story, { parameters }) => {
// 👇 Make it configurable by reading the theme value from parameters
const { theme = 'light' } = parameters;
return (
<ThemeProvider theme={themes[theme]}>
<Story />
</ThemeProvider>
);
},
],
};
```

26
docs/snippets/react/mock-provider-in-preview.ts.mdx Normal file
View File

@ -0,0 +1,26 @@
```tsx
// .storybook/preview.tsx
import React from 'react';
import { Preview } from '@storybook/react';
import { ThemeProvider } from 'styled-components';
// themes = { light, dark }
import * as themes from '../src/themes';
const preview: Preview = {
decorators: [
// 👇 Defining the decorator in the preview file applies it to all stories
(Story, { parameters }) => {
// 👇 Make it configurable by reading the theme value from parameters
const { theme = 'light' } = parameters;
return (
<ThemeProvider theme={themes[theme]}>
<Story />
</ThemeProvider>
);
},
],
};
export default preview;
```

22
docs/snippets/react/nextjs-cache-mock.js.mdx Normal file
View File

@ -0,0 +1,22 @@
```js
// MyForm.stories.js
import { expect, userEvent, within } from '@storybook/test';
import { revalidatePath } from '@storybook/nextjs/cache.mock';
import MyForm from './my-form';
export default {
component: MyForm,
};
export const Submitted = {
async play({ canvasElement }) {
const canvas = within(canvasElement);
const submitButton = canvas.getByRole('button', { name: /submit/i });
await userEvent.click(saveButton);
// 👇 Use any mock assertions on the function
await expect(revalidatePath).toHaveBeenCalledWith('/');
},
};
```

28
docs/snippets/react/nextjs-cache-mock.ts-4-9.mdx Normal file
View File

@ -0,0 +1,28 @@
```ts
// MyForm.stories.ts
import { expect, userEvent, within } from '@storybook/test';
import { Meta, StoryObj } from '@storybook/react';
// 👇 Must use this import path to have mocks typed correctly
import { revalidatePath } from '@storybook/nextjs/cache.mock';
import MyForm from './my-form';
const meta = {
component: MyForm,
} satisfies Meta<typeof MyForm>;
export default meta;
type Story = StoryObj<typeof meta>;
export const Submitted: Story = {
async play({ canvasElement }) {
const canvas = within(canvasElement);
const submitButton = canvas.getByRole('button', { name: /submit/i });
await userEvent.click(saveButton);
// 👇 Use any mock assertions on the function
await expect(revalidatePath).toHaveBeenCalledWith('/');
},
};
```

28
docs/snippets/react/nextjs-cache-mock.ts.mdx Normal file
View File

@ -0,0 +1,28 @@
```ts
// MyForm.stories.ts
import { expect, userEvent, within } from '@storybook/test';
import { Meta, StoryObj } from '@storybook/react';
// 👇 Must use this import path to have mocks typed correctly
import { revalidatePath } from '@storybook/nextjs/cache.mock';
import MyForm from './my-form';
const meta: Meta<typeof MyForm> = {
component: MyForm,
};
export default meta;
type Story = StoryObj<typeof MyForm>;
export const Submitted: Story = {
async play({ canvasElement }) {
const canvas = within(canvasElement);
const submitButton = canvas.getByRole('button', { name: /submit/i });
await userEvent.click(saveButton);
// 👇 Use any mock assertions on the function
await expect(revalidatePath).toHaveBeenCalledWith('/');
},
};
```

26
docs/snippets/react/nextjs-headers-mock.js.mdx Normal file
View File

@ -0,0 +1,26 @@
```js
// MyForm.stories.js
import { expect, userEvent, within } from '@storybook/test';
import { cookies, headers } from '@storybook/nextjs/headers.mock';
import MyForm from './my-form';
export default {
component: MyForm,
};
export const LoggedInEurope = {
async beforeEach() {
// 👇 Set mock cookies and headers ahead of rendering
cookies().set('username', 'Sol');
headers().set('timezone', 'Central European Summer Time');
},
async play() {
// 👇 Assert that your component called the mocks
await expect(cookies().get).toHaveBeenCalledOnce();
await expect(cookies().get).toHaveBeenCalledWith('username');
await expect(headers().get).toHaveBeenCalledOnce();
await expect(cookies().get).toHaveBeenCalledWith('timezone');
},
};
```

32
docs/snippets/react/nextjs-headers-mock.ts-4-9.mdx Normal file
View File

@ -0,0 +1,32 @@
```ts
// MyForm.stories.ts
import { expect, fireEvent, userEvent, within } from '@storybook/test';
import { Meta, StoryObj } from '@storybook/react';
// 👇 Must use this import path to have mocks typed correctly
import { cookies, headers } from '@storybook/nextjs/headers.mock';
import MyForm from './my-form';
const meta = {
component: MyForm,
} satisfies Meta<typeof MyForm>;
export default meta;
type Story = StoryObj<typeof meta>;
export const LoggedInEurope: Story = {
async beforeEach() {
// 👇 Set mock cookies and headers ahead of rendering
cookies().set('username', 'Sol');
headers().set('timezone', 'Central European Summer Time');
},
async play() {
// 👇 Assert that your component called the mocks
await expect(cookies().get).toHaveBeenCalledOnce();
await expect(cookies().get).toHaveBeenCalledWith('username');
await expect(headers().get).toHaveBeenCalledOnce();
await expect(cookies().get).toHaveBeenCalledWith('timezone');
},
};
```

32
docs/snippets/react/nextjs-headers-mock.ts.mdx Normal file
View File

@ -0,0 +1,32 @@
```ts
// MyForm.stories.ts
import { expect, fireEvent, userEvent, within } from '@storybook/test';
import { Meta, StoryObj } from '@storybook/react';
// 👇 Must use this import path to have mocks typed correctly
import { cookies, headers } from '@storybook/nextjs/headers.mock';
import MyForm from './my-form';
const meta: Meta<typeof MyForm> = {
component: MyForm,
};
export default meta;
type Story = StoryObj<typeof MyForm>;
export const LoggedInEurope: Story = {
async beforeEach() {
// 👇 Set mock cookies and headers ahead of rendering
cookies().set('username', 'Sol');
headers().set('timezone', 'Central European Summer Time');
},
async play() {
// 👇 Assert that your component called the mocks
await expect(cookies().get).toHaveBeenCalledOnce();
await expect(cookies().get).toHaveBeenCalledWith('username');
await expect(headers().get).toHaveBeenCalledOnce();
await expect(cookies().get).toHaveBeenCalledWith('timezone');
},
};
```

35
docs/snippets/react/nextjs-navigation-mock.js.mdx Normal file
View File

@ -0,0 +1,35 @@
```js
// MyForm.stories.js
import { expect, fireEvent, userEvent, within } from '@storybook/test';
import { redirect, getRouter } from '@storybook/nextjs/navigation.mock';
import MyForm from './my-form';
export default {
component: MyForm,
parameters: {
nextjs: {
// 👇 As in the Next.js application, next/navigation only works using App Router
appDirectory: true,
},
},
};
export const Unauthenticated = {
async play() => {
// 👇 Assert that your component called redirect()
await expect(redirect).toHaveBeenCalledWith('/login', 'replace');
},
};
export const GoBack = {
async play({ canvasElement }) {
const canvas = within(canvasElement);
const backBtn = await canvas.findByText('Go back');
await userEvent.click(backBtn);
// 👇 Assert that your component called back()
await expect(getRouter().back).toHaveBeenCalled();
},
};
```

41
docs/snippets/react/nextjs-navigation-mock.ts-4-9.mdx Normal file
View File

@ -0,0 +1,41 @@
```ts
// MyForm.stories.ts
import { expect, fireEvent, userEvent, within } from '@storybook/test';
import { Meta, StoryObj } from '@storybook/react';
// 👇 Must use this import path to have mocks typed correctly
import { redirect, getRouter } from '@storybook/nextjs/navigation.mock';
import MyForm from './my-form';
const meta = {
component: MyForm,
parameters: {
nextjs: {
// 👇 As in the Next.js application, next/navigation only works using App Router
appDirectory: true,
},
},
} satisfies Meta<typeof MyForm>;
export default meta;
type Story = StoryObj<typeof meta>;
export const Unauthenticated: Story = {
async play() => {
// 👇 Assert that your component called redirect()
await expect(redirect).toHaveBeenCalledWith('/login', 'replace');
},
};
export const GoBack: Story = {
async play({ canvasElement }) {
const canvas = within(canvasElement);
const backBtn = await canvas.findByText('Go back');
await userEvent.click(backBtn);
// 👇 Assert that your component called back()
await expect(getRouter().back).toHaveBeenCalled();
},
};
```

41
docs/snippets/react/nextjs-navigation-mock.ts.mdx Normal file
View File

@ -0,0 +1,41 @@
```ts
// MyForm.stories.ts
import { expect, fireEvent, userEvent, within } from '@storybook/test';
import { Meta, StoryObj } from '@storybook/react';
// 👇 Must use this import path to have mocks typed correctly
import { redirect, getRouter } from '@storybook/nextjs/navigation.mock';
import MyForm from './my-form';
const meta: Meta<typeof MyForm> = {
component: MyForm,
parameters: {
nextjs: {
// 👇 As in the Next.js application, next/navigation only works using App Router
appDirectory: true,
},
},
};
export default meta;
type Story = StoryObj<typeof MyForm>;
export const Unauthenticated: Story = {
async play() => {
// 👇 Assert that your component called redirect()
await expect(redirect).toHaveBeenCalledWith('/login', 'replace');
},
};
export const GoBack: Story = {
async play({ canvasElement }) {
const canvas = within(canvasElement);
const backBtn = await canvas.findByText('Go back');
await userEvent.click(backBtn);
// 👇 Assert that your component called back()
await expect(getRouter().back).toHaveBeenCalled();
},
};
```

23
docs/snippets/react/nextjs-router-mock.js.mdx Normal file
View File

@ -0,0 +1,23 @@
```ts
// MyForm.stories.ts
import { expect, fireEvent, userEvent, within } from '@storybook/test';
// 👇 Must use this import path to have mocks typed correctly
import { getRouter } from '@storybook/nextjs/router.mock';
import MyForm from './my-form';
export default {
component: MyForm,
};
export const GoBack = {
async play({ canvasElement }) {
const canvas = within(canvasElement);
const backBtn = await canvas.findByText('Go back');
await userEvent.click(backBtn);
// 👇 Assert that your component called back()
await expect(getRouter().back).toHaveBeenCalled();
},
};
```

28
docs/snippets/react/nextjs-router-mock.ts-4-9.mdx Normal file
View File

@ -0,0 +1,28 @@
```ts
// MyForm.stories.ts
import { expect, fireEvent, userEvent, within } from '@storybook/test';
import { Meta, StoryObj } from '@storybook/react';
// 👇 Must use this import path to have mocks typed correctly
import { getRouter } from '@storybook/nextjs/router.mock';
import MyForm from './my-form';
const meta = {
component: MyForm,
} satisfies Meta<typeof MyForm>;
export default meta;
type Story = StoryObj<typeof meta>;
export const GoBack: Story = {
async play({ canvasElement }) {
const canvas = within(canvasElement);
const backBtn = await canvas.findByText('Go back');
await userEvent.click(backBtn);
// 👇 Assert that your component called back()
await expect(getRouter().back).toHaveBeenCalled();
},
};
```

28
docs/snippets/react/nextjs-router-mock.ts.mdx Normal file
View File

@ -0,0 +1,28 @@
```ts
// MyForm.stories.ts
import { expect, fireEvent, userEvent, within } from '@storybook/test';
import { Meta, StoryObj } from '@storybook/react';
// 👇 Must use this import path to have mocks typed correctly
import { getRouter } from '@storybook/nextjs/router.mock';
import MyForm from './my-form';
const meta: Meta<typeof MyForm> = {
component: MyForm,
};
export default meta;
type Story = StoryObj<typeof MyForm>;
export const GoBack: Story = {
async play({ canvasElement }) {
const canvas = within(canvasElement);
const backBtn = await canvas.findByText('Go back');
await userEvent.click(backBtn);
// 👇 Assert that your component called back()
await expect(getRouter().back).toHaveBeenCalled();
},
};
```

25
docs/snippets/web-components/before-each-in-meta-mock-date.js.mdx Normal file
View File

@ -0,0 +1,25 @@
```ts
// Page.stories.ts
import MockDate from 'mockdate';
import { getUserFromSession } from '#api/session.mock';
export default {
component: 'my-page',
// 👇 Set the value of Date for every story in the file
async beforeEach() {
MockDate.set('2024-02-14');
// 👇 Reset the Date after each story
return () => {
MockDate.reset();
};
},
};
export const Default = {
async play({ canvasElement }) {
// ... This will run with the mocked Date
},
};
```

30
docs/snippets/web-components/before-each-in-meta-mock-date.ts.mdx Normal file
View File

@ -0,0 +1,30 @@
```ts
// Page.stories.ts
import { Meta, StoryObj } from '@storybook/web-components';
import MockDate from 'mockdate';
// 👇 Must use this import path to have mocks typed correctly
import { getUserFromSession } from '#api/session.mock';
const meta: Meta = {
component: 'my-page',
// 👇 Set the value of Date for every story in the file
async beforeEach() {
MockDate.set('2024-02-14');
// 👇 Reset the Date after each story
return () => {
MockDate.reset();
};
},
};
export default meta;
type Story = StoryObj;
export const Default: Story = {
async play({ canvasElement }) {
// ... This will run with the mocked Date
},
};
```

30
docs/snippets/web-components/storybook-test-fn-mock-spy.js.mdx Normal file
View File

@ -0,0 +1,30 @@
```ts
// NoteUI.stories.ts
import { expect, userEvent, within } from '@storybook/test';
import { saveNote } from '#app/actions.mock';
import { createNotes } from '#mocks/notes';
export default {
title: 'Mocked/NoteUI',
component: 'note-ui',
};
const notes = createNotes();
export const SaveFlow = {
name: 'Save Flow ▶',
args: {
isEditing: true,
note: notes[0],
},
play: async ({ canvasElement, step }) => {
const canvas = within(canvasElement);
const saveButton = canvas.getByRole('menuitem', { name: /done/i });
await userEvent.click(saveButton);
// 👇 This is the mock function, so you can assert its behavior
await expect(saveNote).toHaveBeenCalled();
},
};
```

35
docs/snippets/web-components/storybook-test-fn-mock-spy.ts.mdx Normal file
View File

@ -0,0 +1,35 @@
```ts
// NoteUI.stories.ts
import { Meta, StoryObj } from '@storybook/react';
import { expect, userEvent, within } from '@storybook/test';
// 👇 Must use this import path to have mocks typed correctly
import { saveNote } from '#app/actions.mock';
import { createNotes } from '#mocks/notes';
const meta: Meta = {
title: 'Mocked/NoteUI',
component: 'note-ui',
};
export default meta;
type Story = StoryObj;
const notes = createNotes();
export const SaveFlow: Story = {
name: 'Save Flow ▶',
args: {
isEditing: true,
note: notes[0],
},
play: async ({ canvasElement, step }) => {
const canvas = within(canvasElement);
const saveButton = canvas.getByRole('menuitem', { name: /done/i });
await userEvent.click(saveButton);
// 👇 This is the mock function, so you can assert its behavior
await expect(saveNote).toHaveBeenCalled();
},
};
```

15
docs/snippets/web-components/storybook-test-mock-return-value.js.mdx Normal file
View File

@ -0,0 +1,15 @@
```ts
// Page.stories.ts
import { getUserFromSession } from '#api/session.mock';
export default {
component: 'my-page',
};
export const Default = {
async beforeEach() {
// 👇 Set the return value for the getUserFromSession function
getUserFromSession.mockReturnValue({ id: '1', name: 'Alice' });
},
};
```

21
docs/snippets/web-components/storybook-test-mock-return-value.ts.mdx Normal file
View File

@ -0,0 +1,21 @@
```ts
// Page.stories.ts
import type { Meta, StoryObj } from '@storybook/web-components';
// 👇 Must use this import path to have mocks typed correctly
import { getUserFromSession } from '#api/session.mock';
const meta: Meta = {
component: 'my-page',
};
export default meta;
type Story = StoryObj;
export const Default: Story = {
async beforeEach() {
// 👇 Set the return value for the getUserFromSession function
getUserFromSession.mockReturnValue({ id: '1', name: 'Alice' });
},
};
```

37
docs/writing-stories/decorators.md
View File

@ -49,36 +49,19 @@ The second argument to a decorator function is the **story context** which conta
- `parameters`- the story's static metadata, most commonly used to control Storybook's behavior of features and addons.
- `viewMode`- Storybook's current active window (e.g., canvas, docs).
This context can be used to adjust the behavior of your decorator based on the story's arguments or other metadata. For example, you could create a decorator that wraps the story in a layout, unless the `noLayout` parameter is set to `true`:
This context can be used to adjust the behavior of your decorator based on the story's arguments or other metadata. For example, you could create a decorator that allows you to optionally apply a layout to the story, by defining `parameters.pageLayout = 'page'` (or `'page-mobile'`):
:
<!-- TODO: Snippetize -->
<!-- prettier-ignore-start -->
```ts
// .storybook/preview.js
import React from 'react';
import { Preview } from '@storybook/react';
<CodeSnippets
paths={[
'react/decorator-parameterized-in-preview.js.mdx',
'react/decorator-parameterized-in-preview.ts.mdx',
]}
/>
import { Layout } from '../components/Layout';
const preview: Preview = {
decorators: [
// 👇 Defining the decorator in the preview file applies it to all stories
(Story, { parameters }) => {
// 👇 Make it configurable by reading from parameters
const { noLayout } = parameters;
return noLayout ? (
<Story />
) : (
<Layout>
<Story />
</Layout>
);
},
],
};
export default preview;
```
<!-- prettier-ignore-end -->
<Callout variant="info" icon="💡">

213
docs/writing-stories/mocking-modules.md
View File

@ -20,16 +20,15 @@ To mock a module, create a file with the same name and in the same directory as
Here's an example of a mock file for a module named `session`:
<!-- TODO: Snippetize -->
<!-- prettier-ignore-start -->
```ts
// lib/session.mock.ts
import { fn } from '@storybook/test';
import * as actual from './session';
<CodeSnippets
paths={[
'common/storybook-test-mock-file-example.ts.mdx',
]}
/>
export * from './session';
export const getUserFromSession = fn(actual.getUserFromSession);
```
<!-- prettier-ignore-end -->
### Mock files for external modules
@ -59,32 +58,15 @@ The recommended method for mocking modules is to use [subpath imports](https://n
To configure subpath imports, you define the `imports` property in your project's `package.json` file. This property maps the subpath to the actual file path. The example below configures subpath imports for four internal modules:
<!-- TODO: Snippetize -->
<!-- prettier-ignore-start -->
```json
// package.json
{
"imports": {
"#api": {
"storybook": "./api.mock.ts",
"default": "./api.ts"
},
"#app/actions": {
"storybook": "./app/actions.mock.ts",
"default": "./app/actions.ts"
},
"#lib/session": {
"storybook": "./lib/session.mock.ts",
"default": "./lib/session.ts"
},
"#lib/db": {
"storybook": "./lib/db.mock.ts",
"default": "./lib/db.ts"
},
"#*": ["./*", "./*.ts", "./*.tsx"]
}
}
```
<CodeSnippets
paths={[
'common/subpath-imports-config.json.mdx',
]}
/>
<!-- prettier-ignore-end -->
There are two aspects to this configuration worth noting:
@ -108,47 +90,18 @@ import { getUserFromSession } from '#lib/session';
If your project is unable to use [subpath imports](#subpath-imports), you can configure your Storybook builder to alias the module to the mock file. This will instruct the builder to replace the module with the mock file when bundling your Storybook stories.
<!-- TODO: Snippetize -->
<!-- prettier-ignore-start -->
```ts
// .storybook/main.ts
viteFinal: async (config) => {
if (config.resolve) {
config.resolve.alias = {
...config.resolve?.alias,
// 👇 External module
'lodash': require.resolve('./lodash.mock'),
// 👇 Internal modules
'@/api': path.resolve(__dirname, "./api.mock.ts"),
'@/app/actions': path.resolve(__dirname, "./app/actions.mock.ts"),
'@/lib/session': path.resolve(__dirname, "./lib/session.mock.ts"),
'@/lib/db': path.resolve(__dirname, "./lib/db.mock.ts"),
}
}
<CodeSnippets
paths={[
'common/module-aliases-config.vite.ts.mdx',
'common/module-aliases-config.vite.js.mdx',
'common/module-aliases-config.webpack.ts.mdx',
'common/module-aliases-config.webpack.js.mdx',
]}
/>
return config;
},
```
```ts
// .storybook/main.ts
webpackFinal: async (config) => {
if (config.resolve) {
config.resolve.alias = {
...config.resolve.alias,
// 👇 External module
'lodash': require.resolve('./lodash.mock'),
// 👇 Internal modules
'@/api$': path.resolve(__dirname, "./api.mock.ts"),
'@/app/actions$': path.resolve(__dirname, "./app/actions.mock.ts"),
'@/lib/session$': path.resolve(__dirname, "./lib/session.mock.ts"),
'@/lib/db$': path.resolve(__dirname, "./lib/db.mock.ts"),
}
}
return config;
},
```
<!-- prettier-ignore-end -->
## Using mocked modules in stories
@ -156,30 +109,19 @@ When you use the `fn` utility to mock a module, you create full [Vitest mock fun
Here, we define `beforeEach` on a story (which will run before the story is rendered) to set a mocked return value for the `getUserFromSession` function used by the Page component:
<!-- TODO: Snippetize -->
<!-- prettier-ignore-start -->
```ts
// Page.stories.ts|tsx
import { Meta, StoryObj } from '@storybook/react';
import { fn } from '@storybook/test';
<CodeSnippets
paths={[
'angular/storybook-test-mock-return-value.ts.mdx',
'web-components/storybook-test-mock-return-value.js.mdx',
'web-components/storybook-test-mock-return-value.ts.mdx',
'common/storybook-test-mock-return-value.js.mdx',
'common/storybook-test-mock-return-value.ts.mdx',
]}
/>
import { getUserFromSession } from '#api/session.mock';
import { Page } from './Page';
const meta: Meta<typeof Page> = {
component: Page,
};
export default meta;
type Story = StoryObj<typeof Page>;
export const Default: Story = {
async beforeEach() {
// 👇 Set the return value for the getUserFromSession function
getUserFromSession.mockReturnValue({ id: '1', name: 'Alice' });
},
};
```
<!-- prettier-ignore-end -->
<Callout variant="info">
@ -193,43 +135,19 @@ The `fn` utility also spies on the original module's functions, which you can us
For example, this story checks that the `saveNote` function was called when the user clicks the save button:
<!-- TODO: Snippetize -->
<!-- prettier-ignore-start -->
```ts
// NoteUI.stories.ts|tsx
import { Meta, StoryObj } from '@storybook/react';
import { expect, userEvent, within } from '@storybook/test';
<CodeSnippets
paths={[
'angular/storybook-test-fn-mock-spy.ts.mdx',
'web-components/storybook-test-fn-mock-spy.js.mdx',
'web-components/storybook-test-fn-mock-spy.ts.mdx',
'common/storybook-test-fn-mock-spy.js.mdx',
'common/storybook-test-fn-mock-spy.ts.mdx',
]}
/>
import { saveNote } from '#app/actions.mock';
import { createNotes } from '#mocks/notes';
import NoteUI from './note-ui';
const meta = {
title: 'Mocked/NoteUI',
component: NoteUI,
} satisfies Meta<typeof NoteUI>;
export default meta;
type Story = StoryObj<typeof meta>;
const notes = createNotes();
export const SaveFlow: Story = {
name: 'Save Flow ▶',
args: {
isEditing: true,
note: notes[0],
},
play: async ({ canvasElement, step }) => {
const canvas = within(canvasElement);
const saveButton = canvas.getByRole('menuitem', { name: /done/i });
await userEvent.click(saveButton);
// 👇 This is the mock function, so you can assert its behavior
await expect(saveNote).toHaveBeenCalled();
},
};
```
<!-- prettier-ignore-end -->
### Setting up and cleaning up
@ -245,31 +163,16 @@ It is _not_ necessary to restore `fn()` mocks with the cleanup function, as Stor
Here's an example of using the [`mockdate`](https://github.com/boblauer/MockDate) package to mock the [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) and reset it when the story unmounts.
<!-- TODO: Snippetize -->
<!-- prettier-ignore-start -->
```ts
// Page.stories.ts|tsx
import { Meta, StoryObj } from '@storybook/react';
import MockDate from 'mockdate';
<CodeSnippets
paths={[
'angular/before-each-in-meta-mock-date.ts.mdx',
'web-components/before-each-in-meta-mock-date.js.mdx',
'web-components/before-each-in-meta-mock-date.ts.mdx',
'common/before-each-in-meta-mock-date.js.mdx',
'common/before-each-in-meta-mock-date.ts.mdx',
]}
/>
import { getUserFromSession } from '#api/session.mock';
import { Page } from './Page';
const meta: Meta<typeof Page> = {
component: Page,
// 👇 Set the current date for every story in the file
async beforeEach() {
MockDate.set('2024-02-14');
// 👇 Reset the date after each test
return () => {
MockDate.reset();
};
},
};
export default meta;
type Story = StoryObj<typeof Page>;
export const Default: Story = {};
```
<!-- prettier-ignore-end -->

18
docs/writing-stories/mocking-network-requests.md
View File

@ -8,21 +8,21 @@ The [MSW addon](https://storybook.js.org/addons/msw-storybook-addon/) brings thi
## Set up the MSW addon
First, if necessary, run this command to install MSW:
First, if necessary, run this command to install MSW and the MSW addon:
<!-- prettier-ignore-start -->
<CodeSnippets
paths={[
'common/msw-install.npm.js.mdx',
'common/msw-install.yarn.js.mdx',
'common/msw-install.pnpm.js.mdx',
'common/msw-addon-install.npm.js.mdx',
'common/msw-addon-install.yarn.js.mdx',
'common/msw-addon-install.pnpm.js.mdx',
]}
/>
<!-- prettier-ignore-end -->
Then generate the service worker file necessary for MSW to work:
If you're not already using MSW, generate the service worker file necessary for MSW to work:
<!-- prettier-ignore-start -->
@ -45,14 +45,6 @@ Angular projects will likely need to adjust the command to save the mock service
</If>
Next, install and register the MSW addon:
<!-- TODO: Snippetize -->
```sh
npx storybook@latest add msw-storybook-addon
```
Then ensure the [`staticDirs`](../api/main-config-static-dirs.md) property in your Storybook configuration will include the generated service worker file (in `/public`, by default):
<!-- prettier-ignore-start -->

72
docs/writing-stories/mocking-providers.md
View File

@ -33,10 +33,20 @@ Components can receive data or configuration from context providers. For example
<!-- prettier-ignore-end -->
<Callout variant="warning">
Note the file extension above (`.tsx` or `.jsx`). You may need to adjust your preview file's extension to allow use of JSX, depending on your project's settings.
</Callout>
<If renderer="react">
<Callout variant="info" icon="💡">
For another example, reference the [Screens](https://storybook.js.org/tutorials/intro-to-storybook/react/en/screen/) chapter of the Intro to Storybook tutorial, where we mock a Redux provider with mock data.
</Callout>
</If>
## Configuring the mock provider
@ -49,59 +59,29 @@ For a better way, with much less repetition, you can use the [decorator function
For example, we can adjust the decorator from above to read from `parameters.theme` to determine which theme to provide:
<!-- TODO: Snippetize -->
<!-- prettier-ignore-start -->
```ts
// .storybook/preview.ts
import React from 'react';
import { Preview } from '@storybook/react';
import { ThemeProvider } from 'styled-components';
<CodeSnippets
paths={[
'react/mock-provider-in-preview.js.mdx',
'react/mock-provider-in-preview.ts.mdx',
]}
/>
const preview: Preview = {
decorators: [
// 👇 Defining the decorator in the preview file applies it to all stories
(Story, { parameters }) => {
// 👇 Make it configurable by reading the theme value from parameters
const theme = parameters.theme || 'default';
return (
<ThemeProvider theme={theme}>
<Story />
</ThemeProvider>
);
},
],
};
export default preview;
```
<!-- prettier-ignore-end -->
Now, you can define a `theme` parameter in your stories to adjust the theme provided by the decorator:
<!-- TODO: Snippetize -->
<!-- prettier-ignore-start -->
```ts
// Button.stories.ts|tsx
import { Meta, StoryObj } from '@storybook/react';
<CodeSnippets
paths={[
'react/configure-mock-provider-with-story-parameter.js.mdx',
'react/configure-mock-provider-with-story-parameter.ts.mdx',
]}
/>
import { Button } from './Button';
const meta: Meta<typeof Button> = {
component: Button,
};
export default meta;
type Story = StoryObj<typeof Button>;
// Wrapped in default theme
export const Default: Story = {};
// Wrapped in dark theme
export const Dark: Story = {
parameters: {
theme: 'dark',
},
};
```
<!-- prettier-ignore-end -->
This powerful approach allows you to provide any value (theme, user role, mock data, etc.) to your components in a way that is both flexible and maintainable.

87
docs/writing-tests/interaction-testing.md
View File

@ -104,38 +104,19 @@ It is _not_ necessary to restore `fn()` mocks with the cleanup function, as Stor
Here's an example of using the [`mockdate`](https://github.com/boblauer/MockDate) package to mock the Date and reset it when the story unmounts.
<!-- TODO: Snippetize -->
<!-- prettier-ignore-start -->
```ts
// Page.stories.ts|tsx
import { Meta, StoryObj } from '@storybook/react';
import MockDate from 'mockdate';
<CodeSnippets
paths={[
'angular/before-each-in-meta-mock-date.ts.mdx',
'web-components/before-each-in-meta-mock-date.js.mdx',
'web-components/before-each-in-meta-mock-date.ts.mdx',
'common/before-each-in-meta-mock-date.js.mdx',
'common/before-each-in-meta-mock-date.ts.mdx',
]}
/>
import { getUserFromSession } from '#api/session.mock';
import { Page } from './Page';
const meta: Meta<typeof Page> = {
component: Page,
// 👇 Set the current date for every story in the file
async beforeEach() {
MockDate.set('2024-02-14');
// 👇 Reset the date after each test
return () => {
MockDate.reset();
};
},
};
export default meta;
type Story = StoryObj<typeof Page>;
export const Default: Story = {
async play({ canvasElement }) {
// ... This will run with the mocked date
},
};
```
<!-- prettier-ignore-end -->
### API for user-events
@ -205,43 +186,19 @@ If your component depends on modules that are imported into the component file,
You can then import the mocked module (which has all of the helpful methods of a [Vitest mocked function](https://vitest.dev/api/mock.html)) into your story and use it to assert on the behavior of your component:
<!-- TODO: Snippetize -->
<!-- prettier-ignore-start -->
```ts
// NoteUI.stories.ts|tsx
import { Meta, StoryObj } from '@storybook/react';
import { expect, userEvent, within } from '@storybook/test';
<CodeSnippets
paths={[
'angular/storybook-test-fn-mock-spy.ts.mdx',
'web-components/storybook-test-fn-mock-spy.js.mdx',
'web-components/storybook-test-fn-mock-spy.ts.mdx',
'common/storybook-test-fn-mock-spy.js.mdx',
'common/storybook-test-fn-mock-spy.ts.mdx',
]}
/>
import { saveNote } from '#app/actions.mock';
import { createNotes } from '#mocks/notes';
import NoteUI from './note-ui';
const meta = {
title: 'Mocked/NoteUI',
component: NoteUI,
} satisfies Meta<typeof NoteUI>;
export default meta;
type Story = StoryObj<typeof meta>;
const notes = createNotes();
export const SaveFlow: Story = {
name: 'Save Flow ▶',
args: {
isEditing: true,
note: notes[0],
},
play: async ({ canvasElement, step }) => {
const canvas = within(canvasElement);
const saveButton = canvas.getByRole('menuitem', { name: /done/i });
await userEvent.click(saveButton);
// 👇 This is the mock function, so you can assert its behavior
await expect(saveNote).toHaveBeenCalled();
},
};
```
<!-- prettier-ignore-end -->
### Interactive debugger