39b2b642d2
Plan UI premium 6–8 semaines (design system, shell, Storybook, a11y): - Design system: DESIGN_TOKENS.md, APP_SHELL.md, FULL_LAYOUT_PAGE.md. Single source for layout/shell (index.css), shadows (design-system.css), durations/easing. - Tokens: shadow-cover-depth, shadow-gold-glow, shadow-fab-glow; layout max-height (max-h-layout-drawer, max-h-layout-panel, max-h-layout-list). All duration-200/300/500 replaced by --duration-fast/normal/slow. Arbitrary shadows replaced by token classes. - Shell & player: Sidebar, Header, GlobalPlayer, MiniPlayer, PlayerQueue, PlayerControls, AudioPlayer use tokens; focus-visible on Sidebar, PlayerQueue, DropdownMenuTrigger/Item, TabsTrigger. Typography: text-[10px]/[9px] → text-xs where applicable. - ESLint: no-restricted-syntax (warn) for w-/h-/rounded-/shadow-/text-/spacing arbitrary. - Scripts: report-arbitrary-values.mjs, capture/compare/generate visual; visual-complete.spec.ts. - Stories full layout: Dashboard, Playlists, Library, Settings, Profile in DashboardLayout.stories. - .cursorrules + README: DESIGN_TOKENS, APP_SHELL, visual commands, no arbitrary without justification. - apps/web/.gitignore: e2e test artifacts (test-results-visual, playwright-report-visual). Co-authored-by: Cursor <cursoragent@cursor.com>
66 lines
3.9 KiB
Markdown
66 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).
|