Storybook для React: как создавать и тестировать UI‑компоненты изолированно

React позволяет строить переиспользуемые UI‑компоненты, но сам по себе React не даёт удобной среды для изолированного просмотра и тестирования этих компонентов. Чтобы посмотреть компонент в вакууме — вне приложения — и задокументировать его состояния, удобно использовать Storybook. В этой статье пошагово показано, как добавить Storybook в проект Create React App, создать компонент Button и описать его варианты отображения.

Что такое Storybook?

Storybook — это инструмент разработки интерфейсов, который запускает отдельный рантайм для ваших компонентов. Он позволяет:

• Разрабатывать компоненты в изоляции от полного приложения.
• Писать «stories» — примеры и состояния компонента.
• Автоматически генерировать документацию и контролы для подтюнинга пропсов (args).

Коротко: Storybook ускоряет компонентно‑ориентированную разработку и делает визуальное тестирование проще.

Важно: для работы Storybook нужен Node.js и базовые знания React.

Создание React‑приложения

Для начала создайте новый проект на базе Create React App:

npx create-react-app btn-storybook  

Эта команда создаст папку btn‑storybook со всеми необходимыми зависимостями и начальной структурой.

Установка Storybook

Перейдите в папку проекта и инициализируйте Storybook:

cd btn-storybook  
npx storybook init  

Так как вы используете Create React App, storybook init выполнит все настройки автоматически: установит зависимости и создаст примерные истории.

Запустите Storybook:

npm run storybook  

Откроется панель Storybook в браузере. Интерфейс содержит боковую панель со списком компонентов и область превью для выбранной истории.

Создание компонента Button

В папке ./src создайте путь ./src/Components/Button и файл Button.js с таким кодом:

import PropTypes from "prop-types"  
  
function Button({ label, backgroundColor = "#6B4EFF", color = "white", borderRadius="48px", border="none"}) {  
  const style = {  
    backgroundColor,  
    padding: "0.5rem 1rem",  
    color,  
    borderRadius,  
    border  
  }  
  return (  
      
      {label}  
      
  )  
}  
Button.propTypes = {  
  label: PropTypes.string,  
  backgroundColor: PropTypes.string,  
  color: PropTypes.string,  
  border:PropTypes.string,  
  borderRadius: PropTypes.string,  
}  
export default Button;  

Объяснение в одну строку: компонент принимает пропсы для метки и стилей и возвращает элемент button.

Создание историй для Button

Storybook использует файлы с расширением .stories.js, чтобы понять, какие примеры (stories) показать. В папке stories (удалите стандартные примеры) создайте файл button.stories.js.

Импортируйте компонент:

import Button from "../Components/Button/Button"  

Экспортируйте метаданные и компонент:

export default {  
    title: "Components/Button",  
    component: Button,  
}  

Первая история — Primary (первичный вариант):

export const Primary = () =>   

После этого вы увидите кнопку в интерфейсе Storybook. Но удобнее использовать шаблон с args — они позволяют менять пропсы через контролы в UI и мгновенно видеть результат.

Создайте шаблон и используйте bind:

const Template = args =>   

export const Primary = Template.bind({})  
  
Primary.args = {  
    backgroundColor: "#6B4EFF",  
    label: "Primary",  
}  

Аналогично создайте Secondary:

export const Secondary = Template.bind({})  
  
Secondary.args = {  
    backgroundColor: "#E7E7FF",  
    color: "#6B4EFF",  
    label: "Secondary",  
}  

Теперь внизу панели превью появятся контролы. Вы сможете менять backgroundColor, color, label, border и borderRadius в реальном времени.

Советы по оформлению историй

• Используйте Template.bind({}) для переиспользования шаблона.
• Группируйте истории в каталоги через title: “Components/Button”.
• Добавляйте описание и argTypes для управляющих контролов (см. документацию Storybook).

Примечание: истории служат не только как примеры, но и как живая документация для команды дизайнеров и QA.

Тестирование UI‑компонентов

Storybook облегчает визуальное тестирование: вы проверяете внешний вид и поведение компонента в разных состояниях. Это снижает число неожиданных багов при интеграции в приложение.

Преимущества:

• Быстрое воспроизведение багов в изоляции.
• Удобство ревью для дизайнеров и продуктовой команды.
• Поддержка автоматических визуальных тестов (например, с Chromatic или Percy).

Когда Storybook не подходит

• Проекты с очень простым UI, где компоненты появляются редко. Storybook добавляет накладные расходы.
• Если команда не готова поддерживать истории в актуальном состоянии — документация устаревает и вводит в заблуждение.
• В системах, где компоненты сильно завязаны на контексте приложения (глобальное состояние, сложные провайдеры) — требуется дополнительная настройка окружения историй.

Альтернативные подходы

• Локальные полигоны и playground внутри приложения. Проще, но менее изолированно.
• Инструменты визуального тестирования без отдельного рантайма — например, snapshot‑тесты (Jest) + @testing-library/react.
• Комбинированный подход: Storybook для визуалки + unit/интеграционные тесты для логики.

Методология разработки компонентов (мини‑метод)

1. Опишите цель компонента и основные состояния.
2. Реализуйте базовую версию с минимальным набором пропсов.
3. Добавьте истории: базовая, альтернативная, отключённая, с ошибкой.
4. Подключите PropTypes/TypeScript для типов.
5. Напишите тесты (unit + визуальные, если нужно).
6. Интегрируйте в библиотеку компонентов и задокументируйте.

Чеклист ролей

Для разработчика:

• Создан компонент и экспортирован.
• Написаны .stories.js: минимум 2 истории.
• Добавлены PropTypes или типы.

Для дизайнера:

• Проверены все ключевые состояния в Storybook.
• Оценена доступность: контраст текста, фокус.

Для QA:

• Покрыты сценарии ручного тестирования.
• Выполнены визуальные регрессионные тесты (при наличии).

Критерии приёмки

• Компонент отображается в Storybook без ошибок.
• Существуют истории для всех ключевых состояний.
• Контролы args корректно меняют визуал.
• Типы пропсов настроены и проверяются.

Глоссарий (1‑строчные определения)

• Story: пример состояния компонента.
• Args: аргументы/пропсы, передаваемые в story.
• Template: функция‑шаблон для создания историй.
• Controls: UI в Storybook для интерактивного изменения args.

Примеры ошибок и как их избежать

• Истории устарели после рефакторинга — регулярно пересматривайте stories при изменениях API компонента.
• Сложные зависимости в компоненте — мокируйте провайдеры и контексты для историй.
• Нехватка покрытий — комбинируйте Storybook с unit‑тестами.

Шаблон checklist для новой истории

• Название: отражает состояние (Primary, Disabled, Loading).
• Args: заданы дефолтные значения.
• Документация: краткое описание, пример использования.

Заключение

Storybook — инструмент, который ускоряет разработку компонентов и улучшает коммуникацию между разработкой, дизайном и QA. Он особенно полезен в больших проектах с множеством переиспользуемых компонентов. Следуя простому рабочему процессу (создать компонент → написать истории → тестировать), вы уменьшите количество багов при интеграции и упростите поддержку библиотеки компонентов.

Краткий план внедрения в команду:

1. Настроить Storybook в одном репозитории.
2. Согласовать формат stories и стиль документации.
3. Добавить в CI базовые визуальные проверки.

Спасибо за внимание — попробуйте создать ещё одну историю (например, Outline или Loading) и посмотрите, насколько быстрее пойдёт работа с компонентами.