Storybook

Qu’est-ce que Storybook ?

Storybook est un atelier pour composants UI. Il rend un composant de manière isolée, en dehors de votre application, ce qui vous permet de le développer sans avoir à naviguer vers la bonne page ou à remplir des conditions spécifiques. Chaque état important devient une story, et l’ensemble de ces stories constitue une documentation vivante.

Initialement conçu comme un outil de développement, Storybook a évolué pour devenir bien plus : un auditeur d’accessibilité, une surface de test d’interaction et une cible pour les tests de régression visuelle. Pour les équipes qui créent des design systems ou des bibliothèques de composants partagés, c’est souvent l’outil front-end le plus précieux après le framework lui-même.

Stories

Un fichier de story exporte un objet meta par défaut et un export nommé par état.

// 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 },
};

Le title détermine l’emplacement du composant dans la barre latérale. Le component lie la story au composant afin que Storybook puisse en déduire les props et générer la documentation. Chaque export nommé correspond à une story.

Args et contrôles

Les args sont les props qu’une story passe au composant. Storybook les transforme en un panneau de contrôles, vous permettant ainsi de modifier les valeurs en temps réel sans éditer le code.

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

Comme les args sont des données structurées, ils alimentent également les autodocs, peuvent être partagés entre plusieurs stories et peuvent être réutilisés par les tests d’interaction. Définir le markup en ligne dans une fonction render fonctionne, mais vous perdez les contrôles en direct et la source unique de vérité ; privilégiez donc les args.

Décorateurs et contexte

Certains composants nécessitent un provider, un thème ou un wrapper de mise en page. Les décorateurs permettent de fournir ce contexte autour d’une story.

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

Un décorateur peut être global, défini par fichier ou par story, ce qui facilite la revue d’un composant sous différents thèmes ou locales sans avoir à modifier le composant lui-même.

Autodocs

Storybook peut générer une page de documentation à partir de vos stories et de leurs args. Lorsque l’option autodocs est activée, chaque composant dispose d’une page listant ses props, ses contrôles et toutes ses stories. Cette page reste synchronisée automatiquement puisqu’elle est générée à partir de la même source. Vous pouvez l’enrichir avec une description, des notes d’utilisation et des exemples de code en utilisant l’API parameters.docs.

Tests d’interaction

Une story peut définir une play function qui s’exécute après le rendu du composant. Elle utilise les mêmes requêtes et événements que Testing Library, le modèle mental est donc identique.

// 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();
  },
};

Comme le test s’exécute à l’intérieur de Storybook, vous pouvez le suivre étape par étape, ce qui rend le débogage bien plus simple qu’un échec en CI. Ces mêmes stories peuvent être exécutées en mode headless dans votre CI avec le test runner de Storybook.

Accessibilité et tests visuels

L’addon d’accessibilité exécute axe sur chaque story et signale les violations dans le panneau de l’addon, regroupées par niveau d’impact. Il détecte les labels manquants, les contrastes insuffisants, les attributs ARIA invalides et d’autres problèmes similaires pendant le développement, ce qui est bien moins coûteux que de les corriger plus tard.

Les outils de régression visuelle capturent une capture d’écran par story et la comparent à une référence (baseline). Comme chaque état est déjà une story, vous obtenez une large couverture visuelle avec très peu d’efforts supplémentaires. Toute modification d’une capture d’écran signale un changement visuel involontaire à examiner.

Où se situe Storybook

Storybook se positionne entre les tests unitaires et les tests de bout en bout. Il ne remplace aucun des deux. Utilisez-le pour développer et documenter vos composants de manière isolée, pour tester des états interactifs avec des fonctions play, et pour auditer l’accessibilité et le rendu visuel. Conservez vos tests de logique rapides dans Vitest, les tests de comportement des composants dans Testing Library, et les parcours utilisateurs complets dans Playwright.

Bonnes pratiques

• Rédigez une story par état significatif, y compris le chargement, l’état vide et les erreurs.
• Privilégiez les args au marquage en ligne afin que les contrôles et la documentation restent précis.
• Colocalisez les stories avec leurs composants et nommez-les selon leur usage.
• Utilisez des decorators pour les providers, les thèmes et le layout au lieu de dupliquer les wrappers.
• Ajoutez des fonctions play pour les interactions et exécutez-les dans votre CI.
• Activez l’addon d’accessibilité et corrigez les violations dès qu’elles apparaissent.
• Publiez le Storybook buildé en tant que documentation vivante.

Erreurs courantes

• Ne rédiger qu’une story “Default” et oublier les états réels.
• Hardcoder les props dans render, perdant ainsi le contrôle et la documentation.
• Considérer Storybook comme un remplacement pour les tests unitaires ou de bout en bout.
• Laisser les stories s’écarter des props réelles du composant.
• Ignorer les avertissements d’accessibilité jusqu’à ce qu’ils s’accumulent.
• Dupliquer la configuration du provider dans chaque story au lieu d’utiliser un decorator.

Et après ?

Storybook transforme vos composants en un catalogue documenté et testable. Associez-le à Testing Library pour les requêtes à l’intérieur des fonctions play, Vitest pour les tests de logique et Playwright pour les flux de bout en bout. Ensuite, choisissez votre composant le plus utilisé et créez des stories pour chacun de ses états possibles.