Tests E2E (Playwright) — runbook

Utilisateurs avancés : ce document décrit comment écrire, exécuter et diagnostiquer les tests end-to-end.

Où sont les tests

Les tests E2E Playwright sont dans l’application (workspace app/) :

• app/tests/e2e/**/*.spec.ts

Lancer les E2E en local

Depuis app/ :

cd app
npm run test:e2e

Pour exécuter un test précis :

cd app
npx playwright test tests/e2e/tournament-student-play.spec.ts --reporter=list

Principes (anti-flake)

• Setup API/debug, vérification UI : préparer données (users/questions/game) via endpoints dédiés, puis valider le vrai parcours UI.
• Attentes event-based : préférer les acknowledgements et événements sockets aux waitForTimeout.
• Scénarios courts : un test = un scénario déterministe.

Helpers Playwright (patterns)

Le codebase fournit des helpers pour éviter des parcours UI longs :

• LoginHelper : login API (enseignant/élève)
• TestDataHelper : création/seed de données pour tests
• NodeSocketHelper / SocketHelper : instrumentation Socket.IO (Node-side et browser-side)

Recommandation : si le scénario dépend des sockets, garder une validation côté navigateur (browser-side) pour coller au comportement client réel.

Validation de contrat (sockets + Zod)

Objectif : éviter les régressions « ça marche visuellement mais le payload est invalide ».

Quand un test attend un game_question, il doit au minimum vérifier :

• timer.status === 'run'
• timer.timerEndDateMs est un nombre

Et si possible : valider le payload avec le schéma Zod partagé utilisé par l’app (source unique de vérité).

Règle importante : console propre

Les E2E sont configurés pour échouer si des erreurs de validation/Zod apparaissent dans la console navigateur. But : éviter les tests « verts » quand le contrat on-wire est cassé.

Endpoints de debug utiles (E2E)

Le backend expose des endpoints pour rendre les tests déterministes.

Exemples (selon ce qui est disponible dans le code) :

• Seed d’un jeu élève : POST /api/v1/debug/seed-student-game
• Inspection des sockets / rooms : GET /api/v1/debug/sockets/:accessCode

Règle : si un test introduit un nouvel endpoint debug ou change un contrat d’endpoint, mettre à jour la doc technique (ici) dans la même PR.

Diagnostics (traces, vidéo, codegen)

Inspecter un trace Playwright :

npx playwright show-trace test-results/<path>/trace.zip

Générer rapidement du code (quand les sélecteurs/UI changent) :

npx playwright codegen http://localhost:3008

Erreurs fréquentes

• Join socket sans ack : souvent causé par un payload join_game incomplet (schéma serveur). Aligner les payloads Node-side avec ceux du client navigateur.
• Race countdown/question : attendre explicitement le bon événement (et vérifier game_error).

Post-run cleanup (recommended for CI)

To keep build artifacts and the service worker in sync with the test run, the E2E teardown now automatically runs a test cleanup step after each run that removes test-only image refs and stale service-worker entries.

• The teardown will invoke two scripts from the backend during globalTeardown:
  • npm run cleanup:test-images (removes test images and DB sharedImage refs when present)
  • npm run cleanup:sw (removes stale test-* and dup-ref-* references from app/frontend/public/sw.js and saves a backup)

Notes:

• These steps are non-fatal (teardown will continue even if cleanup fails) and are safe to run in CI.
• If you prefer manual review, run npx tsx scripts/dry-run-cleanup-test-images.ts locally to list candidates before deletion.
• If your CI regenerates the frontend build artifact after tests, ensure the build includes up-to-date assets to avoid re-introducing stale SW entries.