Как использовать Storybook для React: создание и тестирования кнопки

Storybook позволяет разрабатывать и тестировать UI-компоненты React в изоляции — без полного приложения. В этом руководстве вы создадите простой компонент Button, добавите истории (stories) для его состояний, включите управление аргументами (args) и получите практические чек-листы для интеграции и тестирования.

Что такое Storybook?

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

• разрабатывать компоненты вне контекста приложения;
• документировать визуальные состояния через «истории» (stories);
• интерактивно изменять пропсы через контролы (args) и смотреть результат в реальном времени.

Короткое определение: Storybook — это песочница для компонентов. Она ускоряет компонентно-ориентированную разработку и снижает вероятность регрессий.

Важно

Storybook не заменяет систему сборки и CI/CD. Это инструмент для локальной разработки, документирования и визуального тестирования.

Когда использовать Storybook

Используйте Storybook, если ваш проект:

• ориентирован на переиспользуемые UI-компоненты;
• требует стабильной визуальной документации для дизайнеров и разработчиков;
• нуждается в визуальных тестах и быстрых smoke-тестах интерфейсов.

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

• простому одностраничному сайту без повторно используемых компонентов;
• если вы тестируете сложную бизнес-логику, завязанную на жизненный цикл приложения.

Требования перед началом

• Node.js установлен на машине;
• базовые знания React (функциональные компоненты, пропсы);
• npm или yarn для установки пакетов.

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

Сначала создайте проект React. В терминале выполните:

        `npx create-react-app btn-storybook  
`
    

Это создаст папку btn-storybook с шаблоном React и всеми зависимостями.

Примечание

Если вы используете yarn, замените npx create-react-app на yarn create react-app.

Установка Storybook

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

        `cd btn-storybook  
npx storybook init  
`
    

Если вы использовали create-react-app, эта команда настроит Storybook автоматически, установит зависимости и добавит примерные истории.

Запустите Storybook:

        `npm run storybook  
`
    

После запуска в браузере откроется панель Storybook. Пример того, как она выглядит:

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

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

        `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;  
`
    

Коротко о компоненте

• Принимает пропсы: label, backgroundColor, color, borderRadius и border.
• Использует propTypes для проверки типов в разработке.
• Возвращает простую кнопку с встроенными стилями.

Советы по улучшению

• Для масштабируемости вынесите стили в CSS/Styled Components.
• Добавьте aria-атрибуты и tabindex для доступности.

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

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

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

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

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

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

Простейшая история для Primary:

        `export const Primary = () =>   
`
    

Но удобнее использовать шаблон и args, чтобы управлять значениями через UI Storybook.

Создайте шаблон:

        `const Template = args =>   
`
    

Используйте bind для создания экземпляров историй и задайте 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",  
}  
`
    

После этого в панели Storybook появятся контролы для изменения args и мгновенного ререндеринга компонента.

Контролы и интерактивность

Args позволяют:

• изменять пропсы в UI;
• сохранять наборы аргументов для демонстрации;
• интегрировать с addon-ами для тестирования и скриншотов.

Попробуйте добавить истории для disabled, outline и loading-состояний. Для outline можно изменить border и backgroundColor.

Доступность и тестирование

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

• Кнопка рендерится с переданным label.
• Контраст текста и фона соответствует базовым требованиям (например, заметность текста на заданном фоне).
• Кнопка доступна по клавиатуре и имеет aria-label, если label пустой.
• Изменение args в Storybook отражается на компоненте без перезагрузки.

Минимальные тесты (ручные)

• Нажатие через клавиатуру (Enter/Space) активирует кнопку.
• Проверьте визуальные состояния в разных браузерах.
• Протестируйте с экранными читалками.

Автоматические тесты

• Добавьте визуальные регрессионные тесты (Chromatic, Percy или Lighthouse snapshot).
• Напишите unit-тесты на рендеринг (Jest/React Testing Library): проверка label и inline-стилей.

Примеры тест-кейсов

• Рендер с дефолтными пропсами.
• Рендер с backgroundColor и color из args.
• Поведение при пустом label (должен быть aria-label).
• Snapshot для основных историй (Primary, Secondary, Disabled).

Руководство по интеграции и отладке

Пошаговый мини-процесс внедрения Storybook в команду

1. Установите Storybook в локальном репозитории.
2. Создайте базовую структуру stories для существующих компонентов.
3. Настройте линтер и стандарты по именованию историй.
4. Интегрируйте визуальные тесты в CI (опционально: Chromatic).
5. Обучите дизайнеров и разработчиков пользоваться контролами и args.

Частые проблемы и решения

• Storybook не запускается: проверьте версию Node и конфликтующие зависимости.
• Компонент зависит от контекста приложения: оберните его в провайдеры в истории.
• Плохие стили из глобального CSS: используйте изоляцию стилей или инкапсуляцию.

Чек-листы по ролям

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

• Компонент вынесен в отдельную папку и имеет файл истории.
• Есть шаблон Template и минимум две истории.
• Добавлены propTypes или TypeScript типы.
• Написаны unit-тесты и snapshot, если нужно.

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

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

Для менеджера качества

• Выполнить регрессионные визуальные тесты.
• Проверить доступность и поведение клавиатуры.
• Подтвердить критерии приёмки.

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

• Без Storybook: использовать кастомные примеры страниц в приложении — проще, но менее изолированно.
• Лёгкая документация: MDX в Storybook для смешения документации и историй.
• Visual testing as service: интеграция с Chromatic для автоматических снимков экрана.

Ментальные модели

• Компонент = функция с четко определёнными входами (props) и выходом (рендер).
• История = сценарий использования компонента с конкретными входными данными.
• Args = набор параметров, которые можно менять, как на панели управления.

Совместимость и миграция

Если вы мигрируете с другой сборкой, учтите:

• Версии Storybook иногда несовместимы между мажорными релизами — проверьте changelog.
• Addon-ы могут требовать отдельной настройки для Webpack/Vite.
• При переходе на TypeScript добавьте декларации для stories (stories.tsx).

Пример расширений и сниппетов

Добавьте outline-стили для истории:

export const Outline = Template.bind({})

Outline.args = {
  backgroundColor: 'transparent',
  color: '#6B4EFF',
  border: '1px solid #6B4EFF',
  label: 'Outline'
}

Пример обёртки провайдером (если компонент зависит от ThemeProvider):

export default {
  title: 'Components/Button',
  component: Button,
  decorators: [Story => ]
}

Когда Storybook не решит проблему

Контрпример

Если компонент сильно связан с глобальным состоянием приложения (сложная бизнес-логика, зависимости на WebSocket, роутинг), Storybook поможет лишь частично: придётся либо мокать провайдеры, либо тестировать в интеграционном окружении.

Decision tree для выбора Storybook

flowchart TD
  A[Нужно ли разрабатывать UI изолированно?] -->|Да| B[Используйте Storybook]
  A -->|Нет| C[Можно обойтись простыми примерами в приложении]
  B --> D[Есть требования к визуальному тестированию?]
  D -->|Да| E[Интегрируйте Chromatic/ Percy]
  D -->|Нет| F[Оставьте только локальную разработку и документацию]

Безопасность и приватность

Storybook обычно хранится локально. Если вы размещаете Storybook публично (например, Chromatic или GitHub Pages), убедитесь, что в историях не попадают реальные данные пользователей или секреты.

Краткий план действий для 1 дня

• Установить Storybook и запустить локально.
• Перенести 3 ключевых компонента с историями (включая Button).
• Настроить минимум one snapshot-тест.
• Провести обзор с дизайнером.

Краткое резюме

Storybook ускоряет разработку компонентов, даёт визуальную документацию и улучшает коммуникацию между командами. Простые шаги в этом руководстве помогут подключить Storybook, создать компонент Button и описать его состояния через stories и args.

Ключевые выводы

• Storybook делает компоненты видимыми и тестируемыми в изоляции.
• Args и Template упрощают создание интерактивных историй.
• Включайте accessibility и snapshot-тесты для надёжности.

Обратите внимание

Настраивайте Storybook под рабочий процесс команды: добавляйте декораторы, провайдеры и интеграции с CI по мере роста набора компонентов.