Tests de composants : suivre leur santé avec Vitest
Associez Vitest Browser Mode, Storybook et Kinora pour suivre la santé de vos composants, repérer les régressions et comprendre les échecs. Voici comment.
Suivre la santé de vos composants avec Vitest et Storybook
Un pipeline peut afficher 3 tests en échec sur 400 et vous laisser avec la mauvaise question : « Quels tests ont échoué ? » Dans une équipe qui maintient un design system, la vraie question ressemble plutôt à : « Quels composants sont en mauvais état, et depuis quand ? »
Exécuter des tests de composants dans un navigateur aide vraiment : l'interface se comporte comme en conditions d'usage. Avec Vitest Browser Mode, vous lancez ces tests dans Chromium via Playwright, et l'extension Vitest de Storybook convertit les stories en tests. Le souci, c'est qu'une exécution isolée ne conserve pas l'historique. Et elle ne vous dit pas si vous avez une régression récente... ou juste un test instable qui échoue depuis plusieurs jours.
Un suivi organisé par story complète les rapports de CI. Dans cet article, on voit comment envoyer les résultats Vitest et Storybook vers Kinora, suivre l'état des composants dans le temps et retrouver le contexte quand quelque chose casse. On parlera aussi des limites du dispositif, et des cas où il vaut mieux garder des tests unitaires classiques.
Pourquoi raisonner par composant plutôt que par test
Un outil de test vous renvoie les résultats à l'endroit où il sait les exécuter : fichier, suite ou test individuel. Utile pour lancer les vérifications et décortiquer un échec. Moins pratique quand on veut comprendre la santé globale d'un design system.
Un composant peut être couvert par plusieurs tests (rendu, interaction, accessibilité, comparaison visuelle). À l'inverse, un fichier de test peut toucher plusieurs composants. Donc quand ça échoue, il faut souvent faire le lien soi-même entre le nom du test et le bout d'UI concerné, puis remonter dans le temps pour savoir si c'est nouveau.
En pratique, ça prend du temps. Et ça dépend beaucoup de la qualité des noms de tests, plus de votre discipline à conserver les rapports de CI. Une liste de rouge ne dit pas, toute seule, si le composant Select est devenu instable ou si une modification récente a cassé le bouton désactivé.
La story comme unité de suivi
Storybook parle déjà le langage de l'équipe : la story. Button/Primary ou Dialog/With long content décrivent des états concrets, compréhensibles par les développeurs, les designers et les responsables produit.
Le principe : regrouper les résultats par story, puis répondre à trois questions assez simples :
- Quel est son dernier état connu ?
- Comment cet état a évolué au fil des exécutions ?
- Quels tests sont liés à cette story ?
Ce changement ne « rend pas les tests meilleurs ». Il rend juste leurs résultats exploitables à l'échelle du produit. Et quand vous avez des centaines de composants et de variantes, la différence est énorme : on passe d'un empilement de logs à une vue de la santé du système.
Et non, la story ne remplace pas le test pour diagnostiquer. Le test reste indispensable pour comprendre la défaillance. La story devient l'unité de lecture et de suivi. Les deux niveaux se complètent : ils ne sont pas interchangeables.
Envoyer les résultats Vitest et Storybook à Kinora
Kinora, à la base pensé pour les rapports Playwright, peut recevoir des résultats Vitest via un rapporteur dédié. Le rapporteur s'ajoute au rapporteur standard de Vitest : vous gardez la sortie habituelle dans le terminal, et vous envoyez aussi une copie au service.
Installez d'abord le paquet de développement :
pnpm add -D @kinora/vitest-reporterPuis ajoutez le rapporteur à la configuration Vitest :
import { defineConfig } from 'vitest/config'
export default defineConfig({
test: {
reporters: [
'default',
['@kinora/vitest-reporter', {
project: { slug: 'design-system' },
}],
],
},
})
L'envoi nécessite un jeton d'API défini dans l'environnement d'exécution :
KINORA_TOKEN=<token> npx vitest runEn CI, ce jeton doit rester un secret (dans la plateforme CI), pas une valeur commitée dans le dépôt. Le slug du projet sert à rattacher l'exécution au bon espace. Adaptez-le à votre organisation.
Ce qui est envoyé par défaut
Le rapporteur transmet les tests exécutés dans un navigateur, par exemple ceux de Vitest Browser Mode. Les tests unitaires lancés dans Node.js sont ignorés par défaut. C'est souvent un choix pragmatique : beaucoup de tests unitaires sont rapides et déterministes, mais ils ne disent pas grand-chose sur l'état visuel ou interactif des composants.
Si vous voulez inclure aussi ces tests, vous pouvez activer include: 'all'. Faites-le seulement si ces tests couvrent vraiment une partie importante de la logique des composants. Sinon, vous envoyez juste plus de données sans forcément gagner en diagnostic.
Avec l'extension Vitest de Storybook, chaque story est déjà représentée par un test. Résultat : pas besoin d'ajouter une instrumentation supplémentaire pour associer le test à la story qu'il rend. Le rapporteur enregistre l'association sous une forme du style Component/Story.
Dernier point opérationnel : un souci de connexion au service de rapport ne doit pas faire échouer la suite de tests. Les tests gardent leur comportement normal (ils réussissent ou échouent selon leurs assertions). Ça évite qu'un tableau de bord indisponible bloque la livraison. Par contre, si votre équipe dépend de la présence des rapports dans Kinora, surveillez l'envoi séparément.
Pour aller plus loin, voir la documentation de Vitest et la documentation de l'extension Vitest de Storybook.
Lire l'historique et diagnostiquer les échecs
Après une exécution qui contient des stories, Kinora crée une page « Components ». Les stories y sont regroupées par composant. Pour chaque entrée, l'équipe voit son dernier état, une chronologie sur les 20 dernières exécutions, et les tests associés.
Quand une story est couverte par plusieurs tests, son état reflète le résultat le plus défavorable. Concrètement : si le test de rendu passe mais que le test d'interaction échoue, la story apparaît en échec. C'est cohérent pour une lecture « santé » : un composant ne peut pas être totalement sain si une de ses vérifications importantes échoue.
Distinguer régression et instabilité
La chronologie change la donne. Une story qui est rouge aujourd'hui mais verte sur les 19 exécutions précédentes ressemble clairement à une régression. Dans ce cas, le changement introduit dans la dernière branche devient une piste sérieuse.
À l'inverse, une story qui passe puis échoue régulièrement est souvent instable. Là, la dernière modification n'est pas forcément responsable. Ça ne prouve pas la cause, mais ça évite de traiter chaque échec comme « nouveau ». Et ça oriente le travail : corriger le code pour une régression, ou stabiliser l'environnement/le test pour un bug intermittent.
Au final, l'historique réduit le nombre d'allers-retours dans les journaux CI pour chaque première analyse. Il ne les remplace pas : dès qu'il faut comprendre exactement ce qui s'est passé, il faut revenir aux détails du test.
Conserver les traces Playwright en cas d'échec
Pour diagnostiquer une interaction côté navigateur, une trace Playwright aide beaucoup : elle montre le contexte d'exécution. Avec le fournisseur Playwright de Vitest Browser Mode, vous pouvez conserver une trace uniquement quand un test échoue :
import { playwright } from '@vitest/browser-playwright'
import { defineConfig } from 'vitest/config'
export default defineConfig({
test: {
browser: {
enabled: true,
provider: playwright(),
instances: [{ browser: 'chromium' }],
trace: 'retain-on-failure',
},
},
})
Le rapporteur peut alors envoyer l'archive trace.zip du test en échec. Kinora l'ouvre dans un lecteur intégré : on y trouve notamment des instantanés du DOM, la console et les échanges réseau. L'intérêt est simple : le développeur peut inspecter sans télécharger manuellement un artefact CI.
Évidemment, une trace ajoute du volume et peut contenir des informations sensibles selon l'application et les données de test. Il faut donc vérifier ce qui est enregistré et appliquer les règles de conservation adaptées au projet. Garder la trace seulement en cas d'échec limite généralement le bruit et le stockage.
Comparer les captures visuelles
Les assertions visuelles sont pratiques quand vous voulez du contexte. Quand un toMatchScreenshot échoue, vous pouvez envoyer la référence, la capture réelle et l'image de différence afin de les comparer dans le rapport.
Ça permet de repérer vite un changement subtil : quelques pixels de décalage, un espacement modifié, une taille qui bouge. Mais une différence visuelle n'est pas automatiquement un défaut. Polices, animations, taille de fenêtre et environnement d'exécution peuvent aussi provoquer des écarts « normaux » (ou au moins non problématiques). Gardez des conditions de capture cohérentes, et regardez la différence avant de décider de mettre à jour la référence.
Limites et choix d'architecture
Le suivi par story fonctionne bien si l'association entre le test et le composant reste assez claire. Une même story peut être rendue par plusieurs tests : ce n'est pas un problème, puisque Kinora regroupe. En revanche, si un test rend plusieurs stories, vous introduisez une ambiguïté.
Kinora sait quelles stories le test a montées, mais ne sait pas toujours laquelle a déclenché l'échec. Dans ce cas, il peut marquer toutes les stories montées par le test comme défaillantes. Pour une attribution précise, la règle la plus simple est : tester une story par test quand c'est possible.
Cette règle n'est pas absolue. Regrouper plusieurs scénarios peut être acceptable si le test vérifie volontairement un parcours combiné, et si l'équipe accepte une attribution moins fine. Comme souvent, la bonne granularité dépend surtout de l'usage du rapport : plus vous voulez localiser rapidement un défaut, plus les tests doivent isoler les composants.
Traces des tests Storybook
Les fonctions play de Storybook ne sont pas des actions Playwright. Une trace « test Storybook » peut montrer la story rendue, mais pas forcément détailler chaque étape d'interaction comme le ferait un test Playwright qui pilote explicitement le navigateur.
Si vous avez besoin d'un diagnostic pas à pas des interactions, vérifiez que le type de test et le mode de trace répondent à votre besoin. Ne partez pas du principe qu'un test exécuté dans Chromium fournit automatiquement le même niveau d'inspection qu'un scénario Playwright.
Et si vous utilisez les tests de composants Playwright ?
Vous n'êtes pas obligé d'adopter Vitest Browser Mode. Si vos tests de composants utilisent déjà mount de Playwright, vous pouvez envoyer les résultats comme des tests Playwright classiques. Il reste à enregistrer quelle story a été montée, pour la rattacher à la bonne entrée dans la page « Components » :
import { expect, test } from '@kinora/reporter/ct'
test('le bouton désactivé est bien désactivé', async ({ mount }) => {
const component = await mount('Button/Disabled')
await expect(component.getByRole('button')).toBeDisabled()
})
Les stories issues des deux approches peuvent ensuite apparaître dans la même page. C'est utile si une équipe utilise plusieurs outils en parallèle ou migre progressivement.
Et si vous voulez aller plus loin : les mêmes données peuvent aussi être consultées par un agent via le serveur MCP de Kinora. Son outil component_health peut répondre à des questions comme « quelles stories de Dialog échouent ou sont instables, et quels tests les couvrent ? ». C'est un meilleur point de départ qu'un journal brut - à condition de vérifier les conclusions et de ne donner à l'agent que les données nécessaires.
Conclusion : faire du suivi un outil de décision
Vitest dans le navigateur et les stories Storybook donnent déjà une bonne couverture de l'interface. Ce qui manque souvent, c'est une mémoire exploitable : l'historique par composant, la distinction entre régression et instabilité, et un accès direct au contexte quand ça casse.
Avec un rapporteur Vitest, vous obtenez cette vue sans remplacer vos tests, vos logs CI, ni vos choix d'outillage. La valeur dépend surtout de la qualité des associations entre tests et stories, de la granularité des scénarios, et de la discipline sur les captures et les traces.
Si vous faites déjà tourner Vitest dans un navigateur ou si vous exécutez les tests Storybook en intégration continue, commencez par un pilote. Vérifiez que les échecs sont attribués correctement, que l'historique aide vraiment l'équipe, et que la collecte de traces reste maîtrisée. Ensuite seulement, étendez le dispositif à tout le design system. Vous pouvez aussi consulter l'article source consacré à Vitest, Storybook et Kinora.