Playwrightビジュアルリグレッションテスト&ピクセルマッチガイド

// Example: Basic visual regression test assertion in Playwright
import { test, expect } from '@playwright/test';

test('verify landing page visual layout matches baseline snapshot', async ({ page }) => {
  await page.goto('https://app.example.com');
  await page.waitForLoadState('networkidle');
  
  // Mask changing elements like animated carousels and timestamps
  await expect(page).toHaveScreenshot('landing-page-baseline.png', {
    mask: [page.locator('.hero-carousel-timer'), page.locator('.user-avatar')],
    fullPage: true,
    maxDiffPixelRatio: 0.01, // Allow 1% pixel variance across full viewport
  });
});

// Advanced snapshot comparison configuration in playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  expect: {
    toHaveScreenshot: {
      threshold: 0.2, // Individual pixel color delta threshold (0.0 to 1.0)
      maxDiffPixels: 50, // Absolute pixel count diff limit
      maxDiffPixelRatio: 0.005, // Ratio diff limit (0.5% of total image area)
      animations: 'disabled', // Automatically pause CSS animations and transitions
      caret: 'hide', // Hide blinking text input carets
      scale: 'css', // Render screenshots at CSS pixel resolution rather than physical device DPI
    },
  },
  use: {
    viewport: { width: 1280, height: 720 },
    deviceScaleFactor: 1, // Enforce 1x scale factor to prevent Retina display pixel mismatches
  },
});

// Custom reporter for visual snapshot diff diagnostics
import { Reporter, TestCase, TestResult } from '@playwright/test/reporter';

class VisualDiffReporter implements Reporter {
  onTestEnd(test: TestCase, result: TestResult) {
    if (result.status === 'failed') {
      const visualErrors = result.errors.filter(e => e.message?.includes('Screenshot comparison failed'));
      if (visualErrors.length > 0) {
        console.log(`Visual regression failure detected in test: ${test.title}`);
        console.log(`Inspect visual diff artifacts in test-results folder.`);
      }
    }
  }
}

export default VisualDiffReporter;

// Example: Component-level visual regression with explicit threshold tuning
import { test, expect } from '@playwright/test';

test('verify checkout button hover state visual fidelity', async ({ page }) => {
  await page.goto('https://app.example.com/checkout');
  const payButton = page.locator('button#pay-now');
  
  await payButton.hover();
  await expect(payButton).toHaveScreenshot('pay-button-hover.png', {
    threshold: 0.1, // Strict color matching for brand button background gradients
    maxDiffPixels: 10, // Limit allowed pixel delta to minor border anti-aliasing
  });
});

// Custom Playwright test fixture for custom threshold override per viewport
import { test as baseTest, expect } from '@playwright/test';

export const test = baseTest.extend({
  assertVisualMatch: [async ({ page }, use) => {
    const customMatch = async (name: string, maxRatio = 0.005) => {
      await expect(page).toHaveScreenshot(name, {
        maxDiffPixelRatio: maxRatio,
        stylePath: './e2e/styles/visual-test-overrides.css', // Inject custom CSS to hide changing elements
      });
    };
    await use(customMatch);
  }, { auto: false }],
});

// Responsive viewport visual testing matrix configuration
export const responsiveProjects = [
  {
    name: 'mobile-chrome',
    use: { viewport: { width: 375, height: 667 }, deviceScaleFactor: 2 },
  },
  {
    name: 'tablet-chrome',
    use: { viewport: { width: 768, height: 1024 }, deviceScaleFactor: 1 },
  },
  {
    name: 'desktop-chrome',
    use: { viewport: { width: 1440, height: 900 }, deviceScaleFactor: 1 },
  },
];

# Running Playwright visual regression tests inside Docker locally to match CI
docker run --rm -it \
  -v $(pwd):/work \
  -w /work \
  mcr.microsoft.com/playwright:v1.44.0-jammy \
  npx playwright test --update-snapshots

// Injecting CSS rules to freeze web fonts and hide changing elements during visual tests
import { test, expect } from '@playwright/test';

test.beforeEach(async ({ page }) => {
  // Inject global CSS overrides before taking visual snapshots
  await page.addInitScript(() => {
    const style = document.createElement('style');
    style.innerHTML = `
      *, *::before, *::after {
        animation-duration: 0s !important;
        animation-delay: 0s !important;
        transition-duration: 0s !important;
        transition-delay: 0s !important;
      }
      /* Hide live chat bubbles and date elements */
      .live-chat-bubble, .realtime-date-display {
        visibility: hidden !important;
      }
    `;
    document.head.appendChild(style);
  });
});

// Helper utility to wait for all web fonts to load prior to screenshot capture
export async function waitForFontsLoaded(page: import('@playwright/test').Page) {
  await page.evaluate(async () => {
    await document.fonts.ready;
  });
}

// Standardizing device scale factor across developer machines
export const visualContextOptions = {
  deviceScaleFactor: 1,
  hasTouch: false,
  isMobile: false,
  javaScriptEnabled: true,
};

# GitHub Actions workflow for automated visual regression test reporting
name: Visual Regression Tests
on: [pull_request]

jobs:
  visual-test:
    runs-on: ubuntu-latest
    container:
      image: mcr.microsoft.com/playwright:v1.44.0-jammy
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'
      - name: Install Dependencies
        run: npm ci
      - name: Run Playwright Visual Tests
        run: npx playwright test --project=chromium
      - name: Upload Visual Diff Artifacts on Failure
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: playwright-visual-diffs
          path: test-results/
          retention-days: 7

// Masking complex changing UI elements like maps and embedded video frames
import { test, expect } from '@playwright/test';

test('verify dashboard layout with masked changing elements', async ({ page }) => {
  await page.goto('https://app.example.com/analytics');
  
  // Locate changing elements that alter content on every page load
  const liveStockTicker = page.locator('.stock-ticker-stream');
  const userNotificationBadge = page.locator('.notification-count');
  
  await expect(page).toHaveScreenshot('analytics-dashboard.png', {
    mask: [liveStockTicker, userNotificationBadge],
    maskColor: '#FF00FF', // Custom magenta color for masked regions in diff outputs
  });
});

// Masking strategy for HTML canvas elements and data charts
export async function maskCanvasElements(page: import('@playwright/test').Page) {
  const chartLocators = page.locator('canvas.recharts-surface');
  const count = await chartLocators.count();
  const locatorsArray = [];
  
  for (let i = 0; i < count; i++) {
    locatorsArray.push(chartLocators.nth(i));
  }
  
  return locatorsArray;
}

// Script: Automating local visual snapshot updates in Docker environment
import { execSync } from 'child_process';

function updateVisualSnapshots() {
  console.log('Updating visual baseline snapshots inside Docker container...');
  
  const dockerCmd = `docker run --rm -v ${process.cwd()}:/work -w /work mcr.microsoft.com/playwright:v1.44.0-jammy npx playwright test --update-snapshots`;
  
  try {
    execSync(dockerCmd, { stdio: 'inherit' });
    console.log('Visual snapshots updated successfully. Inspect Git diff before committing.');
  } catch (error) {
    console.error('Failed to update visual snapshots.');
    process.exit(1);
  }
}

updateVisualSnapshots();