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

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-018 pour analyse complète des frameworks BDD