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)

```bash
# 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)

```yaml
# 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.