# Visual tests — pixel-accurate baseline & regression

Workflow **design engineering** : baseline → capture current → pixelmatch diff → report. Aucune modification visuelle sans capture avant/après et diff explicite.

## Structure

```
visual-tests/
├── baselines/   # Référence approuvée (committée). Viewport fixe 1280×720, thème dark.
├── current/     # Captures de la branche en cours (générée par capture script).
├── diffs/       # Images de diff pixelmatch (baseline vs current).
├── reports/     # Rapport HTML + résumé des diffs.
└── PHASE1_REPORT.md  # Rapport visuel initial (hiérarchie, densité, alignements, contrastes).
```

## Règles

- **Seuil pixelmatch** : configurable via `VISUAL_DIFF_THRESHOLD` (défaut `0.1`). Explicite dans les rapports.
- **Viewport** : 1280×720 (desktop) pour les baselines. Breakpoints additionnels optionnels.
- **Thème** : dark forcé pour reproductibilité (aligné avec l’app en prod).

## Commandes

| Commande | Description |
|----------|-------------|
| `npm run visual:capture` | Playwright : capture écrans + composants → `visual-tests/current/`. |
| `npm run visual:update` | Playwright : écrase les baselines → `visual-tests/baselines/`. |
| `npm run visual:compare` | pixelmatch baselines vs current → `diffs/` + rapport JSON/HTML dans `reports/`. |
| `npm run visual:baseline` | Script Node (legacy) : capture → `baselines/`. |
| `npm run visual:test` | Lance les tests Playwright de régression (même config). |

## Écrans et nommage

- **Full page** : login, register, 404 (sans auth), dashboard, playlists, library (avec auth).
- **Composants** : sidebar, header, player (locators ciblés sur `/dashboard`).
- **Nommage** : `{screen-name}-{viewport}-{theme}.png` (ex. `login-desktop-dark.png`).

## Méthode

1. **Baseline** : une seule fois (ou après refonte validée) → `npm run visual:baseline`. Commit des fichiers dans `baselines/`.
2. **Avant une PR** : `npm run visual:capture` puis `npm run visual:compare`. Vérifier `reports/` et que les diffs correspondent aux changements voulus.
3. **CI** : `npm run visual:test` compare les snapshots Playwright aux baselines (même viewport/config). Échec si dépassement du seuil de pixels.

## Seuils

- **maxDiffPixels** (Playwright) : `VISUAL_MAX_DIFF_PIXELS` (défaut `0` en local pour être strict).
- **pixelmatch threshold** : `VISUAL_DIFF_THRESHOLD` (défaut **0.1**). Au-delà de ce ratio (pixels différents / total), la diff est considérée comme une régression. Documenter dans chaque rapport si modifié.

## Procédure de validation visuelle

1. **Lancer l’app** : `npm run dev` (ou `PLAYWRIGHT_BASE_URL` pointant vers l’app).
2. **Capturer l’état courant** : `npm run visual:capture` → remplit `visual-tests/current/`.
3. **Comparer aux baselines** : `npm run visual:compare` → génère `diffs/` et `reports/`.
4. **Interpréter** : ouvrir le rapport HTML dans `reports/` ; vérifier que les écarts correspondent aux changements voulus.
5. **Mettre à jour les baselines** (si changements validés) : `npm run visual:update` puis committer `visual-tests/baselines/`.

Les stories **full layout** (App/Layouts/DashboardLayout : Dashboard, Playlists, Library, Settings) peuvent servir de référence visuelle dans Storybook ; pour une régression automatisée, utiliser les tests Playwright (`e2e/visual-complete.spec.ts`).

## Accessibilité (a11y)

Utiliser l’addon **a11y** de Storybook sur les stories full layout et les composants critiques. Corriger les violations critiques (contraste, focus, labels). Vérifier la navigation clavier (Tab, Enter, Escape) sur Sidebar, Header, modales, player.

## Git

- **Commiter** : `visual-tests/baselines/`, `visual-tests/README.md`, `visual-tests/PHASE1_REPORT.md`.
- **Optionnel à ignorer** : `visual-tests/current/`, `visual-tests/diffs/`, `visual-tests/reports/` (générés localement ou en CI).