veza/apps/web/visual-tests

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).