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
    • CI_TEST_SECRET : Secret partagé entre SST et GitHub Actions pour les endpoints de smoke tests

​
🔧 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
CI_TEST_SECRET=votre_secret_ici
Pour le secret SST (necessaire pour le endpoint /tests/check-exchanges) : 
npx sst secrets set CI_TEST_SECRET "votre_secret_ici" --stage prod

​
2. Configuration Vitest

Le fichier vitest.config.ts est configure pour generer des rapports JSON. En local, les rapports sont ecrits dans docs/reports/vitest/.

​
3. Workflow GitHub Actions

Le pipeline CI (ci.yml) sur master suit l’ordre : Release -> Deploy -> Smoke Tests. Les smoke tests post-deploy appellent les endpoints /tests/* sur la prod deployee et generent les badges a partir des reponses. Le workflow tests.yml (branches main/develop) execute Vitest en CI pour les PR.

​
📝 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

​
Pipeline CI sur master (ci.yml)

  1. Semantic Release : versioning automatique
  2. Deploy : sst deploy --stage prod + Checkly deploy
  3. Smoke Tests post-deploy :
    • Appel de GET https://api.poihunter.com/tests/check-exchanges (protege par Bearer token CI_TEST_SECRET)
    • Le rapport JSON est sauvegarde dans docs/reports/vitest/specs/
    • Les badges sont generes par npm run test:badges
    • Les specs et rapports sont commites automatiquement

​
Pipeline sur branches (tests.yml)

  1. Les tests Vitest sont executes en CI
  2. Les badges sont generes et commites

​
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 les rapports dans docs/reports/vitest/specs/ existent
  3. Pour le pipeline master, vérifiez que CI_TEST_SECRET est identique dans les secrets GitHub et dans SST (npx sst secrets list --stage prod)
  4. 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.