diff --git a/_assets/tutorials/2024-03-27-chromatic/turbosnap-pepperidge.jpg b/_assets/tutorials/2024-03-27-chromatic/turbosnap-pepperidge.jpg new file mode 100644 index 000000000..cc8164f0f Binary files /dev/null and b/_assets/tutorials/2024-03-27-chromatic/turbosnap-pepperidge.jpg differ diff --git a/_assets/tutorials/2024-03-27-chromatic/ui-tests.png b/_assets/tutorials/2024-03-27-chromatic/ui-tests.png new file mode 100644 index 000000000..ef92e53fa Binary files /dev/null and b/_assets/tutorials/2024-03-27-chromatic/ui-tests.png differ diff --git a/_assets/tutorials/2024-03-27-chromatic/ui-tests3.png b/_assets/tutorials/2024-03-27-chromatic/ui-tests3.png new file mode 100644 index 000000000..1da6413c1 Binary files /dev/null and b/_assets/tutorials/2024-03-27-chromatic/ui-tests3.png differ diff --git a/_assets/tutorials/2024-03-27-chromatic/ui-tests4.png b/_assets/tutorials/2024-03-27-chromatic/ui-tests4.png new file mode 100644 index 000000000..9ce16faba Binary files /dev/null and b/_assets/tutorials/2024-03-27-chromatic/ui-tests4.png differ diff --git a/_assets/tutorials/2024-03-27-chromatic/ui-tests5.png b/_assets/tutorials/2024-03-27-chromatic/ui-tests5.png new file mode 100644 index 000000000..9a805146b Binary files /dev/null and b/_assets/tutorials/2024-03-27-chromatic/ui-tests5.png differ diff --git a/_assets/tutorials/2024-03-27-chromatic/ui-tests6.png b/_assets/tutorials/2024-03-27-chromatic/ui-tests6.png new file mode 100644 index 000000000..09d81cc7b Binary files /dev/null and b/_assets/tutorials/2024-03-27-chromatic/ui-tests6.png differ diff --git a/_authors/afauquet.md b/_authors/afauquet.md new file mode 100644 index 000000000..3365bce7a --- /dev/null +++ b/_authors/afauquet.md @@ -0,0 +1,6 @@ +--- +contentType: author +username: afauquet +name: Alice Fauquet +--- +Frontend developer diff --git a/_tutorials/fr/2024-03-27-chromatic/index.md b/_tutorials/fr/2024-03-27-chromatic/index.md new file mode 100644 index 000000000..4584f2bca --- /dev/null +++ b/_tutorials/fr/2024-03-27-chromatic/index.md @@ -0,0 +1,26 @@ +--- +contentType: tutorial +lang: fr +date: '2024-03-27' +slug: chromatic +title: Ajouter des tests de non régression visuelle (et plus encore !) sur Storybook avec Chromatic +excerpt: >- + Nous allons découvrir comment utiliser Chromatic en CI pour faire des tests de non régression visuelle et des tests d'interaction sur un Storybook pour être confiant à chaque nouvelle feature implémentée. +categories: + - javascript +keywords: + - chromatic + - storybook + - visual-testing + - react + - design system +authors: + - afauquet +steps: + - introduction + - initialization + - chromatic-in-ci + - chromatic-use + - other-tests + - conclusion +--- diff --git a/_tutorials/fr/2024-03-27-chromatic/steps/chromatic-in-ci.md b/_tutorials/fr/2024-03-27-chromatic/steps/chromatic-in-ci.md new file mode 100644 index 000000000..e8829adcb --- /dev/null +++ b/_tutorials/fr/2024-03-27-chromatic/steps/chromatic-in-ci.md @@ -0,0 +1,82 @@ +--- +contentType: tutorial-step +tutorial: chromatic +slug: chromatic-in-ci +title: Utilisation de Chromatic en CI +--- + +## Utilisation de Chromatic en CI + +Nous allons commencer par **initialiser notre projet** et faire un premier commit. + +Utilisez les commandes suivantes pour créer **un premier commit** sur une branche principale appelée `main` : + +```bash +git init +git add . +git commit -m "init commit" +git branch -M main +``` + +Ensuite nous allons **créer un repo sur Github** et y envoyer notre premier commit. Rendez-vous sur cette page [https://github.com/new](https://github.com/new) puis créez un repo "chromatic-tuto-elevenlabs". Sur votre terminal, lancez ces commandes (les commandes sont aussi indiquées préremplies sur Github) : + +```bash +git remote add origin https://github.com//.git +git push -u origin main +``` + +Votre premier commit est maintenant sur Github ! Nous allons désormais passer au moment que vous attendez tous : **installer Chromatic** ! + +Nous allons installer Chromatic en devDependency : + +```bash +npm install -D chromatic +``` + +Ensuite, connectez-vous à Chromatic avec votre compte GitHub : [https://www.chromatic.com/start](https://www.chromatic.com/start). +Choisissez l’option `Choose from GitHub`, choisissez le repo que nous utilisons pour ce tuto puis récupérez et utilisez la ligne de commande sous "Publish your Storybook", elle va nous permettre de **faire le lien entre le projet et Chromatic**. + +À la fin du processus vous trouverez un lien qui vous donnera accès à une **version publiée** de votre Storybook. Pas mal, non ? Chromatic vous affichera également **un token**, gardez-le de côté car on va s'en servir dans quelques instants. + +C’est très bien mais nous ce qu’on veut c’est utiliser Chromatic ! Il nous reste une dernière étape avant de rentrer dans le vif du sujet : **créer une Github Action** ! + +Tout d’abord on a besoin de **créer un secret** sur Github. Créez le secret `CHROMATIC_PROJECT_TOKEN` qui contient le token, que vous avez récupéré précédemment. [Pour créer un secret vous pouvez suivre cette documentation](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions). + +Retournez sur votre IDE, créez un dossier `.github/workflows` puis un fichier `chromatic.yml` et collez-y ce template ([qu'on peut également retrouver sur le documentation de Chromatic](https://www.chromatic.com/docs/github-actions/)) : + +```yml +# .github/workflows/chromatic.yml + +name: "Chromatic" + +on: push + +jobs: + chromatic: + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Install dependencies + run: yarn install --immutable --immutable-cache --check-cache + + - name: Publish to Chromatic + uses: chromaui/action@latest + with: + projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }} +``` + +Créez un commit et poussez-le sur le repo : + +```bash +git add . +git commit -m "GitHub action setup" +git push origin main +``` + +Vous pouvez trouver le build dans la pipeline après le push. + +Nous allons maintenant voir **comment fonctionne Chromatic** ! diff --git a/_tutorials/fr/2024-03-27-chromatic/steps/chromatic-use.md b/_tutorials/fr/2024-03-27-chromatic/steps/chromatic-use.md new file mode 100644 index 000000000..69d380e46 --- /dev/null +++ b/_tutorials/fr/2024-03-27-chromatic/steps/chromatic-use.md @@ -0,0 +1,294 @@ +--- +contentType: tutorial-step +tutorial: chromatic +slug: chromatic-use +title: Comment fonctionne Chromatic +--- + +## Comment fonctionne Chromatic ? + +Chromatic fonctionne avec **un système de builds** qui vont se créer à chaque lancement du job dans la CI. Chromatic va vérifier s’il y a des différences visuelles par rapport au build précédent. **S’il n’y a pas de différence, le build passera** et le job sera vert. **S’il y a des différences en revanche, le build ne passera pas**, le job sera orange ou rouge et il faudra accepter ou non les régressions détectées par Chromatic. + +Chromatic va prendre des snapshots, c’est-à-dire des **impressions d’écran** des stories. Pour déterminer s’il y a une différence, il va superposer le nouveau snapshot avec l’ancien et comparer, au pixel près, si quelque chose a changé. C’est le concept de test de non régression visuelle. + +Ce sont **les snapshots qui constituent les crédits** de Chromatic. La version gratuite permet actuellement de prendre 5000 snapshots par mois, ce qui est suffisant pour nos besoins pour l’instant. Cependant nous verrons plus tard que la quantité de snapshots peut augmenter exponentiellement. + +**Le snapshot est pris après la fin des animations** que Chromatic va tenter d’arrêter à la dernière frame. Il se fera également après la fin des interactions de Storybook. Si pour une quelconque raison le snapshot se prend trop tôt il est possible de **rajouter un délai** fixe pour éviter les tests flaky : + +```javascript +export const StoryName = { + args: { + with: "props", +}, + +parameters: { + // Sets the delay (in milliseconds) for a specific story. + chromatic: { delay: 300 }, +}; +``` +([Plus d'informations sur le délais ici](https://www.chromatic.com/docs/delay/)) + +Nous allons **approuver le premier build de Chromatic** pour avoir une branche main saine et avec laquelle on pourra comparer les modifications d'autres branches. + +Dans la pipeline du commit que nous venons de faire vous devriez retrouver l'icône de Chromatic et **un job nommé "UI Tests"**. Cliquez sur "Details" pour vous rendre directement sur **l'interface de Chromatic reliée à votre projet**, sur le build lié au commit. + +![Le job "UI Tests" est vert dans la CI de Github]({BASE_URL}/imgs/tutorials/2024-03-27-chromatic/ui-tests.png) + +Le build est vert : tous les nouveaux snapshots ont été acceptés par défaut ! Tout en bas de la page, dans la partie "Example", on peut retrouver les snapshots qui ont été pris des différents composants. Il y a également un bouton "View Storybook" à droite qui permet d'accéder à son Storybook publié. + +## Modifions le rendu d'un composant + +À partir de maintenant **nous allons faire des branches que nous mergerons** vers main pour reproduire un workflow standard de projet. Nous allons créer une branche qui va contenir une modification de style : + +```bash +git checkout -b feat/button-primay-backgroundcolor +``` + +Nous allons effectuer une **petite modification de couleur** pour vérifier que Chromatic nous demande bien de valider la différence sur notre PR. Dans notre fichier de style `button.css` nous allons changer **la couleur primaire du bouton** par un bleu légèrement différent : + +```css +.storybook-button--primary { + color: white; + background-color: #6495ed; /* Un bleu un peu différent ! */ +} +``` + +### Avec quel autre build Chromatic va t’il comparer exactement ? + +Chromatic va comparer les snapshots avec les snapshots du build d’un ou plusieurs ancêtres. + +Le cas le plus simple et peut-être le plus courant est celui d’un commit **poussé sur une branche déjà existante** et qui possède déjà un build. Chromatic va comparer le build avant le nouveau commit avec les snapshots pris sur le job du nouveau commit. + +Un autre cas : celui d’une nouvelle branche. Dans ce cas Chromatic va comparer le dernier build de la branche principale avec le snapshot de la nouvelle branche. C’est pourquoi il est **très important d’avoir son build de main à jour !** + +Le build se lance en réalité 2 fois : une fois dans la PR au moment du push, puis une seconde fois au merge de la branche vers la branche principale. Dans tous les cas à ce moment là le build avec lequel on va comparer sera **celui de la branche principale**. C’est pourquoi il est très important de lancer un build sur main avec l'option `autoAcceptChanges` pour éviter de valider 2 fois les mêmes changements. À moins qu’il y ait des erreurs dans les interactions ou autres bugs farfelus, le build sera automatiquement validé comme étant la nouvelle base saine pour les nouvelles branches. + +Pour plus d'informations sur les gestion des ancêtres de Chromatic vous pouvez vous rendre sur la [documentation](https://www.chromatic.com/docs/branching-and-baselines/). + +Nous allons configurer l'acceptation automatique des changements dans notre branche actuelle. Dans le fichier `chromatic.yml` nous allons ajouter en dessous du `ProjectToken` une nouvelle ligne qui configure `autoAcceptChanges` : + +```yaml +with: + projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }} + autoAcceptChanges: "main" # Accepte automatiquement les modifications sur main +``` + +Créez un commit avec ces modifications et poussez votre branche : + +```bash +git add . +git commit -m "feat: update button primary backgroundcolor and enable auto-accept on main" +git push -u origin feat/button-primay-backgroundcolor +``` + +Créez ensuite une pull request. Au bout de quelques secondes **vous retrouverez "UI Tests" dans les checks** de la PR. + +![Le job "UI Tests" est orange dans la CI de Github]({BASE_URL}/imgs/tutorials/2024-03-27-chromatic/ui-tests3.png) + +Le build est en orange : il n'est ni validé ni en erreur, il **attend simplement d'être review** comme indiqué dans la colone Status à côté de chacune de nos stories. Nous allons cliquer **sur le bouton bleu "Verify changes"** en haut à droite du tableau principal de la page pour pouvoir review chaque storie modifiée une par une. + +![Le build de Chromatic est orange]({BASE_URL}/imgs/tutorials/2024-03-27-chromatic/ui-tests4.png) + +Sur la nouvelle page nous avons tout en haut à gauche le nom de la première story et du composant : "Button: Primary". **En dessous nous pouvons trouver les snapshots.**. Nous avons à gauche l'état de base du composant, et **à droite le nouvel état** détecté par Chromatic... et notre bouton qui est vert fluo au lieu d'être bleu ! Pas de panique, **c'est la façon dont Chromatic indique les zones de différences** entre les deux snapshots. En haut à droite du snapshot du nouvel état se trouvent des boutons qui permettent de distinguer les zones de différence en ajoutant une ombre ou un effet stroboscopique. **En cliquant sur "Diff" vous désactiverez l'overlay vert** pour afficher le composant. + +Tout en bas de page nous retrouvons le DOM du composant qui est également affiché : il est important de noter que **Chromatic ne prend pas en compte les différences de DOM** pour déterminer si un composant a changé ou non, c'est uniquement le snapshot visuel qu'il prend en compte. Le DOM est plutôt affiché à but informatif, pour aider à débugger par exemple, mais ne compte pas pour Chromatic. Enfin tout en haut à droite nous avons des flèches pour passer entre les différents composants, **puis deux boutons, "Deny" et "Accept"** à côté desquels sont accolés leurs versions "batch" pour tout refuser ou tout accepter. + +On remarque que **le bleu du bouton est effectivement différent** et que Chromatic l'a bien repéré. On remarque aussi que modifier un seul composant a eu un impact sur des stories différentes, Header et Pages, que nous n'avons pas modifiées. C'est la force des tests de non régression visuelle : même si on ne sait pas quelles sont les impacts liés à nos modifications, **Chromatic est là pour vérifier sur chacune des stories les éventuels impacts que nous n'aurions pas envisagés.** C'est un filet de sécurité très rassurant ! + +Un par un, **nous allons accepter les nouveaux snapshots de Chromatic**. Une fois tous les snapshots acceptés Chromatic nous renvoie sur la page précédente et nous pouvons voir que **le Build est devenu vert !** Youpi ! + +![La pipeline de la MR sur Github est passée au vert]({BASE_URL}/imgs/tutorials/2024-03-27-chromatic/ui-tests5.png) + +De retour sur la PR vous verrez que **tous les checks sont passés** et que vous pouvez désormais la merger. Cliquez sur "Merge Pull Request" puis "Confirm Merge" et "Delete Branch" pour supprimer la branche devenue inutile. Rendez-vous sur la liste des commits du projet et patientez quelques instants : **les jobs devraient tous passer au vert sans intervention** de votre part ! Si vous cliquez sur "Details" à côté de "Tests UI" vous verrez qu'un nouveau build a été lancé, depuis `main`, et que vous n'avez pas eu besoin de l'approuver pour qu'il soit vert. + +![La pipeline de main sur Github est automatiquement passée au vert]({BASE_URL}/imgs/tutorials/2024-03-27-chromatic/ui-tests6.png) + +[La documentation complète sur l'utilisation de Chromatic avec les Github Actions est ici](https://www.chromatic.com/docs/github-actions/). + +### Turbosnap pour économiser des snapshots + +Actuellement lorsque le job Chromatic se lance, toutes les stories existantes vont être passées à la moulinette **pour prendre un snapshot.** Comme expliqué précédemment, chaque snapshot consomme un crédit. Vous pouvez trouver le nombre de crédit consommé dans l'interface de Chromatic dans l'onglet "Manage". + +Nous avons aussi vu qu’en réalité pour une PR **il y a deux builds qui sont lancés** : un premier au moment du push sur la branche, et un seconde au moment du merge de la branche sur la branche principale, que nous acceptons automatiquement. Existerait-il **un moyen d’économiser** un peu de snapshot ? + +**Turbosnap** arrive à la rescousse ! Il s'agit d’une feature qui **va vérifier quels sont les fichiers potentiellement modifiés** par le commit afin de ne prendre que les snapshots qui peuvent être dans son scope. Ainsi si j’ai 10 stories sur Storybook mais que je n’en modifie qu’une, alors je n’aurais qu’un snapshot de consommé au lieu de 10 pour chaque build... ou presque. Chaque snapshot évité avec Turbosnap est considéré comme un cinquième d'un snapshot. **Pour 5 snapshots évité, on a donc consommé un crédit**. + +

Note

+Petit instant bommer : avant, Turbosnap était complètement gratuit en crédit jusqu'à récemment : ce qui paraissait logique puisqu'il permettait de ne pas faire de snapshots, et donc d'économiser du temps et des ressources. C'était gagnant / gagnant ! Maintenant, même si le nouveau coût en crédit reste modéré, pour ma part la pilule a un peu de mal à passer... +
+ +![Une utilisation du meme "Pepperidge farm remembers" : "Do you remember when Turbosnap was free ? Pepperidge farm remembers"]({BASE_URL}/imgs/tutorials/2024-03-27-chromatic/turbosnap-pepperidge.jpg) + +Turbosnap va remonter le plus possible dans les utilisations des fichiers modifiés pour déterminer **quelles stories peuvent être affectées**. On peut aussi passer des arguments pour reprendre des snapshots lorsque certains fichiers qui ne sont pas directement liés aux stories sont modifiés, comme les assets avec une option `externals` à ajouter à la configuration de l'Action Github. + +On ne peut pas utiliser Turbosnap **avant d’avoir fait 10 builds validés.** Cela permet apparemment à Turbosnap de bien analyser le projet avant de commencer à exclure des stories. + +Une fois que vous aurez 10 builds Chromatic validés sur le projet, vous pourrez ajouter `onlyChanged` à la configuration des Actions Github : + +```yaml +jobs: + chromatic: + steps: + # ... + - name: Publish to Chromatic + uses: chromaui/action@latest + with: + projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }} + autoAcceptChanges: "main" + onlyChanged: true # Active Turbosnap +``` + +[La documentation complète sur Turbosnap est ici](https://www.chromatic.com/docs/setup-turbosnap/) + +## Les modes (dark/light + viewport + variables globales) + +Les snapshots pris par Chromatic ont par défaut **un viewport de 1200px** de large. Comment faire pour vérifier des rendus sur des viewports différents ? Est-ce qu’on pourrait prendre en compte d’autres éléments comme le darkmode ou la traduction ? + +C’est effectivement possible **grâce aux modes de Chromatic**. + +Nous allons ajouter une apparence en darkmode sur le bouton, et configurer la story du bouton pour que Chromatic prenne plusieurs snapshots : **en darkmode et lightmode, en 1200px et en 420px de large.** + +Nous allons commencer par revenir sur `main` et pull nos modifications, puis créer une nouvelle branche `feat/enable-modes` : + +```bash +git checkout main +git pull +git checkout -b feat/enable-modes +``` + +Pour ajouter une gestion basique des thèmes dans Storybook nous allons **installer l'addon `@storybook/addon-themes`** + +```bash +npm i -D @storybook/addon-themes +``` + +On l'ajoute ensuite **à la suite des addons** déjà installés dans `.storybook/main.ts` : + +```typescript +addons: ['@storybook/addon-themes'], +``` + +Relancez Storybook avec `npm run storybook`, vous verrez apparaître **un bouton qui permet de changer de thème dans la barre supérieure de l'interface**, tout à droite. Nous allons **modifier le CSS du bouton Primary** pour avoir un rendu différent si la classe `.dark` ajoutée par l'addon est présente. Dans le fichier `button.css` ajoutez les lignes suivantes : + +```css +.dark .storybook-button--primary { + color: black; + background-color: #add8e6; +} +``` + +Si vous changez de thème vous pourrez maintenant **voir le bouton de la story Primary changer d'apparence**. + +Nous allons maintenant créer les différents Modes utilisés par Chromatic, car pour l'instant les snapshots seraient toujours pris uniquement en version Light. + +Nous allons créer un fichier `.storybook/modes.ts` dans lequel nous allons créer une variable `allModes` : + +```typescript +export const allModes = { + light: { + theme: "light", + }, + dark: { + theme: "dark", + }, +}; +``` + +On peut décider d'utiliser ces modes sur toutes les stories ou bien sur quelques stories en particulier. Nous allons utiliser cette dernière méthode pour **prendre les différents snapshots sur les stories du bouton**. Dans le fichier `Button.stories.ts` ajoutez ces lignes dans les `parameters` de l'objet `meta` : + +```typescript +import { allModes } from './../../.storybook/modes'; +// ... +const meta = { + title: 'Example/Button', + component: Button, + parameters: { + layout: 'centered', + chromatic: { // On ajoute la configuration des modes ici + modes: { + light: allModes["light"], + dark: allModes["dark"], + }, + }, + }, + tags: ['autodocs'], + argTypes: { + backgroundColor: { control: 'color' }, + }, +} satisfies Meta; +``` + +Nous allons aussi prendre **un snapshot du Header différents viewports**. Dans `.storybook/preview.ts` ajoutez ces lignes aux `parameters` : + +```typescript +const preview = { + parameters: { + // ... + viewport: { + viewports: { + sm: { name: "Small", styles: { width: "640px", height: "900px" } }, + md: { name: "Medium", styles: { width: "768px", height: "900px" } }, + lg: { name: "Large", styles: { width: "1024px", height: "900px" } }, + }, + }, + }, +}; +``` + +En cliquant sur le bouton des viewports du menu en haut de l'interace vous avez maintenant **trois choix : Small, Medium et Large**, qui correspondent aux noms que nous venons d'ajouter. + +Dans `allModes` nous allons **ajouter des propriétés** qui référencent les viewports que nous venons d'ajouter. Voici à quoi ressemble `allModes` maintenant : + +```typescript +export const allModes = { + light: { + theme: "light", + }, + dark: { + theme: "dark", + }, + small: { + viewport: "sm" + }, + medium: { + viewport: "md" + }, + large: { + viewport: "lg" + } +}; +``` + +Ensuite nous allons **ajouter la configuration** des modes dans la `Header.stories.ts`, dans `meta` : + +```typescript +parameters: { + // More on how to position stories at: https://storybook.js.org/docs/configure/story-layout + layout: 'fullscreen', + chromatic: { + modes: { + small: allModes["small"], + medium: allModes["medium"], + large: allModes["large"], + }, + }, +}, +``` + +Et voilà ! Comme tout à l'heure on ajoute les modifications dans un commit, on pousse le tout, on crée la PR puis on va regarder ce que ça donne sur le build. + +Pour le bouton **chaque story a deux nouveaux snapshots** : en effet on a un nouveau snapshot à valider **pour le mode dark, mais aussi pour le mode light !** On voit aussi que pour la story Warning on a modifié la couleur du texte du bouton. Pour les stories du Header nous avons maintenant **trois variations pour les trois viewports que nous avons ajoutés.** + +Il aurait été également possible de croiser les thèmes et les viewports ! + +

Note

+Ajouter des modes de thème ou viewport consomme plus de snapshots : c'est exponentiel. Faites attention à bien cibler quels rendus sont important pour éviter de consommer trop de crédit. +
+ +

Info

+Le navigateur par défaut de la version gratuite est Chrome, mais il est possible de tester différents navigateurs avec les versions payantes de Chromatic. Attention encore une fois, ajouter un nouveau navigateur revient à multiplier tous les snapshots déjà présents et donc là aussi à augmenter sa consommation de crédit. +
+ +[Voir la documentation complète sur les Modes](https://www.chromatic.com/docs/modes/) + +Maintenant que nous avons modifié nos stories pour implémenter différents tests de non régression visuelle, nous allons pouvoir passer à la dernière partie de ce tuto, et parler des autres types de tests que nous pouvons faire sur Chromatic ! diff --git a/_tutorials/fr/2024-03-27-chromatic/steps/conclusion.md b/_tutorials/fr/2024-03-27-chromatic/steps/conclusion.md new file mode 100644 index 000000000..8a66ab91b --- /dev/null +++ b/_tutorials/fr/2024-03-27-chromatic/steps/conclusion.md @@ -0,0 +1,13 @@ +--- +contentType: tutorial-step +tutorial: chromatic +slug: conclusion +title: Conclusion +--- + +## Conclusion + +Eh bien ce tuto était un gros morceau ! + +On a installé un projet avec Storybook et Chromatic, configuré et installé Chromatic en CI, réalisé toutes sortes de tests de non régression visuelle et d'interactions... J'espère que toutes ces étapes vous ont permis de mieux comprendre les avantages (et les défauts !) de Chromatic, et comment cet outil peut vous aider à être plus confiant à chaque nouvelle feature implémentée sur vos projets. + diff --git a/_tutorials/fr/2024-03-27-chromatic/steps/initialization.md b/_tutorials/fr/2024-03-27-chromatic/steps/initialization.md new file mode 100644 index 000000000..3cb976742 --- /dev/null +++ b/_tutorials/fr/2024-03-27-chromatic/steps/initialization.md @@ -0,0 +1,45 @@ +--- +contentType: tutorial-step +tutorial: chromatic +slug: initialization +title: Initialisation du projet +--- + +## Initialisation du projet (Vite + React + Storybook) + +Comme il est probable que vous utilisiez React, nous allons faire un nouveau projet en React appelé "chromatic-tuto-elevenlabs" sur lequel nous allons installer Storybook et React. Storybook comprendra automatiquement qu’il est sur un projet React. + +Sur un terminal, placez-vous dans le dossier dans lequel vous souhaitez **créer le projet**, puis lancez ces commandes : + +```bash +npm create vite@latest chromatic-tuto-elevenlabs --template react-ts +``` + +Acceptez l’installation de `create-vite` puis sélectionnez en Framework `React` et en variant `Typescript` (ou `Javascript` si vous êtes plus à l’aise, ça ne change pas grand chose dans le cadre de ce tuto mais il faudra adapter les extraits de code en retirant les types). **Installez le projet** sans le lancer : + +```bash +cd chromatic-tuto-elevenlabs +npm install +``` + +Avant de lancer le projet nous allons **installer Storybook**. Comme dit précédemment, Storybook va automatiquement déterminer dans quel environnement il est installé. + +

Important

+Une nouvelle version majeure de Storybook, la version 8, est sortie récement au moment où j'écris ce tuto. Pour être sûrs de ne pas se retrouver avec des bugs dûs à la nouveauté de cette version, je vous propose d'installer la dernière version 7 sur laquelle je suis sûre que tout fonctionne bien. +
+ +Lancez cette commande, puis acceptez l’installation du package `storybook`, puis un peu plus tard dans l’installation, installez le plugin ESLint recommandé si vous le souhaitez. + +```bash +npx storybook@7 init +``` + +À la fin de l’installation un onglet s’ouvre par défaut à l’adresse `localhost:6006`. Si vous avez besoin de relancer Storybook plus tard, faites cette commande : + +```bash +npm run storybook +``` + +Si vous n’avez pas l’habitude de Storybook je vous conseille de suivre le tour proposé par Storybook au premier lancement du projet (préparez-vous à recevoir une myriade de confettis colorés). + +Nous avons donc pour l’instant 3 stories : un bouton, un header et une page complète. Nous allons utiliser dans ce tuto le composant le plus simple : le bouton. Mais accrochez-vous parce qu’il va falloir **faire un peu de CI**... diff --git a/_tutorials/fr/2024-03-27-chromatic/steps/introduction.md b/_tutorials/fr/2024-03-27-chromatic/steps/introduction.md new file mode 100644 index 000000000..ba0202b8d --- /dev/null +++ b/_tutorials/fr/2024-03-27-chromatic/steps/introduction.md @@ -0,0 +1,35 @@ +--- +contentType: tutorial-step +tutorial: chromatic +slug: introduction +title: Introduction +--- + +## Qu'allons-nous faire ? + +Storybook se définit comme un "workshop" permettant de créer des composants et des pages en isolation. Concrètement, **c’est une interface sur laquelle on va pouvoir jouer avec les différents états d’un composant** pour vérifier s’il correspond bien au design attendu, trouver de la documentation et récupérer les props à utiliser pour différentes implémentations. C’est un outil qui est de plus en plus utilisé lors de la **création de Design Systems**, et qui peut être utilisé avec de plus en plus de frameworks bien qu’il soit initialement fait pour React. L’utilisation de Storybook peut être améliorée avec des plugins. + +Mais si on passe nos composants sur Storybook, **est-ce qu’il est possible de les y tester aussi directement ? La réponse est oui !** Un des outils à notre disposition pour cela, **c’est Chromatic**. + +Chromatic est développé par la même équipe que Storybook (d’ailleurs on peut remarquer que la chaîne officielle de Storybook sur Youtube s’est renommée Chromatic !). C’est un outil qu’on utilise dans la CI, qui permet de faire des **tests de non régression visuelle (mais pas que !)** sur les stories créées sur Storybook. Chromatic est un outil payant avec une version gratuite que nous allons utiliser et qui va nous permettre d'effectuer 5000 snapshots, ce qui est largement suffisant pour les besoins de ce tuto ! + +

Note

+Un plugin est actuellement en bêta au moment où j'écris ce tutoriel pour la version 8 de Storybook pour permettre de lancer Chromatic directement en local sans passer par la CI, mais pour l’instant nous allons passer par la CI uniquement. +
+ +Les tests de non régression visuelle sont parfaits dans le cas d’un Design System car ils permettent de **vérifier au pixel près si les modifications sur un composant n’affectent pas d’autres composants**, ce qui peut être très compliqué à remarquer sur des projets complexes. Dans ce tuto nous allons voir : + +- comment **installer Storybook et Chromatic** sur un nouveau projet Vite + React +- comment **automatiser** Chromatic en CI +- comment **créer et tester visuellement** sur Chromatic un composant simple +- comment faire des **tests d’interaction** et les lancer avec Chromatic + +## Prérequis + +- Avoir NodeJs en version 16 ou plus installé sur votre machine (`node -v` pour vérifier) +- Avoir un compte Github + +

Note

+Avant de commencer je voudrais quand même vous avertir : Chromatic est un outil très pratique, qui n'a pas vraiment de concurrent aussi facile d'utilisation actuellement. À partir du moment où on commence à ajouter des tests de non régression visuelle il devient difficile de s'en passer pour le projet. Il est donc probable que votre projet devienne dépendant de Chromatic, et il est déjà arrivé qu'ils décident d'augmenter le tarif de certains services. Comme il n'y a actuellement pas de réel concurrent, utiliser Chromatic c'est malheureusement accepter cette dépendance. +
+ diff --git a/_tutorials/fr/2024-03-27-chromatic/steps/other-tests.md b/_tutorials/fr/2024-03-27-chromatic/steps/other-tests.md new file mode 100644 index 000000000..e1ba44c4c --- /dev/null +++ b/_tutorials/fr/2024-03-27-chromatic/steps/other-tests.md @@ -0,0 +1,247 @@ +--- +contentType: tutorial-step +tutorial: chromatic +slug: other-tests +title: Les autres tests qu'on peut lancer sur Chromatic +--- + +## Tests d'interactivité avec Play + +Pour l’instant nous avons vu qu’avec Chromatic on pouvait lancer des tests de non régression visuelle. On peut également lancer des **tests d’interaction de composant !** On pourra tester si les comportements du composant lorsque l’utilisateur interagit avec correspond bien à ce que l’on souhaite. + +Ces tests sont réalisés dans **l’onglet Interactions** des stories. Pour ajouter une interaction à une story il faut créer une fonction `play`. À l’intérieur on va pouvoir utiliser les utilitaires fournis par `@storybook/tests` qui regroupent **des utilitaires de Jest et de Testing-library**. On pourra utiliser `step` pour diviser les tests en sous-parties nommées. + +Chromatic n’est pas nécessaire pour lancer les tests d’interactivité. Il y a d’autres façons de lancer ces tests de façon automatique, notamment avec `@storybook/test-runner`. Je parle de ces tests ici car ils sont **automatiquement lancés dans Chromatic** avant qu'il prenne le snapshot, donc c’est d’une pierre deux coups. + +Nous allons voir dans quels cas concrets on peut utiliser des tests d'interactivité. + +### Création de notre composant de test + +Nous allons réaliser **une modale très basique**, un composant avec un `dialog` qui s'ouvre et se ferme. + +Tout d'abord nous allons nous mettre sur une nouvelle branche, `feat/enable-interactions`. + +```bash +git checkout main +git checkout -b feat/enable-interactions +``` + +Dans `src/stories`, créez un fichier `Modal.tsx`. Copiez et collez à l'intérieur de ce fichier le code suivant : + +```tsx +import { useRef } from 'react'; +import { Button } from './Button'; + +export const Modal = ({onOpenModal}: {onOpenModal: () => void}) => { + const dialogElement = useRef(null); + const openModal = () => { + dialogElement?.current?.showModal(); + onOpenModal(); + } + const closeModal = () => dialogElement?.current?.close(); + + return( + <> + + +

Je suis une modale !

+ +