Storybook

Was ist Storybook?

Storybook ist eine Werkstatt für UI-Komponenten. Es rendert eine Komponente isoliert, außerhalb Ihrer Anwendung, sodass Sie diese entwickeln können, ohne mühsam zur richtigen Seite navigieren oder bestimmte Bedingungen erfüllen zu müssen. Jeder Zustand, der für Sie relevant ist, wird zu einer Story, und die Sammlung dieser Stories wird zu einer lebendigen Dokumentation.

Was als reines Entwicklungstool begann, hat sich zu weit mehr entwickelt: einem Tool für Accessibility-Audits, einer Oberfläche für Interaktionstests und einem Ziel für Visual-Regression-Tests. Für Teams, die Design-Systeme oder gemeinsame Komponenten-Bibliotheken erstellen, ist es oft das wertvollste Front-End-Tool überhaupt, direkt nach dem verwendeten Framework.

Stories

Eine Story-Datei exportiert ein Standard-Meta-Objekt sowie einen benannten Export pro Zustand.

// Button.stories.jsx
import { Button } from "./Button";

export default {
  title: "Components/Button",
  component: Button,
  args: { children: "Save" },
  argTypes: {
    variant: {
      control: "select",
      options: ["primary", "secondary", "ghost"],
    },
  },
};

export const Primary = {
  args: { variant: "primary" },
};

export const Secondary = {
  args: { variant: "secondary" },
};

export const Disabled = {
  args: { disabled: true },
};

Das title bestimmt, wo die Komponente in der Sidebar erscheint. Das component verknüpft die Story mit der Komponente, sodass Storybook die Props ableiten und die Dokumentation generieren kann. Jeder benannte Export ist eine Story.

Args und Controls

Args sind die Props, die eine Story an die Komponente übergibt. Storybook wandelt diese in ein Controls-Panel um, sodass du Werte live ändern kannst, ohne den Code bearbeiten zu müssen.

// Card.stories.jsx
export default {
  title: "Components/Card",
  component: Card,
  args: {
    title: "Pro plan",
    description: "Everything you need to ship.",
    elevated: false,
  },
};

Da Args strukturierte Daten sind, steuern sie auch die Autodocs, können zwischen Stories geteilt und in Interaktionstests wiederverwendet werden. Das Definieren von Markup inline in einer render-Funktion funktioniert zwar, führt aber zum Verlust der Live-Controls und der „Single Source of Truth“ – daher solltest du Args bevorzugen.

Decorators und Kontext

Einige Komponenten benötigen einen Provider, ein Theme oder einen Layout-Wrapper. Decorators stellen diesen Kontext rund um eine Story bereit.

// preview.jsx
export default {
  decorators: [
    (Story) => (
      <ThemeProvider theme="dark">
        <div style={{ padding: "1rem" }}>
          <Story />
        </div>
      </ThemeProvider>
    ),
  ],
};

Ein Decorator kann global, pro Datei oder pro Story definiert werden. Das macht es einfach, eine Komponente in verschiedenen Themes oder Locales zu prüfen, ohne die Komponente selbst ändern zu müssen.

Autodocs

Storybook kann automatisch eine Dokumentationsseite aus deinen Stories und deren Args generieren. Wenn Autodocs aktiviert ist, erhält jede Komponente eine Seite, auf der die Props, Controls und jede einzelne Story aufgelistet werden. Diese bleibt automatisch synchron, da sie aus derselben Quelle generiert wird. Du kannst die Seite mithilfe der parameters.docs API mit Beschreibungen, Nutzungshinweisen und Code-Beispielen anreichern.

Interaktionstests

Eine Story kann eine play function definieren, die nach dem Rendern der Komponente ausgeführt wird. Sie verwendet dieselben Queries und Events wie Testing Library, sodass das mentale Modell direkt übertragbar ist.

// Search.stories.jsx
import { expect, userEvent, within } from "@storybook/test";

export const TypesAndSubmits = {
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement);

    await userEvent.type(canvas.getByLabelText("Search"), "vitest");
    await userEvent.click(canvas.getByRole("button", { name: "Go" }));

    await expect(canvas.getByText("3 results")).toBeVisible();
  },
};

Da der Test innerhalb von Storybook läuft, können Sie ihn Schritt für Schritt beobachten, was das Debugging wesentlich einfacher macht als bei einem fehlgeschlagenen CI-Run. Dieselben Stories können in der CI mit dem Storybook test runner headless ausgeführt werden.

Barrierefreiheit und visuelles Testing

Das Accessibility-Addon führt axe für jede Story aus und meldet Verstöße im Addon-Panel, gruppiert nach ihrer Auswirkung. Es erkennt fehlende Labels, schlechte Kontraste, ungültiges ARIA und ähnliche Probleme bereits während der Entwicklung, was wesentlich kostengünstiger ist, als diese später zu beheben.

Tools für visuelle Regression erstellen pro Story einen Screenshot und vergleichen diesen mit einem Baseline-Bild. Da jeder Zustand bereits als Story existiert, erhalten Sie eine umfassende visuelle Abdeckung mit minimalem Mehraufwand. Ein geänderter Screenshot markiert eine unbeabsichtigte visuelle Änderung zur Überprüfung.

Wo Storybook ins Spiel kommt

Storybook positioniert sich zwischen Unit-Tests und End-to-End-Tests. Es ist kein Ersatz für keines von beidem. Nutze es, um Komponenten isoliert zu entwickeln und zu dokumentieren, interaktive Zustände mit Play-Funktionen zu testen sowie die Barrierefreiheit und das visuelle Design zu prüfen. Behalte schnelle Logik-Tests in Vitest, das Komponentenverhalten in Testing Library und vollständige User Journeys in Playwright.

Best Practices

• Schreiben Sie pro bedeutsamem Zustand eine Story, einschließlich Loading-, Empty- und Error-States.
• Bevorzugen Sie args gegenüber Inline-Markup, damit Controls und Dokumentation präzise bleiben.
• Platzieren Sie Stories direkt bei ihren Komponenten (Colocation) und benennen Sie diese nach ihrem Verwendungszweck.
• Nutzen Sie Decorators für Provider, Themes und Layouts, anstatt Wrapper zu duplizieren.
• Fügen Sie play functions für Interaktionen hinzu und lassen Sie diese in der CI ausführen.
• Aktivieren Sie das Accessibility-Addon und beheben Sie Verstöße, sobald sie auftreten.
• Veröffentlichen Sie das gebaute Storybook als lebendige Dokumentation.

Häufige Fehler

• Nur eine „Default“-Story schreiben und reale Zustände vernachlässigen.
• Props in render hartcodieren und dadurch Controls und Dokumentation verlieren.
• Storybook als Ersatz für Unit- oder End-to-End-Tests betrachten.
• Stories zulassen, die von den tatsächlichen Props der Komponente abweichen.
• Accessibility-Warnungen ignorieren, bis sie sich aufstauen.
• Das Provider-Setup in jeder Story duplizieren, anstatt einen Decorator zu verwenden.

Wie geht es weiter?

Storybook verwandelt Komponenten in einen dokumentierten und testbaren Katalog. Kombinieren Sie es mit Testing Library für die Queries innerhalb von play functions, Vitest für Logik-Tests und Playwright für End-to-End-Flows. Wählen Sie anschließend Ihre am häufigsten verwendete Komponente aus und erstellen Sie Stories für jeden möglichen Zustand.