Guía Completa de Storybook: Desarrollo, Pruebas y Documentación de Interfaces de Usuario

Construir componentes de interfaz de usuario (UI) consistentes y escalables es crucial en el desarrollo web moderno. Storybook es una herramienta que permite a los desarrolladores aislar, desarrollar, probar y documentar componentes de UI en un entorno aislado (sandboxed).

Storybook te permite:

✅ Desarrollar componentes de forma aislada sin necesidad de ejecutar la aplicación completa.
✅ Crear una librería de componentes para mantener la consistencia del diseño.
✅ Probar y documentar el comportamiento de la UI de forma interactiva.
✅ Integrar con frameworks como React, Vue, Angular y más.

En esta guía completa, cubriremos los siguientes temas..

¿Qué es Storybook?

Storybook es una herramienta de código abierto para construir componentes de UI de forma aislada.

Proporciona un entorno dedicado para probar y documentar componentes sin necesidad de ejecutar la aplicación completa.

¿Por qué usar Storybook?

Característica	Storybook
Desarrollar componentes de forma aislada	✅ Sí
Previsualización interactiva de componentes	✅ Sí
Generación de documentación integrada	✅ Sí
Soporte para múltiples frameworks	✅ Sí
Integración con Jest, Testing Library, Playwright	✅ Sí

Instalación y Configuración de Storybook

Storybook se puede instalar en un proyecto nuevo o existente.

Instalación para React

Ejecuta el siguiente comando en el directorio de tu proyecto:

npx storybook@latest init

Este comando:

• Detecta automáticamente el framework y configura Storybook.
• Genera una carpeta .storybook con archivos de configuración.
• Crea historias de ejemplo para empezar.

Iniciar Storybook

npm run storybook

Storybook se abrirá en http://localhost:6006/.

Escribiendo tu Primera Historia

Una «historia» representa un estado de un componente de UI. Define cómo debe aparecer el componente en diferentes escenarios.

Ejemplo Básico de Historia de Botón (React)

Crea un archivo Button.stories.js dentro de src/components/Button/:

import React from 'react';
import Button from './Button';

export default {
  title: 'Componentes/Button',
  component: Button,
};

export const Primario = () => <Button label="Botón Primario" />;
export const Secundario = () => <Button label="Botón Secundario" variant="secondary" />;

• Cada export representa un estado diferente del componente.
• title define la categoría en Storybook.
• component vincula el componente de UI a la historia.

Usando Controles para Interacción Dinámica

Los «Controles» de Storybook permiten a los desarrolladores modificar las props (propiedades) dinámicamente en la UI.

Ejemplo: Añadiendo Controles a un Botón

Modifica Button.stories.js:

export const Playground = (args) => <Button {...args} />;

Playground.args = {
  label: 'Botón Dinámico',
  variant: 'primary',
};

Ahora, Storybook proporcionará un panel en la UI donde los desarrolladores pueden cambiar label y variant dinámicamente.

• Ayuda a probar diferentes estados sin modificar el código.

Mejorando Storybook con Add-ons (Complementos)

Los «Add-ons» de Storybook extienden su funcionalidad.

Add-ons Populares de Storybook

Add-on	Propósito
@storybook/addon-controls	Ajustar props dinámicamente
@storybook/addon-docs	Generar documentación
@storybook/addon-a11y	Pruebas de accesibilidad
@storybook/testing-library	Pruebas de interacción de la UI

Instalando un Add-on

Ejemplo: Instalando el Add-on de Accesibilidad

npm install @storybook/addon-a11y --save-dev

Modifica .storybook/main.js para registrar el add-on:

module.exports = {
  addons: ['@storybook/addon-a11y'],
};

• Añade un panel de «Accesibilidad» para probar contraste, atributos ARIA y problemas de color.

Organizando Historias para Escalabilidad

Un proyecto de Storybook bien estructurado mejora el mantenimiento.

Estructura de Carpetas Recomendada

  src
 ┣   components
 ┃ ┣   Button
 ┃ ┃ ┣   Button.js
 ┃ ┃ ┣   Button.stories.js
 ┃ ┃ ┣   Button.test.js
 ┣   .storybook
 ┃ ┣   main.js   # Configuraciones
 ┃ ┣   preview.js  # Decoradores globales

• Cada componente tiene su propia carpeta para facilitar la organización.
• .storybook/main.js gestiona las configuraciones y los add-ons.

Automatizando Pruebas de Accesibilidad en Storybook

Asegurar que tus componentes de UI sean accesibles es crucial para la usabilidad. Storybook se integra con herramientas de prueba de accesibilidad para detectar automáticamente posibles problemas.

Instalando el Add-on de Accesibilidad

npm install --save-dev @storybook/addon-a11y

Habilitando el Add-on

Modifica .storybook/main.js:

module.exports = {
  addons: ['@storybook/addon-a11y'],
};

Ejecutando Pruebas de Accesibilidad

Cuando la UI de Storybook se carga, un nuevo panel de «Accesibilidad» aparece, mostrando cualquier problema detectado.

• Comprueba automáticamente problemas de contraste, falta de atributos ARIA y accesibilidad con el teclado.
• Ayuda a solucionar problemas de cumplimiento de WCAG antes de la producción.

Pruebas de Regresión Visual en Storybook

Las Pruebas de Regresión Visual detectan cambios en la UI comparando componentes renderizados antes y después de las actualizaciones. Esto asegura que las modificaciones en la UI no introduzcan cambios de diseño no intencionados.

Instalando Add-ons de Pruebas Visuales

npm install --save-dev @storybook/addon-visual-tests

Añadiendo una Prueba de Captura de Pantalla (Screenshot)

Modifica Button.stories.js:

import { within, userEvent } from '@storybook/testing-library';

export const VisualTest = () => <Button label="Haz clic" />;

VisualTest.play = async ({ canvasElement }) => {
  const canvas = within(canvasElement);
  const button = canvas.getByRole('button');
  await userEvent.click(button);
};

Ejecutando Pruebas Visuales

npx storybook test

• Detecta cambios en la UI con comparaciones automáticas de snapshots.

Simulando Llamadas a la API (Mocking) en Storybook

Storybook puede simular peticiones a la API para probar el comportamiento de la UI sin depender de un backend.

Ejemplo: Simulando una Respuesta de la API

Instala Mock Service Worker (MSW):

npm install msw --save-dev

Crea mocks.js:

import { setupWorker, rest } from 'msw';

export const worker = setupWorker(
  rest.get('/api/user', (req, res, ctx) => {
    return res(ctx.json({ name: 'Usuario Mock' }));
  })
);

Inicia el servidor mock en preview.js:

import { worker } from '../mocks';

worker.start();

• Los componentes ahora reciben respuestas de la API simuladas durante el desarrollo.

Integrando Storybook con Playwright para Pruebas E2E

Storybook se puede usar con Playwright para realizar pruebas end-to-end (E2E) para componentes de UI.

Instalando Playwright

npm install --save-dev @playwright/test

Escribiendo una Prueba de Playwright para un Componente de Storybook

Crea un archivo Button.spec.js:

const { test, expect } = require('@playwright/test');

test('Verificar si el componente Botón se renderiza', async ({ page }) => {
    await page.goto('http://localhost:6006/?path=/story/components-button--primario');
    const button = await page.locator('button');
    await expect(button).toHaveText('Botón Primario');
});

Ejecutando la Prueba de Playwright

npx playwright test

• Combina las pruebas de componentes de UI con la automatización completa del navegador.

Escribiendo Pruebas de Componentes en Storybook

Storybook se integra con Jest, Testing Library y Playwright para pruebas de UI.

Ejemplo: Probando con Jest + Testing Library

Instala las dependencias:

npm install @testing-library/react jest --save-dev

Crea Button.test.js:

import { render, screen } from '@testing-library/react';
import Button from './Button';

test('renderiza el botón', () => {
  render(<Button label="Haz clic" />);
  expect(screen.getByText('Haz clic')).toBeInTheDocument();
});

• Asegura que los componentes se renderizan correctamente.
• Se ejecuta con npm test.

Desplegando Storybook como Documentación

Storybook se puede desplegar como un sitio de documentación de componentes.

Generar la Construcción Estática

npm run build-storybook

Esto crea una carpeta storybook-static/.

Desplegar en GitHub Pages

npx storybook-to-ghpages

• Hace que Storybook sea accesible a través de GitHub Pages o cualquier host estático.

Ejecutando Storybook en CI/CD

Integrar Storybook en pipelines de CI/CD asegura la consistencia de la UI en todo el desarrollo.

Ejemplo de GitHub Actions

Crea .github/workflows/storybook.yml:

name: Storybook CI
on: push
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v2
      - name: Install Dependencies
        run: npm install
      - name: Build Storybook
        run: npm run build-storybook
      - name: Deploy Storybook
        run: npx storybook-to-ghpages

• Ejecuta Storybook en cada push de código.

Mejores Prácticas para Proyectos de Storybook

✅ Usa los Add-ons de Controles y Docs para la interacción dinámica con los componentes.
✅ Organiza los componentes por categoría (Componentes/Button vs Componentes/Inputs).
✅ Automatiza las pruebas visuales y de snapshot para detectar cambios no intencionados.
✅ Despliega Storybook como documentación en vivo para desarrolladores y diseñadores.
✅ Integra Storybook en CI/CD para asegurar la consistencia de la UI.

Conclusión

Storybook es una herramienta poderosa para el desarrollo, prueba y documentación de interfaces de usuario. Mejora la reutilización, la consistencia y la colaboración entre equipos.