35aaa105d0
- Ajouter ADR-018 (librairies Go) dans TECHNICAL.md - Transformer Shared en menu dépliable dans mkdocs (cohérence avec autres domaines) - Corriger listes markdown (ajout lignes vides avant listes) - Corriger line breaks dans génération BDD (étapes "Et" sur nouvelles lignes) - Ajouter script fix-markdown-lists.sh pour corrections futures Impacte 86 fichiers de documentation et 164 fichiers BDD générés.
158 lines
5.9 KiB
Markdown
158 lines
5.9 KiB
Markdown
# 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-018](018-librairies-go.md) pour analyse complète des frameworks BDD
|