> ## Documentation Index
> Fetch the complete documentation index at: https://docs.poihunter.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Comment intégrer les Badges de Tests ?

> Guide pour configurer et utiliser les badges de tests automatiques dans les spécifications

# 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 24+ (LTS)
* 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 :

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
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`) :

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
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 :

```markdown theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
## 📊 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 :

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
# 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 :

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
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](https://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** :

```typescript theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
// @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** :

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
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

* [Template de spécification](../templates/spec-template.md)
* [Documentation Checkly](https://www.checklyhq.com/docs)
* [Documentation Vitest](https://vitest.dev/)
* [Shields.io Badges](https://shields.io/)

## 📖 Exemple Concret

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

### Exemple : Badges de tests

{/* Ne pas modifier manuellement, ils sont mis à jour automatiquement après chaque commit */}

#### 📊 Statut des Tests

**Tests Frontend (Checkly)**
![checkly-frontend no-tests](https://img.shields.io/badge/checkly-frontend-no-tests-lightgrey)

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

#### 🎯 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.