67 lines
3.9 KiB
Markdown
67 lines
3.9 KiB
Markdown
|
# 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).
|