Skip to main content

​
Comment intégrer les Badges de Tests

Ce guide explique comment configurer et utiliser le système de badges automatiques pour les tests dans les spécifications.

​
🎯 Vue d’ensemble

Le système de badges permet d’afficher automatiquement le statut des tests (Checkly pour le frontend, Vitest pour le backend) directement dans les fichiers de spécification. Les badges sont mis à jour automatiquement après chaque exécution des tests.

​
📋 Prérequis

  • Node.js 20+
  • Variables d’environnement configurées :
    • CHECKLY_API_KEY : Clé API Checkly
    • CHECKLY_ACCOUNT_ID : ID du compte Checkly

​
🔧 Configuration

​
1. Variables d’Environnement

Ajoutez les variables d’environnement dans votre .env ou dans les secrets GitHub Actions : 
CHECKLY_API_KEY=cu_votre_token_ici
CHECKLY_ACCOUNT_ID=votre_account_id

​
2. Configuration Vitest

Le fichier vitest.config.ts est déjà configuré pour générer des rapports JSON dans reports/vitest/results.json.

​
3. Workflow GitHub Actions

Le workflow .github/workflows/tests.yml est configuré pour :
  1. Exécuter les tests backend (Vitest)
  2. Exécuter les tests frontend (Playwright)
  3. Générer les badges automatiquement
  4. Commiter les badges mis à jour

​
📝 Utilisation du Template

​
Créer une Nouvelle Spécification

  1. Copiez le template depuis docs/templates/spec-template.md
  2. Placez-le dans docs/specifications/
  3. Remplissez les sections avec votre contenu
  4. Les badges seront générés automatiquement lors de la prochaine exécution des tests

​
Structure du Template

Le template inclut une section de badges qui sera automatiquement mise à jour : 
## 📊 Statut des Tests

### Tests Frontend (Checkly)
![checkly-frontend passing](https://img.shields.io/badge/checkly-frontend-passing-brightgreen)

### Tests Backend (Vitest)
![vitest-backend passing](https://img.shields.io/badge/vitest-backend-passing-brightgreen)

​
🚀 Génération Manuelle des Badges

Pour générer les badges manuellement : 
# Générer les rapports de tests d'abord
npm run test -- --reporter=json --outputFile=reports/vitest/results.json

# Puis générer les badges
npm run test:badges
Ou en une seule commande : 
npm run test:badges:generate

​
🔄 Workflow Automatique

​
Après un Commit

  1. Le workflow GitHub Actions tests.yml se déclenche
  2. Les tests backend (Vitest) sont exécutés
  3. Les tests frontend (Playwright) sont exécutés
  4. Les résultats Checkly sont récupérés via l’API
  5. Les badges sont générés et mis à jour dans les spécifications
  6. Les changements sont commités automatiquement (si push sur master/main)

​
Mapping Tests ↔ Spécifications

Le script generate-test-badges.js associe automatiquement les tests aux spécifications en se basant sur :
  • Checkly : Le nom du check Checkly doit contenir le nom de la spécification (ou vice versa)
  • Vitest : Le chemin du fichier de test doit correspondre au nom de la spécification
Exemple :
  • Spécification : docs/specifications/swing-position-workflow.md
  • Test Checkly : positions-filters → sera associé si le nom contient “position”
  • Test Vitest : packages/functions/src/tests/positions/swingPositionService.test.ts → sera associé car contient “position”

​
📊 Format des Badges

Les badges utilisent Shields.io avec les couleurs suivantes :
  • 🟢 brightgreen : Tous les tests passent
  • 🔴 red : Au moins un test échoue
  • ⚪ lightgrey : Aucun test trouvé

​
🧪 Tests

​
Tests Frontend (Checkly)

Les tests frontend sont exécutés via Checkly et surveillent l’expérience utilisateur en production. Fichiers de tests : features/[nom-du-test].spec.ts Configuration Checkly : 
// @checkly frequency: 10min
// @checkly locations: paris, new-york
// @checkly alertChannels: linear
// @checkly tags: production, [tag]

​
Tests Backend (Vitest)

Les tests backend sont exécutés via Vitest et valident la logique métier. Fichiers de tests : packages/functions/src/tests/[module]/[nom-du-test].test.ts Exécution : 
npm run test

​
🔍 Dépannage

​
Les badges ne se mettent pas à jour

  1. Vérifiez que les variables d’environnement Checkly sont définies
  2. Vérifiez que le fichier reports/vitest/results.json existe après l’exécution des tests
  3. Vérifiez les logs du workflow GitHub Actions

​
Les badges affichent “no-tests”

Cela signifie qu’aucun test n’a été trouvé pour cette spécification. Vérifiez :
  1. Que les noms des tests correspondent au nom de la spécification
  2. Que les fichiers de tests existent et sont correctement nommés
  3. Que les tests sont bien exécutés

​
Erreur lors de la récupération Checkly

Si l’API Checkly retourne une erreur :
  1. Vérifiez que CHECKLY_API_KEY est valide
  2. Vérifiez que CHECKLY_ACCOUNT_ID est correct
  3. Vérifiez que les checks Checkly sont bien déployés

​
📚 Références

​
📖 Exemple Concret

Voici un exemple complet d’une spécification avec badges de tests :

​
Exemple : Badges de tests

​
📊 Statut des Tests

Tests Frontend (Checkly) checkly-frontend no-tests Tests Backend (Vitest) vitest-backend passing

​
🎯 Objectif

Cet exemple sert de validation “end-to-end” pour :
  • le lien Spécification ↔ Tests
  • la génération du rapport Vitest JSON (reports/vitest/results.json)
  • la mise à jour automatique des badges dans les specs

​
🧪 Tests associés

  • Frontend (Playwright / Checkly) : features/test-badges-example.spec.ts
  • Backend (Vitest) : packages/functions/src/tests/specs/test-badges-example.test.ts

​
✅ Critères d’acceptation

  • Le test frontend passe et peut être déployé/surveillé via Checkly.
  • Le test backend passe via Vitest.
  • Après exécution du job CI, la section “Statut des Tests” est mise à jour automatiquement dans ce fichier.