re:re:actable
Урок 035 минут чтения

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 + playVitest + 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".

Документация

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам