@assertrx/dino 1.0.0

package/skills/playwright-core/visual-regression.md

@@ -0,0 +1,1027 @@
+# Visual Regression Testing
+
+> **When to use**: Catching unintended visual changes -- layout shifts, style regressions, broken responsive designs, theme corruption -- that functional assertions miss. Visual tests answer "does it still look right?" after code changes.
+> **Prerequisites**: [core/configuration.md](configuration.md) for project setup, [core/assertions-and-waiting.md](assertions-and-waiting.md) for assertion basics.
+
+## Quick Reference
+
+```typescript
+// Page screenshot -- compare entire viewport
+await expect(page).toHaveScreenshot();
+
+// Element screenshot -- compare a specific component
+await expect(page.getByTestId('pricing-card')).toHaveScreenshot();
+
+// Named snapshot -- explicit file name
+await expect(page).toHaveScreenshot('homepage-hero.png');
+
+// With threshold -- allow minor pixel differences
+await expect(page).toHaveScreenshot({ maxDiffPixelRatio: 0.01 });
+
+// Mask dynamic content -- hide timestamps, avatars, ads
+await expect(page).toHaveScreenshot({
+  mask: [page.getByTestId('timestamp'), page.getByRole('img', { name: 'Avatar' })],
+});
+
+// Disable animations -- prevent flaky diffs from CSS transitions
+await expect(page).toHaveScreenshot({ animations: 'disabled' });
+
+// Update baselines (CLI)
+npx playwright test --update-snapshots
+```
+
+## Patterns
+
+### 1. Screenshot Comparison Basics
+
+**Use when**: Verifying that a page or component renders correctly after code changes. Best for pages with stable layouts -- landing pages, dashboards, settings panels.
+**Avoid when**: The page is highly dynamic with real-time data, live feeds, or content that changes on every load. Use functional assertions instead.
+
+Playwright compares a screenshot taken during the test against a stored baseline (golden) image. On first run, the baseline is created. On subsequent runs, differences cause the test to fail with a visual diff report.
+
+**TypeScript**
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('homepage renders correctly', async ({ page }) => {
+  await page.goto('/');
+
+  // Full page screenshot comparison
+  await expect(page).toHaveScreenshot('homepage.png');
+});
+
+test('pricing card matches design', async ({ page }) => {
+  await page.goto('/pricing');
+
+  // Element-level screenshot -- scoped to a single component
+  const card = page.getByTestId('pro-plan-card');
+  await expect(card).toHaveScreenshot('pro-plan-card.png');
+});
+```
+
+**JavaScript**
+```javascript
+const { test, expect } = require('@playwright/test');
+
+test('homepage renders correctly', async ({ page }) => {
+  await page.goto('/');
+
+  await expect(page).toHaveScreenshot('homepage.png');
+});
+
+test('pricing card matches design', async ({ page }) => {
+  await page.goto('/pricing');
+
+  const card = page.getByTestId('pro-plan-card');
+  await expect(card).toHaveScreenshot('pro-plan-card.png');
+});
+```
+
+Snapshots are stored alongside tests by default in a folder named `<test-file-name>-snapshots/`. The folder structure includes the project name and platform:
+
+```
+tests/
+  homepage.spec.ts
+  homepage.spec.ts-snapshots/
+    homepage-chromium-linux.png
+    homepage-chromium-darwin.png
+```
+
+### 2. Configuring Thresholds
+
+**Use when**: Your UI has minor rendering differences between runs -- anti-aliasing, font hinting, sub-pixel rendering. Thresholds prevent false failures from pixel-level noise.
+**Avoid when**: You want pixel-perfect comparisons (design-system component libraries, icon rendering). Keep thresholds at zero.
+
+Three knobs control comparison sensitivity:
+
+| Option | What it controls | Good default |
+|---|---|---|
+| `maxDiffPixels` | Absolute number of pixels that can differ | `100` for full pages, `10` for components |
+| `maxDiffPixelRatio` | Fraction of total pixels that can differ (0-1) | `0.01` (1%) for full pages |
+| `threshold` | Per-pixel color difference tolerance (0-1) | `0.2` for most UIs, `0.1` for design systems |
+
+**TypeScript**
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('dashboard allows minor rendering variance', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // Allow up to 1% of pixels to differ
+  await expect(page).toHaveScreenshot('dashboard.png', {
+    maxDiffPixelRatio: 0.01,
+  });
+});
+
+test('icon renders pixel-perfect', async ({ page }) => {
+  await page.goto('/icons');
+
+  // Strict: zero tolerance
+  await expect(page.getByTestId('logo')).toHaveScreenshot('logo.png', {
+    maxDiffPixels: 0,
+    threshold: 0,
+  });
+});
+
+test('chart allows anti-aliasing differences', async ({ page }) => {
+  await page.goto('/analytics');
+
+  // Per-pixel color threshold + absolute pixel count cap
+  await expect(page.getByTestId('revenue-chart')).toHaveScreenshot('revenue-chart.png', {
+    threshold: 0.3,
+    maxDiffPixels: 200,
+  });
+});
+```
+
+**JavaScript**
+```javascript
+const { test, expect } = require('@playwright/test');
+
+test('dashboard allows minor rendering variance', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  await expect(page).toHaveScreenshot('dashboard.png', {
+    maxDiffPixelRatio: 0.01,
+  });
+});
+
+test('icon renders pixel-perfect', async ({ page }) => {
+  await page.goto('/icons');
+
+  await expect(page.getByTestId('logo')).toHaveScreenshot('logo.png', {
+    maxDiffPixels: 0,
+    threshold: 0,
+  });
+});
+
+test('chart allows anti-aliasing differences', async ({ page }) => {
+  await page.goto('/analytics');
+
+  await expect(page.getByTestId('revenue-chart')).toHaveScreenshot('revenue-chart.png', {
+    threshold: 0.3,
+    maxDiffPixels: 200,
+  });
+});
+```
+
+**Global thresholds** in `playwright.config.ts`:
+
+```typescript
+// playwright.config.ts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  expect: {
+    toHaveScreenshot: {
+      maxDiffPixelRatio: 0.01,
+      threshold: 0.2,
+      animations: 'disabled',
+    },
+  },
+});
+```
+
+### 3. Full Page vs Element Screenshots
+
+**Use when**: Deciding scope. Full page catches layout shifts and spacing regressions. Element screenshots isolate components and are more stable.
+**Avoid when**: Neither -- use both strategically.
+
+**TypeScript**
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('full page screenshot catches layout shifts', async ({ page }) => {
+  await page.goto('/');
+
+  // Captures the visible viewport
+  await expect(page).toHaveScreenshot('homepage-viewport.png');
+
+  // Captures the entire scrollable page
+  await expect(page).toHaveScreenshot('homepage-full.png', {
+    fullPage: true,
+  });
+});
+
+test('element screenshot isolates component changes', async ({ page }) => {
+  await page.goto('/pricing');
+
+  // Only the pricing table -- immune to header/footer changes
+  await expect(page.getByRole('table')).toHaveScreenshot('pricing-table.png');
+
+  // A specific card within the page
+  await expect(page.getByTestId('enterprise-card')).toHaveScreenshot('enterprise-card.png');
+});
+```
+
+**JavaScript**
+```javascript
+const { test, expect } = require('@playwright/test');
+
+test('full page screenshot catches layout shifts', async ({ page }) => {
+  await page.goto('/');
+
+  await expect(page).toHaveScreenshot('homepage-viewport.png');
+
+  await expect(page).toHaveScreenshot('homepage-full.png', {
+    fullPage: true,
+  });
+});
+
+test('element screenshot isolates component changes', async ({ page }) => {
+  await page.goto('/pricing');
+
+  await expect(page.getByRole('table')).toHaveScreenshot('pricing-table.png');
+  await expect(page.getByTestId('enterprise-card')).toHaveScreenshot('enterprise-card.png');
+});
+```
+
+**Rule of thumb**: Use element screenshots for components that change independently. Use full page screenshots for key landing pages and layouts where spacing between sections matters.
+
+### 4. Masking Dynamic Content
+
+**Use when**: The page contains content that changes between test runs -- timestamps, user avatars, ad slots, relative dates ("3 minutes ago"), random hero images, A/B test variants.
+**Avoid when**: All content is deterministic. Masking adds maintenance overhead.
+
+The `mask` option overlays a solid-colored box over specified locators before taking the screenshot. The masked region is excluded from comparison.
+
+**TypeScript**
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('dashboard with masked dynamic content', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  await expect(page).toHaveScreenshot('dashboard.png', {
+    mask: [
+      page.getByTestId('current-time'),
+      page.getByTestId('user-avatar'),
+      page.getByTestId('live-visitor-count'),
+      page.locator('.ad-banner'),
+    ],
+    maskColor: '#FF00FF', // visible magenta -- makes it obvious what's masked in reviews
+  });
+});
+
+test('feed page with relative timestamps', async ({ page }) => {
+  await page.goto('/feed');
+
+  // Mask all relative time elements at once
+  await expect(page).toHaveScreenshot('feed.png', {
+    mask: [page.locator('time[datetime]')],
+  });
+});
+
+test('profile page with user-generated content', async ({ page }) => {
+  await page.goto('/profile/test-user');
+
+  await expect(page).toHaveScreenshot('profile.png', {
+    mask: [
+      page.getByRole('img', { name: 'Profile photo' }),
+      page.getByTestId('last-login'),
+      page.getByTestId('member-since'),
+    ],
+  });
+});
+```
+
+**JavaScript**
+```javascript
+const { test, expect } = require('@playwright/test');
+
+test('dashboard with masked dynamic content', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  await expect(page).toHaveScreenshot('dashboard.png', {
+    mask: [
+      page.getByTestId('current-time'),
+      page.getByTestId('user-avatar'),
+      page.getByTestId('live-visitor-count'),
+      page.locator('.ad-banner'),
+    ],
+    maskColor: '#FF00FF',
+  });
+});
+
+test('feed page with relative timestamps', async ({ page }) => {
+  await page.goto('/feed');
+
+  await expect(page).toHaveScreenshot('feed.png', {
+    mask: [page.locator('time[datetime]')],
+  });
+});
+
+test('profile page with user-generated content', async ({ page }) => {
+  await page.goto('/profile/test-user');
+
+  await expect(page).toHaveScreenshot('profile.png', {
+    mask: [
+      page.getByRole('img', { name: 'Profile photo' }),
+      page.getByTestId('last-login'),
+      page.getByTestId('member-since'),
+    ],
+  });
+});
+```
+
+**Alternative: freeze dynamic content with JavaScript**
+
+When masking is not sufficient (e.g., content affects layout), inject JavaScript to freeze the content:
+
+```typescript
+test('freeze clock before screenshot', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // Replace all dynamic timestamps with a fixed value
+  await page.evaluate(() => {
+    document.querySelectorAll('[data-testid="timestamp"]').forEach((el) => {
+      el.textContent = 'Jan 1, 2025 12:00 PM';
+    });
+  });
+
+  await expect(page).toHaveScreenshot('dashboard-frozen.png');
+});
+```
+
+### 5. Animations Handling
+
+**Use when**: Always. CSS animations and transitions are the number one cause of flaky visual diffs. A screenshot captured mid-animation will never match the baseline.
+**Avoid when**: You are explicitly testing the animation itself (rare).
+
+**TypeScript**
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('page renders without animation interference', async ({ page }) => {
+  await page.goto('/');
+
+  // Disables CSS animations and transitions before screenshotting
+  await expect(page).toHaveScreenshot('homepage.png', {
+    animations: 'disabled',
+  });
+});
+```
+
+**JavaScript**
+```javascript
+const { test, expect } = require('@playwright/test');
+
+test('page renders without animation interference', async ({ page }) => {
+  await page.goto('/');
+
+  await expect(page).toHaveScreenshot('homepage.png', {
+    animations: 'disabled',
+  });
+});
+```
+
+**Set globally** -- this should be the default for every project:
+
+```typescript
+// playwright.config.ts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  expect: {
+    toHaveScreenshot: {
+      animations: 'disabled',
+    },
+  },
+});
+```
+
+When `animations: 'disabled'` is set, Playwright:
+1. Injects a stylesheet that sets `* { animation-duration: 0s !important; transition-duration: 0s !important; }`.
+2. Waits for any currently running animations to finish (forces them to their end state).
+3. Takes the screenshot.
+
+For JavaScript-driven animations (requestAnimationFrame, GSAP, Framer Motion), you may also need to wait for stability:
+
+```typescript
+test('page with JS animations', async ({ page }) => {
+  await page.goto('/animated-landing');
+
+  // Wait for the hero animation to settle
+  await page.getByTestId('hero-section').waitFor({ state: 'visible' });
+  await page.waitForTimeout(500); // last resort for JS animations -- use sparingly
+
+  await expect(page).toHaveScreenshot('landing.png', {
+    animations: 'disabled',
+  });
+});
+```
+
+### 6. Updating Snapshots
+
+**Use when**: You have intentionally changed the UI and need to update the baselines. A design refresh, rebrand, new feature, or layout change.
+**Avoid when**: The diff is unexpected -- investigate the cause before blindly updating.
+
+```bash
+# Update all snapshots
+npx playwright test --update-snapshots
+
+# Update snapshots for a specific test file
+npx playwright test tests/homepage.spec.ts --update-snapshots
+
+# Update snapshots for a specific project (browser)
+npx playwright test --project=chromium --update-snapshots
+```
+
+**Workflow for reviewing snapshot changes:**
+
+1. Run tests and observe failures in the HTML report:
+   ```bash
+   npx playwright test
+   npx playwright show-report
+   ```
+   The report shows the expected image, actual image, and a diff image side-by-side.
+
+2. If the changes are intentional, update the snapshots:
+   ```bash
+   npx playwright test --update-snapshots
+   ```
+
+3. Review the updated snapshots in your diff tool before committing:
+   ```bash
+   git diff --name-only  # see which snapshot files changed
+   ```
+
+4. Commit the updated snapshots with a clear message explaining why they changed.
+
+**Tip**: Never run `--update-snapshots` in CI. Always update locally, review the diffs, and commit the new baselines.
+
+**TypeScript -- helper for controlled updates**
+```typescript
+import { test, expect } from '@playwright/test';
+
+// Tag visual tests so you can update them selectively
+test('homepage visual @visual', async ({ page }) => {
+  await page.goto('/');
+  await expect(page).toHaveScreenshot('homepage.png', {
+    animations: 'disabled',
+  });
+});
+
+test('pricing visual @visual', async ({ page }) => {
+  await page.goto('/pricing');
+  await expect(page).toHaveScreenshot('pricing.png', {
+    animations: 'disabled',
+  });
+});
+```
+
+```bash
+# Update only visual tests
+npx playwright test --grep @visual --update-snapshots
+```
+
+### 7. Cross-Browser Visual Testing
+
+**Use when**: Your users span Chrome, Firefox, and Safari and you need to verify rendering consistency per browser.
+**Avoid when**: Early stage projects targeting a single browser -- visual tests across three browsers triple the maintenance burden.
+
+Playwright automatically separates snapshots by project name. Each browser gets its own baseline file. This is correct behavior -- browsers render fonts, shadows, and anti-aliasing differently.
+
+**TypeScript**
+```typescript
+// playwright.config.ts
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './tests',
+  expect: {
+    toHaveScreenshot: {
+      animations: 'disabled',
+      maxDiffPixelRatio: 0.01,
+    },
+  },
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+    {
+      name: 'firefox',
+      use: { ...devices['Desktop Firefox'] },
+    },
+    {
+      name: 'webkit',
+      use: { ...devices['Desktop Safari'] },
+    },
+  ],
+});
+```
+
+```typescript
+// tests/homepage.spec.ts
+import { test, expect } from '@playwright/test';
+
+test('homepage renders correctly per browser', async ({ page }) => {
+  await page.goto('/');
+
+  // Playwright creates separate baselines per project:
+  //   homepage.spec.ts-snapshots/homepage-chromium-linux.png
+  //   homepage.spec.ts-snapshots/homepage-firefox-linux.png
+  //   homepage.spec.ts-snapshots/homepage-webkit-linux.png
+  await expect(page).toHaveScreenshot('homepage.png', {
+    animations: 'disabled',
+  });
+});
+```
+
+**JavaScript**
+```javascript
+const { test, expect } = require('@playwright/test');
+
+test('homepage renders correctly per browser', async ({ page }) => {
+  await page.goto('/');
+
+  await expect(page).toHaveScreenshot('homepage.png', {
+    animations: 'disabled',
+  });
+});
+```
+
+**Strategy for managing cross-browser snapshots**: Run visual tests in a single browser (Chromium on Linux in CI) to minimize snapshot count and only add other browsers when you have actual cross-browser rendering bugs. You can scope visual tests to one project:
+
+```typescript
+// playwright.config.ts
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  projects: [
+    {
+      name: 'visual',
+      testMatch: '**/*.visual.spec.ts',
+      use: { ...devices['Desktop Chrome'] },
+    },
+    {
+      name: 'chromium',
+      testIgnore: '**/*.visual.spec.ts',
+      use: { ...devices['Desktop Chrome'] },
+    },
+    {
+      name: 'firefox',
+      testIgnore: '**/*.visual.spec.ts',
+      use: { ...devices['Desktop Firefox'] },
+    },
+  ],
+});
+```
+
+### 8. Responsive Visual Testing
+
+**Use when**: Your application has responsive breakpoints and you need to verify layouts at different viewport sizes.
+**Avoid when**: The page has a single fixed-width layout.
+
+**TypeScript**
+```typescript
+import { test, expect } from '@playwright/test';
+
+const viewports = [
+  { name: 'mobile', width: 375, height: 812 },
+  { name: 'tablet', width: 768, height: 1024 },
+  { name: 'desktop', width: 1440, height: 900 },
+];
+
+for (const viewport of viewports) {
+  test(`homepage at ${viewport.name} (${viewport.width}x${viewport.height})`, async ({ page }) => {
+    await page.setViewportSize({ width: viewport.width, height: viewport.height });
+    await page.goto('/');
+
+    await expect(page).toHaveScreenshot(`homepage-${viewport.name}.png`, {
+      animations: 'disabled',
+      fullPage: true,
+    });
+  });
+}
+```
+
+**JavaScript**
+```javascript
+const { test, expect } = require('@playwright/test');
+
+const viewports = [
+  { name: 'mobile', width: 375, height: 812 },
+  { name: 'tablet', width: 768, height: 1024 },
+  { name: 'desktop', width: 1440, height: 900 },
+];
+
+for (const viewport of viewports) {
+  test(`homepage at ${viewport.name} (${viewport.width}x${viewport.height})`, async ({ page }) => {
+    await page.setViewportSize({ width: viewport.width, height: viewport.height });
+    await page.goto('/');
+
+    await expect(page).toHaveScreenshot(`homepage-${viewport.name}.png`, {
+      animations: 'disabled',
+      fullPage: true,
+    });
+  });
+}
+```
+
+**Alternative: use Playwright projects for responsive testing.**
+
+```typescript
+// playwright.config.ts
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  projects: [
+    {
+      name: 'desktop',
+      testMatch: '**/*.visual.spec.ts',
+      use: {
+        ...devices['Desktop Chrome'],
+        viewport: { width: 1440, height: 900 },
+      },
+    },
+    {
+      name: 'tablet',
+      testMatch: '**/*.visual.spec.ts',
+      use: {
+        ...devices['iPad (gen 7)'],
+      },
+    },
+    {
+      name: 'mobile',
+      testMatch: '**/*.visual.spec.ts',
+      use: {
+        ...devices['iPhone 14'],
+      },
+    },
+  ],
+});
+```
+
+This approach gives you separate snapshot folders per device and runs them in parallel.
+
+### 9. CI Setup for Visual Tests
+
+**Use when**: Running visual regression tests in CI. The critical requirement is consistent rendering -- the same test must produce the same screenshot every time.
+**Avoid when**: Never skip this. Visual tests without CI consistency are worthless.
+
+**The problem**: Font rendering, anti-aliasing, and sub-pixel rendering differ across operating systems. A snapshot taken on macOS will not match one taken on Linux. This is the most common source of visual test pain.
+
+**The solution**: Run visual tests inside Docker using the official Playwright container. Generate and update snapshots from the same container.
+
+**GitHub Actions with Docker**
+
+```yaml
+# .github/workflows/visual-tests.yml
+name: Visual Regression Tests
+on: [push, pull_request]
+
+jobs:
+  visual-tests:
+    runs-on: ubuntu-latest
+    container:
+      image: mcr.microsoft.com/playwright:v1.50.0-noble
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - run: npm ci
+
+      - name: Run visual tests
+        run: npx playwright test --project=visual
+        env:
+          HOME: /root  # required for Playwright in Docker
+
+      - uses: actions/upload-artifact@v4
+        if: failure()
+        with:
+          name: visual-test-report
+          path: playwright-report/
+          retention-days: 14
+```
+
+**Updating snapshots locally using Docker** -- so your local baselines match CI:
+
+```bash
+# Generate/update snapshots using the same container as CI
+docker run --rm -v $(pwd):/work -w /work \
+  mcr.microsoft.com/playwright:v1.50.0-noble \
+  npx playwright test --update-snapshots --project=visual
+```
+
+**Add a script to `package.json`** for convenience:
+
+```json
+{
+  "scripts": {
+    "test:visual": "npx playwright test --project=visual",
+    "test:visual:update": "docker run --rm -v $(pwd):/work -w /work mcr.microsoft.com/playwright:v1.50.0-noble npx playwright test --update-snapshots --project=visual"
+  }
+}
+```
+
+**Configure snapshots for Linux only** in your config:
+
+```typescript
+// playwright.config.ts
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  snapshotPathTemplate: '{testDir}/{testFileDir}/{testFileName}-snapshots/{arg}{-projectName}{ext}',
+  // Omits {-snapshotSuffix} which includes the platform name (linux, darwin, win32).
+  // This means snapshots are platform-agnostic -- you MUST generate them in Docker.
+  projects: [
+    {
+      name: 'visual',
+      testMatch: '**/*.visual.spec.ts',
+      use: { ...devices['Desktop Chrome'] },
+    },
+  ],
+});
+```
+
+### 10. Component Visual Testing
+
+**Use when**: Testing individual UI components in isolation -- buttons, cards, forms, modals. Faster than full-page screenshots, more stable, and easier to maintain.
+**Avoid when**: You need to verify interactions between multiple components or page-level layout.
+
+**TypeScript -- using Playwright component testing**
+```typescript
+// tests/components/button.visual.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Button component visual states', () => {
+  test('primary button', async ({ page }) => {
+    await page.goto('/storybook/iframe.html?id=button--primary');
+    const button = page.getByRole('button');
+    await expect(button).toHaveScreenshot('button-primary.png', {
+      animations: 'disabled',
+    });
+  });
+
+  test('primary button hover', async ({ page }) => {
+    await page.goto('/storybook/iframe.html?id=button--primary');
+    const button = page.getByRole('button');
+    await button.hover();
+    await expect(button).toHaveScreenshot('button-primary-hover.png', {
+      animations: 'disabled',
+    });
+  });
+
+  test('primary button disabled', async ({ page }) => {
+    await page.goto('/storybook/iframe.html?id=button--primary-disabled');
+    const button = page.getByRole('button');
+    await expect(button).toHaveScreenshot('button-primary-disabled.png', {
+      animations: 'disabled',
+    });
+  });
+
+  test('button sizes', async ({ page }) => {
+    for (const size of ['small', 'medium', 'large']) {
+      await page.goto(`/storybook/iframe.html?id=button--${size}`);
+      const button = page.getByRole('button');
+      await expect(button).toHaveScreenshot(`button-${size}.png`, {
+        animations: 'disabled',
+      });
+    }
+  });
+});
+```
+
+**JavaScript**
+```javascript
+const { test, expect } = require('@playwright/test');
+
+test.describe('Button component visual states', () => {
+  test('primary button', async ({ page }) => {
+    await page.goto('/storybook/iframe.html?id=button--primary');
+    const button = page.getByRole('button');
+    await expect(button).toHaveScreenshot('button-primary.png', {
+      animations: 'disabled',
+    });
+  });
+
+  test('primary button hover', async ({ page }) => {
+    await page.goto('/storybook/iframe.html?id=button--primary');
+    const button = page.getByRole('button');
+    await button.hover();
+    await expect(button).toHaveScreenshot('button-primary-hover.png', {
+      animations: 'disabled',
+    });
+  });
+
+  test('primary button disabled', async ({ page }) => {
+    await page.goto('/storybook/iframe.html?id=button--primary-disabled');
+    const button = page.getByRole('button');
+    await expect(button).toHaveScreenshot('button-primary-disabled.png', {
+      animations: 'disabled',
+    });
+  });
+
+  test('button sizes', async ({ page }) => {
+    for (const size of ['small', 'medium', 'large']) {
+      await page.goto(`/storybook/iframe.html?id=button--${size}`);
+      const button = page.getByRole('button');
+      await expect(button).toHaveScreenshot(`button-${size}.png`, {
+        animations: 'disabled',
+      });
+    }
+  });
+});
+```
+
+**Using a dedicated visual test page** instead of Storybook:
+
+```typescript
+// tests/components/card.visual.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Card component', () => {
+  test.beforeEach(async ({ page }) => {
+    // Navigate to a page that renders the component in isolation
+    await page.goto('/test-harness/card');
+  });
+
+  test('default state', async ({ page }) => {
+    await expect(page.getByTestId('card')).toHaveScreenshot('card-default.png', {
+      animations: 'disabled',
+    });
+  });
+
+  test('with long content truncates correctly', async ({ page }) => {
+    await page.goto('/test-harness/card?content=long');
+    await expect(page.getByTestId('card')).toHaveScreenshot('card-long-content.png', {
+      animations: 'disabled',
+    });
+  });
+
+  test('error state', async ({ page }) => {
+    await page.goto('/test-harness/card?state=error');
+    await expect(page.getByTestId('card')).toHaveScreenshot('card-error.png', {
+      animations: 'disabled',
+    });
+  });
+});
+```
+
+### 11. Asserting Pseudo-Element Styles Instead of a Screenshot (Playwright 1.60+)
+
+**Use when**: You only care about one or two computed styles on a `::before` / `::after` pseudo-element (an icon glyph, a required asterisk, a status dot color). A targeted CSS assertion is faster and far less brittle than a pixel diff.
+**Avoid when**: The thing you're verifying is genuinely visual (layout, gradients, shadows). Keep using `toHaveScreenshot()` there.
+
+Playwright 1.60's `pseudo` option on `toHaveCSS()` lets you check pseudo-element styles without a screenshot baseline to maintain:
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('status badge renders a green dot via ::before', async ({ page }) => {
+  await page.goto('/orders');
+
+  const badge = page.getByTestId('status-online');
+  // No snapshot file to update — assert the computed style directly
+  await expect(badge).toHaveCSS('background-color', 'rgb(22, 163, 74)', { pseudo: '::before' });
+});
+```
+
+This complements visual snapshots: use it to lock down specific pseudo-element styling that would otherwise force a full screenshot. See [core/assertions-and-waiting.md](assertions-and-waiting.md#asserting-pseudo-element-styles-tohavecss-pseudo-playwright-160).
+
+## Decision Guide
+
+| Scenario | Recommended Approach | Why |
+|---|---|---|
+| Key landing pages, marketing site | Full page screenshot, `fullPage: true` | Catches layout shifts, spacing, and overall visual harmony |
+| Individual UI components (buttons, cards, modals) | Element screenshot on the component | Isolated, fast, stable -- immune to unrelated page changes |
+| Page with dynamic content (timestamps, live data) | Full page + `mask` on dynamic elements | Covers layout while ignoring volatile content |
+| Design system component library | Element screenshot per variant, zero threshold | Pixel-perfect enforcement for shared components |
+| Responsive layout verification | Screenshot per viewport (loop or projects) | Catches breakpoint bugs at mobile/tablet/desktop |
+| Cross-browser rendering consistency | Separate snapshots per browser project | Browsers render fonts and shadows differently |
+| CI pipeline | Docker container (Playwright image), Linux-only snapshots | Consistent rendering, no OS-dependent diffs |
+| Pixel threshold: design system | `threshold: 0`, `maxDiffPixels: 0` | Zero tolerance for component library |
+| Pixel threshold: content pages | `maxDiffPixelRatio: 0.01`, `threshold: 0.2` | Allows minor anti-aliasing variance |
+| Pixel threshold: charts and graphs | `maxDiffPixels: 200`, `threshold: 0.3` | Anti-aliasing on curves varies across runs |
+| Visual tests add value | Stable pages, design systems, post-refactor verification | Clear baseline, predictable content |
+| Visual tests are noise | Highly dynamic pages, real-time dashboards, A/B test pages | Content changes on every load, diffs are meaningless |
+
+## Anti-Patterns
+
+| Don't Do This | Problem | Do This Instead |
+|---|---|---|
+| Visual testing every page in the app | Massive snapshot maintenance, constant false failures, team ignores results | Pick 5-10 key pages and critical components. Quality over quantity. |
+| Not masking dynamic content (timestamps, avatars, counters) | Screenshots differ on every run. Tests are permanently flaky. | Use `mask` option for all dynamic elements. Audit pages for volatility before adding visual tests. |
+| Running visual tests across macOS, Linux, and Windows | Font rendering differs per OS. Snapshots never match cross-platform. | Standardize on Linux via Docker. Generate and run snapshots in the same Playwright Docker container. |
+| Not using Docker in CI for visual tests | CI runner OS updates, font changes, or library upgrades silently shift rendering. | Pin a specific Playwright Docker image version. Update intentionally. |
+| Updating snapshots blindly with `--update-snapshots` | Accepts unintentional regressions. The baseline becomes wrong. | Always review the diff in the HTML report first. Understand why the snapshot changed. |
+| Skipping `animations: 'disabled'` | CSS transitions and keyframe animations create random diffs. One of the top causes of flaky visual tests. | Set `animations: 'disabled'` globally in config. |
+| Using visual tests instead of functional assertions | Screenshot diffs do not tell you *what* broke -- just that *something* looks different. Slow to debug. | Use functional assertions (`toHaveText`, `toBeVisible`) for behavior. Visual tests complement, never replace. |
+| Committing snapshots generated on different platforms | The repo has macOS snapshots from dev A, Linux snapshots from dev B. Tests fail for everyone. | All team members generate snapshots using the same Docker container. Add a `test:visual:update` script. |
+| Setting threshold too high (e.g., `maxDiffPixelRatio: 0.1`) | 10% of pixels can change and the test still passes. Defeats the purpose. | Start with `0.01` (1%) and adjust per-test if needed. |
+| Full page screenshots on pages with infinite scroll or lazy loading | Page height is nondeterministic. Screenshots vary by load timing. | Use element screenshots on the above-the-fold content, or scroll to a deterministic state first. |
+
+## Troubleshooting
+
+### "Screenshot comparison failed" on first CI run after local development
+
+**Cause**: Snapshots were generated on macOS (or Windows) locally. CI runs on Linux. Font rendering differs between operating systems, so every pixel comparison fails.
+
+**Fix**: Generate snapshots using Docker locally so they match CI:
+
+```bash
+docker run --rm -v $(pwd):/work -w /work \
+  mcr.microsoft.com/playwright:v1.50.0-noble \
+  npx playwright test --update-snapshots --project=visual
+```
+
+Commit the Linux-generated snapshots. Never commit macOS-generated snapshots if CI runs on Linux.
+
+### "Expected screenshot to match but X pixels differ"
+
+**Cause**: Minor rendering differences from anti-aliasing, font hinting, or sub-pixel rendering. Common with text-heavy pages and curved shapes (charts, rounded corners).
+
+**Fix**: Add a small tolerance:
+
+```typescript
+await expect(page).toHaveScreenshot('page.png', {
+  maxDiffPixelRatio: 0.01,  // allow 1% variance
+  threshold: 0.2,           // per-pixel color tolerance
+});
+```
+
+If the diff is larger, check the HTML report. Look at the diff image to determine if the change is a real regression or rendering noise.
+
+### Visual tests pass locally but fail in CI (even with Docker)
+
+**Cause**: Different Playwright versions locally vs CI. The Docker image pins a specific Playwright version. If your local `@playwright/test` is newer, the rendering engine may differ.
+
+**Fix**: Ensure the Playwright version in `package.json` matches the Docker image tag:
+
+```json
+{
+  "devDependencies": {
+    "@playwright/test": "1.50.0"
+  }
+}
+```
+
+```yaml
+# CI config
+container:
+  image: mcr.microsoft.com/playwright:v1.50.0-noble  # must match
+```
+
+### Animations cause random diff failures
+
+**Cause**: CSS animations or transitions captured mid-frame. The screenshot is taken at a non-deterministic point in the animation timeline.
+
+**Fix**: Set `animations: 'disabled'` globally:
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+  expect: {
+    toHaveScreenshot: {
+      animations: 'disabled',
+    },
+  },
+});
+```
+
+For JavaScript-driven animations, wait for a stable state before screenshotting. As a last resort, use `page.waitForTimeout(300)` after the animation trigger.
+
+### Snapshot file names conflict between tests
+
+**Cause**: Two tests in different files use the same screenshot name (`'homepage.png'`) without unique file paths.
+
+**Fix**: Playwright includes the test file name in the snapshot path by default. If you still have conflicts, use explicit unique names:
+
+```typescript
+await expect(page).toHaveScreenshot('auth-homepage.png');   // in auth.spec.ts
+await expect(page).toHaveScreenshot('public-homepage.png'); // in public.spec.ts
+```
+
+Or customize the snapshot path template in config:
+
+```typescript
+export default defineConfig({
+  snapshotPathTemplate: '{testDir}/{testFileDir}/{testFileName}-snapshots/{arg}{-projectName}{ext}',
+});
+```
+
+### Too many snapshot files to maintain
+
+**Cause**: Visual tests for every page, every browser, every viewport. The snapshot count explodes.
+
+**Fix**: Be selective. Visual test only pages where visual regressions are high-risk:
+- Landing pages and marketing pages
+- Design system components
+- Complex layouts (dashboards, data tables)
+- Pages after a major refactor
+
+Skip pages where functional assertions already cover the key elements. A `toHaveText` and `toBeVisible` check is often enough.
+
+## Related
+
+- [core/assertions-and-waiting.md](assertions-and-waiting.md) -- `toHaveScreenshot()` is a web-first assertion and follows the same retry semantics
+- [core/configuration.md](configuration.md) -- global screenshot config, project setup, `snapshotPathTemplate`
+- [core/mobile-and-responsive.md](mobile-and-responsive.md) -- responsive viewport testing patterns
+- [ci/docker-and-containers.md](../ci/docker-and-containers.md) -- Docker setup for consistent rendering
+- [ci/ci-github-actions.md](../ci/ci-github-actions.md) -- CI pipeline configuration for visual tests