Storybook – Für eine robuste Entwicklung von Komponenten

Was ist Storybook?

Storybook ist ein JavaScript Open-Source-Tool, welches es Entwickler:innen ermöglicht, Komponenten in einer isolierten Umgebung, unabhängig von einer Businesslogik zu entwickeln, zu visualisieren und auf ihre Funktionalität zu testen. Hierfür wird außerhalb der Anwendung eine separate Seite gebaut, welche als eine Art Komponentenbibliothek gilt und alle Komponenten geordnet visualisiert. Diese Seite ermöglicht es interaktiv durch die Komponenten zu navigieren, diese zu inspizieren und durch Verändern der Attribute verschiedene Zustände zu erzeugen. Da hierfür keine Programmierkenntnisse benötigt werden, können etwa Designer:innen effektiver mit den Entwickler:innen zusammenarbeiten. Durch die Integration der Testing Umgebung, die auf Jest und Playwright basiert, können die Komponenten auf Herz und Nieren getestet werden. Zuletzt ist es ebenfalls möglich, die Funktionalität von Storybook durch Erweiterungen zu verbessern. Storybook wird von Beginn aus bereits mit einer Handvoll von Erweiterungen ausgeliefert. Darunter fällt die Dokumentations-Erweiterung, welche es ermöglicht, automatisiert Dokumentation mittels Kommentare im Quellcode zu erzeugen.

Storybook aufsetzen

Bevor Storybook gestartet werden kann, muss dieses installiert werden. Hierfür muss innerhalb einer bestehenden Projektstruktur eines unterstützten Frameworks der folgende Befehl ausgeführt werden.

npx storybook@latest init

Anschließend wird das Projekt mit allen notwendigen Abhängigkeiten ausgestattet und ein Beispielordner initialisiert.

Zum Starten von Storybook, welches eine eigene Entwicklung Umgebung besitzt, kann folgender Befehl ausgeführt werden.

npm run storybook

Anschließend kann mit der Entwicklung der Stories begonnen werden. Hierfür wird innerhalb eines Verzeichnisses der Komponente eine weitere Datei angelegt, welche componentName.stories.(js|ts) als Dateinamen besitzt. Innerhalb dieser Datei wird jetzt mittels der Component Story Format (CSF) eine Umgebung für die Komponente erzeugt. Die metaVariable ist hierbei eine Art der lokalen Konfiguration. Innerhalb diesem Objekt können Optionen gesetzt werden, die für alle Stories gelten, als auch Metadaten. Die benannten Exporte innerhalb dieser Datei, die dem Typ Story entsprechen, sind die verschiedenen Variationen der Komponente. Innerhalb dieser Story können nun die allgemeinen Einstellungen überschrieben und Parameter an die Komponente übergeben werden.

import type { Meta, StoryObj } from '@storybook/angular';

import { ButtonComponent } from './button.component';

const meta: Meta<ButtonComponent> = {
  component: ButtonComponent,
};

export default meta;
type Story = StoryObj<ButtonComponent>;

export const PrimaryButton: Story = {
  args: {
    color: "primary"
  },
};

export const SecondaryButton: Story = {
  args: {
    color: "secondary"
  },
};

// more variants...

Testing

Das Testen von Komponenten ist ein wichtiger Schritt, um sicherzustellen, dass die Benutzer:innen der Anwendung auf keine Probleme stoßen, die womöglich Konsequenzen mit sich bringen. Hierfür bringt Storybook eine eigene Testing Umgebung, die auf den beliebten Frameworks Jest und Playwright basieren, mit sich. Diese ermöglichen das simple Testen der Benutzeroberfläche bis hin zu gesamten Abläufen innerhalb der Anwendung. Dies ermöglicht es, einen Userflow zu simulieren, der über verschiedene Interaktionen und navigieren von Seiten hinausragt.

Um eine Story zu testen, wird innerhalb des Story Objektes eine play Funktion definiert. Diese Funktion dient als Testing Umgebung einer Story und beinhaltet den Quellcode der Tests. Die play Funktion erhält als Übergabeparameter den Kontext der gesamten Story, welcher benötigt wird, um den Canvas mit der Komponente zu befüllen. Hierfür wird die within Funktion von Testing library verwendet, welche einen Canvas zurückgibt, auf dem die verschiedenen Tests ausgeführt werden. Anschließend kann durch verschiedene Abfragemethoden wie getByRole, getByText oder getByTestId ein HTML Element aus dem Canvas selektiert werden. Testing Library erzeugt hierbei ein nützliches Feature, da Elemente nur über Inhalte, die für assistive Technologien verfügbar sind, abgefragt werden können. Somit wird eine minimale, grundlegende Barrierefreiheit innerhalb der Anwendung sichergestellt. Mittels der Testing Library können nun verschiedene Interaktionen auf den Elementen ausgeführt werden. Abschließend kann jetzt mittels der expect Funktion, die von Jest importiert wird, die erwarteten Veränderungen abgefragt werden.

// other imports...
import { userEvent, within } from '@storybook/testing-library';
import { expect } from '@storybook/jest';

// ...

export const LoggedOutWithButton: Story = {
  play: async (context) => {
    const canvas = within(context.canvasElement);

    await userEvent.click(canvas.getByTestId('logout-btn'));

    await expect(canvas.getByRole('button', { name: /Log in/i })).toBeInTheDocument();
    await expect(canvas.getByRole('button', { name: /Log out/i })).not.toBeInTheDocument();
  }
}

Nachdem diese play Funktion implementiert wurde, kann jeder Schritt, der ausgeführt wurde, und der Benutzeroberfläche von Storybook eingesehen und zu diesem Zustand gesprungen werden. Diese Funktionalität kann durch Erweiterungen auch noch ausgebaut werden, um beispielsweise die Story Tests mittels der Kommandozeile auszuführen. Ebenfalls ist es möglich, mittels einer Erweiterung, Snapshot Testing hinzuzufügen, wobei der neue Zustand pixelgenau mit dem vorherigen Zustand abgeglichen wird.

Erweiterungen

Storybook bietet von Haus aus bereits einen großen, umfangreichen Funktionskatalog an. Dieser kann jedoch durch das Einbinden von Erweiterungen noch weiter ausgebaut werden. Hierfür bietet Storybook auf ihrer Website eine eigene Sektion mit dem Namen „Integrations“, welche eine Auflistung der vielfältigen Erweiterungen verfügt.

a11y

Die Accessibility (a11y) Erweiterung ermöglicht es, die Komponenten in Storybook automatisiert auf die a11y Konventionen zu überprüfen. Somit kann sichergestellt werden, dass die Komponenten oder ganze Seiten von allen Benutzer:innen ohne Einschränkungen wahrgenommen werden kann. a11y testet hierbei auf visuelle Eigenschaften, wie Kontrastwerte von einer Schriftfarbe zu einer Hintergrundfarbe, als auch den korrekten Einsatz der ARIA Attribute der HTML-Elemente.

Test runner

Durch den Einsatz der Test runner Erweiterung wird die bereits ausgiebige Testing Umgebung von Storybook erweitert. Eine der Hauptfunktionen von Test runner ist das Ausführen der Tests, die innerhalb einer .stories. Datei definiert wurden, mittels der Kommandozeile. Somit können das Überprüfen der Tests auch innerhalb einer Pipeline ausgeführt und überprüft werden. Weitere Funktionen sind beispielsweise die automatisierte Generation von Smoke Tests, Code Coverage Reports als auch die Möglichkeit Snapshot Tests zu schreiben.

Designs

Mittels der Designs Erweiterung wird eine Integration von Designvorgaben in Storybook gegeben. Somit können beispielsweise Figma Designvorlagen innerhalb von Storybook eingebettet und mit der Implementierung verglichen werden. Dies verbessert und erleichtert die Zusammenarbeit von Entwickler:innen und Designer:innen.

Fazit

Das Aufsetzen von Storybook in ein Projekt erfolgt durch eine Handvoll von Schritten. Auch das Implementieren von Komponenten kann mit wenigen Schritten umgesetzt werden. Jedoch kann das Aufsetzen in einem großen existierenden Projekt, das bereits eine Vielzahl von Komponenten aufweist, als schwerer erweisen. Verschiedene Abhängigkeiten, wie Businesslogik oder einer API, müssen zuerst abgekoppelt werden, bevor diese Komponente in ein Storybook implementiert werden. Daraus lässt sich schließen, dass eine Implementierung in einem neuen Projekt sinnvoll erscheint und in bestehenden Projekten dies zuerst ermittelt werden muss.

Abschließend lässt sich sagen, dass Storybook ein umfangreiches Werkzeug ist, welches ein breites Spektrum an Funktionen abdeckt, die zusätzlich durch die Integration von Erweiterungen noch verbessert werden kann. Die Möglichkeit, alle Komponenten, gesammelt in einer separaten Anwendung zu visualisieren und somit Designer:innen als auch anderen Mitarbeiter:innen zu präsentieren, erweist sich als äußerst hilfreich. Durch die zusätzliche Möglichkeit, die Komponenten mittels Jest und Playwright auf ihre Funktionalität und Aussehen zu testen, versichert eine robuste und kontinuierlich gestaltete Anwendung.