Storybook как инструмент тестирования компонентов
На этой странице
Storybook — не только витрина компонентов, но и полноценная среда их тестирования. Каждая история (story) описывает компонент в конкретном состоянии (Primary, Disabled, Loading, WithLongText, Error), и эти же истории переиспользуются как тесты: рендер-тест (история отрисовалась без ошибок), interaction-тест через play-функцию (кликнуть, ввести текст, проверить результат прямо в истории с помощью storybook/test — тех же Testing Library и expect), тест доступности (axe через addon-a11y), визуальный тест (Chromatic или аналоги снимают каждую историю). Начиная с Storybook 9 истории запускаются как тесты через Vitest (аддон @storybook/addon-vitest) в Browser Mode — в настоящем браузере, в CI и в интерфейсе Storybook. Плюсы подхода: одна история = документация + ручная проверка дизайнером + автотест; состояния, которые трудно воспроизвести в приложении (ошибка сервера, пустой список), описаны явно. Сеть мокают через MSW (msw-storybook-addon), модули — через sb.mock/моки в конфиге.
Вопрос
Как использовать Storybook для тестирования компонентов? Что такое play-функции и как запускать истории как тесты?
История с состояниями
// src/shared/ui/button/button.stories.tsx
import type { Meta, StoryObj } from "@storybook/react-vite";
import { Button } from "./button";
const meta = {
component: Button,
args: { children: "Сохранить" },
parameters: { a11y: { test: "error" } }, // нарушения axe — ошибка теста
} satisfies Meta<typeof Button>;
export default meta;
type Story = StoryObj<typeof meta>;
export const Primary: Story = {};
export const Danger: Story = { args: { variant: "danger", children: "Удалить" } };
export const Loading: Story = { args: { isLoading: true } };
export const Disabled: Story = { args: { disabled: true } };
export const LongText: Story = { args: { children: "Очень длинный текст кнопки, который не должен ломать вёрстку" } };Interaction-тест: play-функция
// src/features/login/login-form.stories.tsx
import { expect, fn, waitFor } from "storybook/test"; // canvas и userEvent приходят в контекст play
import { http, HttpResponse } from "msw";
import { LoginForm } from "./login-form";
const meta = { component: LoginForm, args: { onSuccess: fn() } } satisfies Meta<typeof LoginForm>;
export default meta;
type Story = StoryObj<typeof meta>;
export const ValidationErrors: Story = {
play: async ({ canvas, userEvent }) => {
await userEvent.click(canvas.getByRole("button", { name: "Войти" }));
await expect(canvas.getByLabelText("Email")).toHaveAccessibleDescription("Введите email");
},
};
export const WrongPassword: Story = {
parameters: {
msw: { handlers: [http.post("/api/login", () => HttpResponse.json({ code: "INVALID" }, { status: 401 }))] },
},
play: async ({ canvas, userEvent, args }) => {
await userEvent.type(canvas.getByLabelText("Email"), "anna@example.com");
await userEvent.type(canvas.getByLabelText("Пароль"), "wrong");
await userEvent.click(canvas.getByRole("button", { name: "Войти" }));
await expect(await canvas.findByRole("alert")).toHaveTextContent("Неверный email или пароль");
await expect(args.onSuccess).not.toHaveBeenCalled();
},
};
export const Success: Story = {
play: async ({ canvas, userEvent, args }) => {
await userEvent.type(canvas.getByLabelText("Email"), "anna@example.com");
await userEvent.type(canvas.getByLabelText("Пароль"), "correct-password");
await userEvent.click(canvas.getByRole("button", { name: "Войти" }));
await waitFor(() => expect(args.onSuccess).toHaveBeenCalled());
},
};В интерфейсе Storybook вкладка Interactions показывает каждый шаг play-функции — можно пройти по шагам и увидеть, где упало.
Запуск историй как тестов (Vitest)
pnpm dlx storybook add @storybook/addon-vitest # настраивает vitest-проект для историй// vitest.config.ts (фрагмент, созданный аддоном)
import { storybookTest } from "@storybook/addon-vitest/vitest-plugin";
import { playwright } from "@vitest/browser-playwright";
projects: [
{
extends: true,
plugins: [storybookTest({ configDir: ".storybook" })],
test: {
name: "storybook",
browser: { enabled: true, headless: true, provider: playwright(), instances: [{ browser: "chromium" }] },
},
},
],pnpm vitest --project storybook # каждая история = тест (рендер + play + a11y)В CI это обычный Vitest-прогон; в Storybook появляется виджет тестов с результатами, покрытием и a11y по каждой истории.
Провайдеры и моки
// .storybook/preview.tsx — глобальные декораторы
import { initialize, mswLoader } from "msw-storybook-addon";
initialize({ onUnhandledRequest: "bypass" });
const preview: Preview = {
loaders: [mswLoader],
decorators: [
(Story) => (
<QueryClientProvider client={new QueryClient({ defaultOptions: { queries: { retry: false } } })}>
<ThemeProvider><Story /></ThemeProvider>
</QueryClientProvider>
),
],
parameters: { msw: { handlers } }, // общие хэндлеры, те же что в Vitest
};
export default preview;Storybook-тесты и обычные компонентные тесты
| Storybook + play | Vitest + RTL |
|---|---|
| История видна людям: дизайнер, QA, разработчики | Только код |
| Отлично для дизайн-системы и визуальных состояний | Отлично для логики экранов и многих сценариев |
| Шаги видны в UI, отладка в браузере | Быстрые прогоны, jsdom или браузер |
| Одна история — документация + визуальный тест + a11y | Тесты не являются документацией UI |
| Сложные сценарии с множеством веток громоздки | Удобны таблицы (it.each), фабрики, хелперы |
Частая практика: UI-кит и виджеты — Storybook (истории + play + a11y + визуальные), бизнес-логика экранов — Vitest + RTL, сценарии — Playwright.
Сопутствующие возможности
- Portable stories:
composeStoriesпозволяет использовать истории (с их args и декораторами) внутри RTL- или Playwright-тестов. - Покрытие кода по историям в виджете тестов.
- Chromatic: визуальные снимки всех историй + UI Review в PR.
- Docs: автодокументация props из TypeScript.
Что важно помнить
- История = компонент в конкретном состоянии; её переиспользуют как тест.
- play-функция — interaction-тест с
storybook/test(Testing Library + expect). - Storybook 9+: истории запускаются как тесты через Vitest в браузере.
- a11y и визуальные проверки на каждой истории.
- MSW и декораторы дают реалистичное окружение.
Мини-шпаргалка
export const Story: StoryObj = { args, parameters, play }.play: async ({ canvas, userEvent, args }) => { … await expect(...) }.fn()для колбэков,parameters.msw.handlersдля сети.@storybook/addon-vitest→vitest --project storybook.parameters.a11y.test: "error".