hermann/expria-frontend
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1
expria-frontend/docs/TEST_ENVIRONMENT.md

9.3 KiB
Raw Blame History

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

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 :

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