# TEST_ENVIRONMENT.md — Expria Frontend

> **Document de référence — Version 1.0**
> Ce document décrit comment configurer et utiliser l'environnement de test frontend.
> Complément au `TEST_ENVIRONMENT.md` backend (qui décrit la base de données Supabase et les comptes de test).

---

## 1. Principe

L'environnement de test frontend permet de faire tourner le code React localement, connecté soit au backend de production (`api.expria.app`), soit à une instance backend locale (pour tests isolés).

**Règles absolues :**
- Ne jamais utiliser de comptes réels (utilisateurs payants) pour les tests
- Utiliser exclusivement les 4 comptes `@gmail.com` documentés dans le backend
- Ne jamais committer les fichiers `.env` (présents dans `.gitignore`)

---

## 2. Prérequis

| Outil | Version minimum | Vérification |
|---|---|---|
| Node.js | 20.x LTS | `node --version` |
| npm | 10.x | `npm --version` |
| Git | 2.x | `git --version` |
| Navigateur moderne | Chrome 120+, Firefox 120+, Safari 17+ | — |

Recommandé :
- VS Code (ou Cursor) avec extensions : ESLint, Prettier, Tailwind CSS IntelliSense, Vitest
- DevTools React (extension navigateur)

---

## 3. Configuration — mode dev connecté au backend de production

C'est le mode par défaut. Le frontend local appelle `https://api.expria.app`.

### Fichier `.env` à créer à la racine du projet

```
# URL du backend de production
VITE_API_URL=https://api.expria.app

# Supabase (clé publique uniquement)
VITE_SUPABASE_URL=https://<project>.supabase.co
VITE_SUPABASE_ANON_KEY=<clé publique à obtenir auprès de Hermann>

# Flags de features (à ajuster selon le sprint)
VITE_ENABLE_T2_LIVE=false

# Monitoring (optionnel)
VITE_SENTRY_DSN=
```

**Les vraies valeurs** sont à récupérer dans :
- Le coffre-fort de Hermann (1Password / Bitwarden)
- Ou auprès de Hermann directement

Après modification du `.env`, redémarrer le dev server (Vite charge les env au démarrage seulement).

### Lancement

```bash
npm install
npm run dev
```

Le frontend est disponible sur `http://localhost:5173` (port Vite par défaut).

---

## 4. Configuration — mode dev connecté au backend local

Utile quand on veut :
- Tester une modification backend avant déploiement
- Déboguer un flux complet frontend + backend
- Travailler sans connexion internet stable

### Prérequis

Le backend doit tourner localement dans un autre terminal :
```bash
cd D:\expria-backend
npm run dev
# Backend disponible sur http://localhost:3000 (vérifier le port exact)
```

### Fichier `.env` (ajustement)

```
VITE_API_URL=http://localhost:3000
# Le reste reste identique
```

### Points d'attention

- **CORS** : le backend doit autoriser `http://localhost:5173` dans sa configuration CORS. À vérifier dans `expria-backend/src/index.ts`. Si CORS bloque les requêtes, voir SEC-02 dans `SECURITY.md`.
- **WebSocket T2** : devient `ws://localhost:3000/t2/live` (non sécurisé en dev local). Acceptable pour le dev.
- **Supabase** : reste en production même en dev local (Supabase n'a pas de mode local simple). Les comptes de test `@gmail.com` fonctionnent identiquement.

---

## 5. Comptes de test (rappel)

Identiques aux comptes documentés dans `expria-backend/docs/TEST_ENVIRONMENT.md` :

| Email | Plan | Simulations utilisées | Cas testé |
|---|---|---|---|
| test.free@gmail.com | free | 0 | Parcours Free normal |
| test.standard@gmail.com | standard | 12 | Parcours Standard complet |
| test.premium@gmail.com | premium | 28 | Parcours Premium complet |
| test.quota@gmail.com | free | 5 | Blocage quota Free |

**Mot de passe commun :** `Expria2025!test`

Les comptes sont créés par le script SQL de `expria-backend/docs/TEST_ENVIRONMENT.md` §3. Si un compte manque ou est corrompu, demander à Hermann de rejouer le script côté Supabase.

---

## 6. Scénarios de test spécifiques

### 6.1 Simuler un utilisateur Free qui atteint le quota

1. Se connecter avec `test.free@gmail.com`
2. Utiliser `test.quota@gmail.com` à la place (qui a déjà 5/5 utilisées)
3. Tenter de lancer une simulation → modal de blocage doit apparaître

**Ne pas** essayer de forcer le compteur en soumettant 5 simulations réelles — ça consomme des appels à DeepSeek (payant) et pollue la base.

### 6.2 Simuler un changement de plan

Pour tester le flux d'upgrade sans vraiment payer :
1. Aller sur `/pricing` avec `test.free@gmail.com`
2. Cliquer "Choisir Standard"
3. Sur la page Stripe Checkout, utiliser la carte de test `4242 4242 4242 4242`
4. Date d'expiration : n'importe laquelle dans le futur
5. CVC : n'importe lequel (3 chiffres)

Le webhook Stripe met à jour `plan = 'standard'` dans Supabase. Pour revenir à l'état initial après test, Hermann peut rejouer le script de reset de `expria-backend/docs/TEST_ENVIRONMENT.md` §5.

### 6.3 Simuler un paiement refusé

Même flux que 6.2 mais avec la carte `4000 0000 0000 0002`. Stripe retourne "paiement refusé". Le plan reste inchangé, le message d'erreur doit s'afficher clairement.

### 6.4 Simuler une session expirée

1. Se connecter normalement
2. Ouvrir DevTools → Application → Local Storage
3. Trouver la clé contenant le JWT Supabase (`sb-<project>-auth-token`)
4. Modifier la valeur pour casser le token (changer 1 caractère)
5. Rafraîchir la page
6. Le frontend doit détecter le JWT invalide → message "Session expirée" + redirect `/login`

Ce test vérifie SEC-06 (gestion des sessions expirées).

### 6.5 Simuler T2 Live sans avoir Premium

1. Se connecter avec `test.free@gmail.com` ou `test.standard@gmail.com`
2. Accéder à l'URL `/t2-live` directement
3. Le frontend doit afficher un PaywallModal ou rediriger
4. Si malgré tout une requête WebSocket est envoyée, le backend doit fermer la connexion avec close code 4003 (`PLAN_INSUFFICIENT`)

---

## 7. Matrice de compatibilité navigateurs

Ces navigateurs sont ceux que Claude Code doit considérer comme supportés. Tester au minimum sur les deux premiers.

| Navigateur | Version minimum | Priorité de test | Notes |
|---|---|---|---|
| Chrome (desktop) | 120 | 🔴 obligatoire | Majoritaire chez les utilisateurs |
| Chrome Mobile (Android) | 120 | 🔴 obligatoire | Audience Afrique = mobile-first |
| Safari Mobile (iOS) | 17 | 🟡 recommandé | Audience Canada = iPhone courant |
| Firefox (desktop) | 120 | 🟢 optionnel | Usage faible |
| Safari Desktop | 17 | 🟢 optionnel | Niche |

**Attention particulière pour mobile Android (Afrique) :**
- Connexions 3G/4G instables → vérifier que retry dans `api-client.ts` gère bien
- RAM limitée → éviter les listes illimitées, paginer
- Clavier virtuel qui masque les inputs → vérifier scroll automatique

Test mobile rapide via DevTools : Chrome → F12 → Toggle device toolbar → sélectionner "iPhone 12" ou "Galaxy S20".

Test mobile réel : idéal avant chaque release production, via un vrai téléphone ou un service comme BrowserStack (payant).

---

## 8. Simulation de conditions réseau dégradées

Dans Chrome DevTools → Network tab → Throttling dropdown :
- **Fast 3G** : simule une connexion 3G typique (Afrique)
- **Slow 3G** : simule une connexion 2G (zones rurales)
- **Offline** : simule une perte réseau

Tests à effectuer en mode "Fast 3G" :
- Login : doit répondre en < 10s
- Submit simulation : timeout à 30s doit fonctionner
- T2 Live : doit tenir la connexion WebSocket ou échouer gracieusement

---

## 9. Procédure avant chaque session Claude Code

```
[ ] D:\expria-frontend existe et contient docs/ à jour
[ ] .env est configuré (demander à Hermann si nécessaire)
[ ] npm install a été exécuté récemment (dernière modification package.json)
[ ] npm run dev démarre sans erreur
[ ] Login test.free@gmail.com fonctionne
[ ] Un commit Git propre existe avant de commencer
[ ] Les documents de référence ont été lus (cf. ONBOARDING.md §7)
```

---

## 10. Procédure après chaque session Claude Code

```
[ ] npm run typecheck : 0 erreur
[ ] npm run test : 0 échec
[ ] Les tests du Golden Dataset concernés ont été rejoués (cf. GOLDEN_DATASET.md)
[ ] Si modifications d'état (profils de test modifiés par des actions de test),
    rejouer le script de reset backend
[ ] Un commit Git a été fait avec un message clair
[ ] CHANGELOG.md mis à jour
```

---

## 11. Debugging

### Erreur "CORS blocked" au démarrage
- Vérifier que le backend autorise `http://localhost:5173`
- Vérifier que `VITE_API_URL` dans `.env` pointe vers la bonne URL backend
- Voir SEC-02 dans `SECURITY.md`

### Erreur "Invalid JWT" après login
- Le JWT expire au bout de ~1h, se déconnecter et se reconnecter
- Vider le localStorage (DevTools → Application → Clear site data)
- Vérifier que `VITE_SUPABASE_URL` correspond bien au projet Supabase utilisé par le backend

### Les variables d'environnement ne sont pas prises en compte
- Vite charge `.env` au démarrage uniquement — redémarrer `npm run dev` après modification
- Les variables doivent commencer par `VITE_` pour être exposées côté client
- Vérifier qu'il n'y a pas d'espace autour du `=` dans `.env`

### WebSocket T2 Live ne se connecte pas
- Vérifier `VITE_ENABLE_T2_LIVE=true` dans `.env`
- Vérifier que l'utilisateur est bien Premium
- Ouvrir DevTools → Network → filtrer par "WS" pour voir le handshake WebSocket
- Vérifier les close codes : 4001 = auth, 4003 = plan insuffisant

---

## 12. Historique

| Version | Date | Changements |
|---|---|---|
| 1.0 | 2026-04-17 | Création initiale |