roadwave/docs/adr/007-tests-bdd.md

# ADR-007 : Tests et Spécifications Exécutables

**Statut** : Accepté
**Date** : 2025-01-17

## Contexte

RoadWave nécessite une documentation des use cases qui soit à la fois lisible par tous les stakeholders et vérifiable automatiquement. Les scénarios utilisateurs (touriste, routier, commerçant) doivent être validés en continu.

## Décision

**Gherkin** pour les spécifications avec **Godog** comme runner de tests.

## Alternatives considérées

| Option | Lisibilité | Intégration Go | Maintenance |
|--------|------------|----------------|-------------|
| **Gherkin + Godog** | Excellente | Native | Faible |
| Gauge (Markdown) | Bonne | Plugin | Moyenne |
| Tests Go natifs | Faible (devs only) | Native | Faible |
| Concordion | Bonne | Java-centric | Élevée |

## Justification

- **Living Documentation** : Les fichiers `.feature` servent de documentation ET de tests
- **Accessibilité** : Syntaxe Given/When/Then lisible par PO, devs, testeurs
- **Cohérence stack** : Godog est le standard BDD pour Go
- **CI/CD** : Intégration simple dans les pipelines

## Structure

Les features BDD sont organisées en **3 catégories** selon la couche testée :

```
features/
├── api/                      # Tests de contrats API (Backend)
│   ├── authentication/       # REST endpoints, validation email, 2FA
│   ├── recommendation/       # Algorithm backend, scoring GPS
│   ├── rgpd-compliance/      # GDPR API (delete, export, consent)
│   ├── content-creation/     # Upload, encoding, validation API
│   ├── moderation/           # Moderation workflow API
│   ├── monetisation/         # Payments, KYC, payouts API
│   ├── premium/              # Subscription API
│   ├── radio-live/           # Live streaming backend
│   └── publicites/           # Ads API, budget, metrics
│
├── ui/                       # Tests d'interface utilisateur (Mobile)
│   ├── audio-guides/         # Audio player UI, modes (piéton, vélo)
│   ├── navigation/           # Steering wheel, voice commands, UI
│   ├── interest-gauges/      # Gauge visualization, progression
│   ├── mode-offline/         # Download UI, sync status
│   ├── partage/              # Share dialog
│   ├── profil/               # Creator profile screen
│   └── recherche/            # Search bar, filters UI
│
└── e2e/                      # Tests end-to-end (Backend + Mobile)
    ├── abonnements/          # Full subscription flow (Mangopay + Zitadel + UI)
    └── error-handling/       # Network errors, GPS disabled (backend + mobile)
```

### Convention de Catégorisation

#### `/features/api/` - Tests de contrats API (Backend)

**Objectif** : Tester les endpoints REST (requêtes HTTP, codes de statut, validation)

**Exécuté par** : Backend (Godog + step definitions Go dans `/backend/tests/bdd/`)

**Exemples de scénarios** :
- `POST /api/v1/auth/register` avec email invalide → retourne 400
- `GET /api/v1/contents/nearby` avec rayon 500m → retourne POI triés par distance
- `DELETE /api/v1/user/account` → supprime données RGPD conformément

**Caractéristiques** :
- Focus sur la **logique métier backend** (algorithme, validation, persistance)
- Pas d'interface utilisateur
- Testable via requêtes HTTP directes

---

#### `/features/ui/` - Tests d'interface utilisateur (Mobile)

**Objectif** : Tester les interactions utilisateur (tap, scroll, navigation, widgets)

**Exécuté par** : Mobile (Flutter `integration_test` + step definitions Dart dans `/mobile/tests/bdd/`)

**Exemples de scénarios** :
- Cliquer sur "Lecture" → widget audio player s'affiche avec progress bar
- Mode piéton activé → carte interactive affichée + bouton "Télécharger zone"
- Scroll dans liste podcasts → lazy loading déclenche pagination

**Caractéristiques** :
- Focus sur l'**expérience utilisateur mobile**
- Validation visuelle (widgets, animations, navigation)
- Mock du backend si nécessaire (tests UI isolés)

---

#### `/features/e2e/` - Tests end-to-end (Backend + Mobile)

**Objectif** : Tester les parcours complets impliquant plusieurs composants

**Exécuté par** : Backend **ET** Mobile ensemble

**Exemples de scénarios** :
- Abonnement Premium : Formulaire mobile → API Zitadel → API RoadWave → Mangopay → Confirmation UI
- Erreur réseau : Perte connexion pendant streaming → Fallback mode offline → Reprise auto après reconnexion
- Notification géolocalisée : GPS détecte POI → Backend calcule recommandation → Push notification → Ouverture app → Lecture audio

**Caractéristiques** :
- Tests **cross-composants** (intégration complète)
- Implique souvent des **services tiers** (Zitadel, Mangopay, Firebase)
- Validation du **parcours utilisateur de bout en bout**

---

### Implémentation Step Definitions

**Backend** : `/backend/tests/bdd/`
- Step definitions Go pour features `api/` et `e2e/`
- Utilise `godog` et packages backend (`service`, `repository`)

**Mobile** : `/mobile/tests/bdd/`
- Step definitions Dart pour features `ui/` et `e2e/`
- Utilise Flutter `integration_test` framework

**Note** : Les step definitions ne sont pas encore implémentées (répertoires avec `.gitkeep` seulement). Cette organisation prépare la structure pour l'implémentation future.

---

## Exemple

```gherkin
Feature: Recommandation géolocalisée

  Scenario: Touriste près d'un monument
    Given un utilisateur avec l'intérêt "tourisme" à 80%
    And une position GPS à 100m de la Tour Eiffel
    When le système calcule les recommandations
    Then l'audio guide "Histoire de la Tour Eiffel" est en première position
```

## Conséquences

- Dépendance : `github.com/cucumber/godog` (MIT)
- Les use cases du README doivent être traduits en `.feature`
- CI exécute `godog run` avant chaque merge

**Librairies** : Voir [ADR-020](020-librairies-go.md) pour analyse complète des frameworks BDD