đŸŽ„ Guide Complet des Tests E2E

Ce guide centralise toutes les informations sur les tests End-to-End avec Playwright et la génération de vidéos de documentation vivante.

🎯 Introduction

Les tests E2E de KoproGo testent toute la stack :

  • ✅ Frontend (Astro + Svelte)

  • ✅ Backend (Rust + Actix-web)

  • ✅ Base de donnĂ©es (PostgreSQL)

  • ✅ API REST

  • ✅ PWA + Mode Offline

Chaque test peut enregistrer une vidéo de démonstration : générez-les localement, puis ajoutez les fichiers .webm dans docs/_static/videos/ pour enrichir la documentation.

🚀 DĂ©marrage Rapide

Installation (une seule fois)

# Installer les dépendances frontend
cd frontend
npm install

# Installer Playwright et Chromium
npx playwright install chromium

DĂ©marrer les services

# Depuis la racine du projet
make up

# Les services démarrent automatiquement via Docker Compose + Traefik
# Frontend: http://localhost
# API: http://localhost/api/v1

Lancer les tests

# Tests normaux (rapides)
cd frontend
npm run test:e2e

# OU depuis la racine
make test-e2e

# Tests ralentis (pour vidéos plus lisibles) ⭐
make test-e2e-slow

đŸ“č Enregistrer de Nouveaux Tests

MĂ©thode 1 : Playwright Codegen (⭐ RecommandĂ©)

Enregistrement interactif - Playwright génÚre le code automatiquement !

# Assurer que l'app tourne
make up

# Lancer l'enregistrement
cd frontend
npm run codegen

# OU pour mobile
npm run codegen:mobile

# Alternative depuis la racine
make codegen
make codegen DEVICE=mobile

Ce qui se passe :

  1. Un navigateur s’ouvre sur http://localhost

  2. Une fenĂȘtre “Playwright Inspector” s’ouvre Ă  cĂŽtĂ©

  3. Vous naviguez dans l’app (clic, remplissage de formulaires, etc.)

  4. Le code du test apparaĂźt en temps rĂ©el dans l’Inspector

  5. Vous copiez le code et le collez dans un fichier .spec.ts

Sauvegarder le test :

// frontend/tests/e2e/mon-test.spec.ts
import { test, expect } from '@playwright/test';

test('Mon scénario de test', async ({ page }) => {
  await page.goto('/login');
  await page.fill('input[type="email"]', 'test@test.com');
  await page.fill('input[type="password"]', 'test123');
  await page.click('button[type="submit"]');
  await expect(page.locator('text=Dashboard')).toBeVisible();
});

Lancer le test :

npm run test:e2e -- mon-test.spec.ts

La vidéo sera dans frontend/test-results/ !

MĂ©thode 2 : Écrire le Test Manuellement

Si vous préférez écrire le code directement :

# Créer le fichier
nano frontend/tests/e2e/mon-test.spec.ts

# Écrire le test (voir exemple ci-dessus)

# Lancer
npm run test:e2e -- mon-test.spec.ts

🐌 CrĂ©er des VidĂ©os Plus Lisibles

Pour que les vidéos soient plus faciles à suivre, utilisez le mode ralenti :

make test-e2e-slow

Ce qui se passe automatiquement :

  1. ✅ Ajoute await page.waitForTimeout(1000) aprùs chaque action (click, fill, etc.)

  2. ✅ Lance les tests E2E

  3. ✅ GĂ©nĂšre les vidĂ©os localement (1 seconde entre chaque action = plus lisible !)

  4. ✅ Restaure automatiquement la vitesse normale aprùs

Délai personnalisé :

# 2 secondes entre chaque action
bash .claude/scripts/slow-down-tests.sh 2000
cd frontend && npm run test:e2e
bash .claude/scripts/restore-test-speed.sh

Restaurer manuellement :

make test-e2e-restore-speed

📚 Ajouter les VidĂ©os dans la Documentation

Une fois les tests exécutés en local, synchronisez et versionnez les vidéos :

# Copie les vidéos + génÚre la page RST automatiquement
make docs-sync-videos

# Générer la documentation Sphinx
make docs-sphinx

# VĂ©rifier le rendu localement
open docs/_build/html/e2e-videos.html

Les fichiers copiĂ©s dans docs/_static/videos/ doivent ĂȘtre commitĂ©s dans Git. Ils seront ensuite publiĂ©s automatiquement par le workflow documentation (.github/workflows/docs.yml).

Le dossier docs/_build/ reste local (ignoré par Git) : ne le commitez pas.

Les vidĂ©os validĂ©es sont listĂ©es dans la page đŸŽ„ VidĂ©os Tests E2E (Documentation Vivante).

🎬 Commandes Disponibles

Commandes npm (depuis frontend/)

# Enregistrement interactif
npm run codegen              # Desktop
npm run codegen:mobile       # iPhone 13

# Tests
npm run test:e2e             # Tous les tests (headless)
PLAYWRIGHT_BASE_URL=http://localhost npm run test:e2e -- AdminDashBoard.improved.spec.ts  # Suite admin
npm run test:e2e -- mon-test.spec.ts  # Un test spécifique
npm run test:e2e:ui          # Mode UI (interface graphique)
npm run test:e2e:headed      # Voir le navigateur
npm run test:e2e:debug       # Mode debug pas Ă  pas

# Rapports
npm run test:e2e:report      # Ouvre le rapport HTML avec vidéos

Commandes make (depuis la racine)

# Tests E2E
make test-e2e                # Tests normaux (rapides)
make test-e2e-slow           # Tests ralentis (vidéos lisibles)
make test-e2e-restore-speed  # Restaurer vitesse normale

# Documentation
make docs-sync-videos        # Copier vidéos + générer RST (local)
make docs-with-videos        # Helper local pour générer vidéos + doc
make docs-sphinx             # Générer doc Sphinx seule
make codegen                 # Playwright codegen (DEVICE=mobile pour iPhone 13)

Les cibles make test-e2e et make docs-with-videos exportent automatiquement PLAYWRIGHT_BASE_URL=http://localhost pour cibler l’environnement Traefik local.

📂 Structure des Fichiers

Tests E2E

frontend/tests/e2e/
├── config.ts                        # Helper pour construire les endpoints
└── AdminDashBoard.improved.spec.ts  # Suite complùte admin (org/users/buildings)

VidĂ©os GĂ©nĂ©rĂ©es

frontend/test-results/
├── admin-dashboard-tour-test-chromium/
│   ├── video.webm              # ← VidĂ©o du test
│   ├── trace.zip               # Trace Playwright
│   └── test-failed-1.png       # (si Ă©chec)
└── autre-test-chromium/
    └── video.webm

Documentation VidĂ©os

docs/_static/videos/
├── admin-dashboard-tour.webm
├── login-success.webm
└── *.webm                      # Toutes vos vidĂ©os

docs/e2e-videos.rst             # Page auto-générée

⚙ Configuration Playwright

Le fichier frontend/playwright.config.ts configure :

  • Enregistrement vidĂ©o : video: { mode: 'on', size: { width: 1280, height: 720 } }

  • Base URL : baseURL: 'http://localhost:3000'

  • WebServer : DĂ©marre automatiquement npm run dev

  • Timeouts : 10s par action, 30s par page

  • Screenshots : Uniquement en cas d’échec

🐛 Debugging

Mode UI (RecommandĂ©)

cd frontend
npm run test:e2e:ui

Cela ouvre une interface graphique oĂč vous pouvez :

  • ✅ Voir tous vos tests

  • ✅ Les lancer un par un

  • ✅ Voir les vidĂ©os/screenshots

  • ✅ Inspecter chaque Ă©tape

  • ✅ Voir les timings

Mode Debug

npm run test:e2e:debug

Le test s’arrĂȘte Ă  chaque Ă©tape, vous pouvez :

  • Inspecter le DOM

  • ExĂ©cuter du code dans la console

  • Avancer pas Ă  pas

Mode Headed (Voir le navigateur)

npm run test:e2e:headed

Le navigateur s’affiche pendant l’exĂ©cution des tests.

🆘 ProblĂšmes Courants

❌ Les navigateurs ne s’installent pas

# Sans dépendances systÚme (si pas de sudo)
npx playwright install chromium

# Avec dépendances (si sudo disponible)
npx playwright install chromium --with-deps

❌ L’app n’est pas accessible

# VĂ©rifier que les services tournent
curl http://localhost
curl http://localhost/api/v1/health

# Si pas de réponse, démarrer :
make up

❌ Timeout lors des tests

Augmentez les timeouts dans playwright.config.ts :

use: {
  actionTimeout: 20000,        // 20s au lieu de 10s
  navigationTimeout: 60000,    // 60s au lieu de 30s
}

❌ Les vidĂ©os ne sont pas gĂ©nĂ©rĂ©es

VĂ©rifiez dans playwright.config.ts :

video: {
  mode: 'on',  // Doit ĂȘtre 'on', pas 'retain-on-failure'
}

❌ “Target page has been closed”

Votre app redirige trop vite. Ajoutez des attentes :

await page.click('button');
await page.waitForURL('/dashboard');

📊 Best Practices

  1. Noms de tests explicites

    // ✅ Bon
test('Login admin et navigation vers dashboard organisations', ...)

// ❌ Mauvais
test('test', ...)

  2. Utiliser les rĂŽles ARIA

    // ✅ Bon (plus robuste)
await page.getByRole('button', { name: 'Se connecter' }).click();

// ❌ Éviter (fragile)
await page.click('.btn-login');

  3. Attentes explicites

    // ✅ Bon
await expect(page.getByText('Dashboard')).toBeVisible();

// ❌ Éviter
await page.waitForTimeout(5000);

  4. One test, one scenario

    Chaque test doit tester UN scénario utilisateur complet.

  5. Vidéos lisibles

    Utilisez make test-e2e-slow pour créer des vidéos de documentation.

🔗 IntĂ©gration CI/CD

Les vidĂ©os ne sont plus gĂ©nĂ©rĂ©es dans la CI : elles doivent provenir d’un run local fiable, puis ĂȘtre ajoutĂ©es au dĂ©pĂŽt. Le workflow .github/workflows/docs.yml se charge ensuite de publier la documentation Sphinx (et toutes les vidĂ©os dĂ©jĂ  prĂ©sentes dans docs/_static/videos/) vers GitHub Pages.

📚 Ressources

đŸ€– Guide maintenu avec Claude Code

KoproGo ASBL - Tests E2E et Documentation Vivante