veza/docs/VISUAL_TESTING_STRATEGY.md

Stratégie de tests visuels (Playwright + pixelmatch)

Objectif : vue fiable du frontend via des screenshots automatiques et une comparaison pixel-perfect pour éviter les régressions visuelles.

---

1. Stack

Outil	Rôle
Playwright	Lancement du navigateur, navigation, capture d’écran, comparaison avec les baselines.
toHaveScreenshot()	Comparaison pixel à pixel (Playwright utilise en interne un algorithme type pixelmatch).
pixelmatch + pngjs	Script optionnel scripts/visual-diff.js pour générer une image de diff à partir de deux PNG (expected/actual).

Les baselines (golden screenshots) sont versionnées dans le dépôt. En CI, on compare les nouvelles captures aux baselines ; en local, on peut mettre à jour les baselines après un changement volontaire.

---

2. Config dédiée : playwright.config.visual.ts

• Répertoire des tests : e2e/tests/visual/
• Snapshots : e2e/tests/visual/__snapshots__/ (un fichier par test, nommé {arg}-{projectName}{ext}).
• Viewport fixe : 1280×720 (Chromium uniquement) pour des captures reproductibles.
• Réduction des animations : reduceMotion: 'reduce' pour limiter la flou du à des animations.
• Un worker : exécution séquentielle pour éviter les variations de charge.
• Auth : les tests login/register utilisent un contexte sans cookie. Les tests “app” (dashboard, sidebar, player) utilisent e2e/.auth/user.json s’il existe ; sinon certains tests (ex. sidebar) sont skippés. Pour créer ou mettre à jour les baselines authentifiés, exécuter d’abord les tests E2E normaux (avec global setup) une fois : npx playwright test --config=playwright.config.ts (cela crée e2e/.auth/user.json), puis npm run test:visual:update.

---

3. Suite de tests : e2e/tests/visual/visual-regression.spec.ts

• Auth (sans cookie) : login, register — full page, thème dark forcé.
• App (avec auth) : dashboard full page, header, sidebar, barre de lecture — thème dark forcé.
• Routes : playlists, 404.
• Viewports : mobile 375×667, tablette 768×1024.

Chaque test :

1. Navigue vers l’URL.
2. Attend networkidle et les éléments principaux.
3. Force le thème dark (document.documentElement.classList.add('dark')).
4. Attend un délai de stabilisation (800 ms).
5. Appelle expect(...).toHaveScreenshot(...) avec maxDiffPixels (et éventuellement maxDiffPixelRatio).

Tolérance pixel-perfect : par défaut maxDiffPixels: 0. En CI, si besoin (police, anti-aliasing), on peut relâcher via la variable d’environnement VISUAL_MAX_DIFF_PIXELS (ex. 50).

---

4. Commandes npm (apps/web)

# Lancer les tests visuels (compare aux baselines)
npm run test:visual

# Mettre à jour les baselines après un changement volontaire
npm run test:visual:update

# Ouvrir le rapport HTML des derniers runs
npm run test:visual:report

En CI, exécuter npm run test:visual après le build. En cas d’échec, les artefacts contiennent les dossiers test-results-visual avec expected / actual / diff.

---

5. Workflow recommandé

1. Développement : modifier l’UI, lancer npm run test:visual. Si le changement est voulu, lancer npm run test:visual:update et committer les nouveaux fichiers dans e2e/tests/visual/__snapshots__/.
2. CI : exécuter npm run test:visual (sans --update-snapshots). En cas d’échec, télécharger les artefacts (expected, actual, diff) pour analyser.
3. Optionnel : après un échec, utiliser node scripts/visual-diff.js <expected.png> <actual.png> [diff.png] pour générer une image de diff avec pixelmatch (seuillage personnalisable).

---

6. Bonnes pratiques

• Thème : forcer dark dans les tests pour des baselines cohérentes.
• Viewport : ne pas changer de taille dans un même projet “visual” sauf tests dédiés (mobile/tablette).
• Données : utiliser des mocks ou un compte de test stable pour que le contenu (dashboard, playlists) ne change pas d’un run à l’autre.
• Animations : reduceMotion + délai de stabilisation pour éviter les flous.
• Nommage : noms de snapshots courts et explicites (ex. login-page.png, dashboard-sidebar.png).

---

7. Fichiers clés

Fichier	Rôle
playwright.config.visual.ts	Config viewport, snapshot path, projet Chromium.
e2e/tests/visual/visual-regression.spec.ts	Tous les tests toHaveScreenshot.
e2e/tests/visual/__snapshots__/	Baselines PNG (à committer).
scripts/visual-diff.js	Script optionnel pixelmatch pour diff image.
docs/VISUAL_TESTING_STRATEGY.md	Ce document.

---

8. Intégration CI (exemple)

# Exemple GitHub Actions
- name: Run visual regression
  run: cd apps/web && npm run test:visual
  env:
    VISUAL_MAX_DIFF_PIXELS: "0"   # ou "50" si tolérance acceptée

- name: Upload visual test results
  if: failure()
  uses: actions/upload-artifact@v4
  with:
    name: visual-test-results
    path: apps/web/e2e/test-results-visual/

Cette stratégie donne une vue automatique et pixel-perfect du frontend via Playwright et, en option, pixelmatch pour l’analyse des diffs.