Visual Regression Testing Patterns

Le visual regression capture des screenshots et les compare à un baseline pour détecter les changements UI non intentionnels. Complémente (sans remplacer) les tests unitaires et E2E.

1. Decision tree

Projet avec Storybook ?
├── OUI → Chromatic (intégration native Storybook, cloud managed)
└── NON →
    ├── Budget + cross-browser critique → Percy ou Applitools
    ├── Budget zéro + local only → BackstopJS
    └── Already using Playwright → Playwright visual comparisons built-in

Besoin de tests AI-powered (smart diff) ?
└── Applitools Eyes (plus cher mais détecte les changements "meaningful")

2. Chromatic (recommandé si Storybook)

npm install -D chromatic

# CI run
npx chromatic --project-token=xxx --exit-zero-on-changes

// .storybook/main.ts
export default {
  stories: ['../src/**/*.stories.@(ts|tsx)'],
  addons: ['@storybook/addon-essentials'],
  framework: { name: '@storybook/react-vite' },
}

Chromatic capture un snapshot de chaque story × chaque viewport × chaque browser configuré. Les diffs sont review-able dans une UI dédiée, avec approve/reject qui met à jour le baseline.

3. Playwright visual comparisons (built-in)

// tests/visual.spec.ts
import { test, expect } from '@playwright/test'

test('homepage visual', async ({ page }) => {
  await page.goto('https://example.com')
  await expect(page).toHaveScreenshot('homepage.png', {
    maxDiffPixelRatio: 0.01,
    fullPage: true,
    animations: 'disabled',
  })
})

test('hero component', async ({ page }) => {
  await page.goto('https://example.com')
  const hero = page.locator('.hero')
  await expect(hero).toHaveScreenshot('hero.png')
})

// playwright.config.ts
export default defineConfig({
  snapshotPathTemplate: '{testDir}/__screenshots__/{testFilePath}/{arg}{ext}',
  expect: {
    toHaveScreenshot: {
      maxDiffPixelRatio: 0.01,
      threshold: 0.2,
      animations: 'disabled',
    },
  },
})

Première run → crée les baselines. Runs suivants → compare. Update baseline : npx playwright test --update-snapshots.

4. BackstopJS (open source, local)

npm install -D backstopjs
npx backstop init

// backstop.json
{
  "id": "my_project",
  "viewports": [
    { "label": "phone", "width": 375, "height": 667 },
    { "label": "tablet", "width": 768, "height": 1024 },
    { "label": "desktop", "width": 1440, "height": 900 }
  ],
  "scenarios": [
    {
      "label": "homepage",
      "url": "https://example.com",
      "selectors": ["document"],
      "delay": 500,
      "misMatchThreshold": 0.1
    },
    {
      "label": "product page",
      "url": "https://example.com/products/p1",
      "selectors": [".product-hero", ".product-description"],
      "hideSelectors": [".advertisement", ".cookie-banner"]
    }
  ],
  "engine": "puppeteer",
  "report": ["browser"]
}

npx backstop reference   # créer les baselines
npx backstop test         # comparer
npx backstop approve      # accepter les changements

5. Handling dynamic content

Problème : dates, animations, random IDs, user avatars → causent des faux positifs.

Solution 1 — Masquer les zones dynamiques

// Playwright
await expect(page).toHaveScreenshot({
  mask: [page.locator('.timestamp'), page.locator('.user-avatar')],
})

// Chromatic — via CSS `visibility: hidden` dans une story dédiée

Solution 2 — Disable animations + fix dates

// Playwright
test.beforeEach(async ({ page }) => {
  // Freeze Date.now()
  await page.addInitScript(() => {
    const fixedDate = new Date('2026-01-01T00:00:00Z')
    Date.now = () => fixedDate.getTime()
  })

  // Disable CSS animations
  await page.addStyleTag({
    content: `
      *, *::before, *::after {
        animation-duration: 0s !important;
        transition-duration: 0s !important;
      }
    `,
  })
})

Solution 3 — Wait for fonts

await page.evaluate(() => document.fonts.ready)

6. CI integration (GitHub Actions + Chromatic)

name: Visual regression

on: [pull_request]

jobs:
  chromatic:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
      - run: npm ci
      - run: npm run build-storybook
      - uses: chromaui/action@v1
        with:
          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
          exitOnceUploaded: true

Chromatic commente la PR avec un lien vers les diffs review.

7. Baseline management

Branching strategy

• Baselines liées à main — chaque merge met à jour la baseline
• PR branch — compare contre la baseline de main
• Approve changes dans Chromatic UI ou via npx playwright test --update-snapshots + commit

Cross-OS baselines

Les rendus varient entre macOS / Linux / Windows → toujours générer les baselines dans le même environnement que la CI (typiquement Linux).

# En local sur macOS
docker run --rm -v $(pwd):/app -w /app mcr.microsoft.com/playwright:v1.41.0 \
  npx playwright test --update-snapshots

8. Viewport matrix

Un bon setup capture 3-4 viewports :

• Mobile portrait (375 × 667)
• Mobile landscape (667 × 375) — optionnel
• Tablet (768 × 1024)
• Desktop (1440 × 900)

Au-delà de 4, le coût CI explose.

9. Browser matrix

Chromatic et Percy supportent Chrome + Firefox + Safari + Edge en parallèle. Playwright built-in aussi.

Règle : couvrir au minimum Chrome (le standard) + Safari (iOS users) + Firefox (rendering different engine).

Anti-patterns

1. Baselines committées sur macOS, CI sur Linux → 100 % de diffs sur le CI
2. Pas de mask sur dates / animations → tests flaky
3. Screenshots full page sur tout le site → baseline énorme, diffs impossibles à review
4. Threshold 0 (pixel-perfect absolu) → anti-aliasing détecté comme changement
5. Pas de review des diffs avant approve → baseline polluée
6. Tests visuels en dev local sans CI → détection tardive
7. Appliquer les tests à des pages avec contenu dynamique (liste de tweets live) → flaky par design
8. Pas de wait pour les fonts → rendu inconsistant
9. Screenshots mobiles sans isMobile: true → pas de touch events, pas de viewport meta

Checklist

• Tool choisi (Chromatic si Storybook, Playwright si E2E existant)
• Viewports définis (3-4 max)
• Browsers définis
• Dynamic content masked ou mocké
• Animations disabled
• Fonts wait implémenté
• Dates fixées via page.addInitScript
• Baselines générées dans le même OS que la CI
• Threshold calibré (0.01-0.1)
• CI integration avec approval workflow
• Storybook comme source de composants isolés (recommandé)

Quand déléguer

• E2E fonctionnel → skill e2e-testing
• Frontend design → skill frontend-design
• Accessibility → accessibility-auditor
• Storybook setup → skill frontend-patterns

Ressources

• https://www.chromatic.com/docs
• https://playwright.dev/docs/test-snapshots
• https://docs.percy.io/
• https://applitools.com/docs/
• https://github.com/garris/BackstopJS