Playwright大規模ビジュアルリグレッションテスト: Dockerベースライン、Pixelmatch、不安定なCIからの保護

# Dockerfile for Playwright VRT baseline generation and CI execution
FROM mcr.microsoft.com/playwright/chromium:v1.45.0-jammy

# Set working directory
WORKDIR /app

# Install pnpm globally
RUN npm install -g pnpm

# Copy package.json and pnpm-lock.yaml for dependency installation
COPY package.json pnpm-lock.yaml ./
# If using Turborepo, copy workspace root package.json and pnpm-workspace.yaml
# COPY pnpm-workspace.yaml ./
# COPY apps/web/package.json apps/web/
# COPY packages/ui/package.json packages/ui/

# Install dependencies
# For Turborepo, you might need to install dependencies at the root
# RUN pnpm install --frozen-lockfile
# Or, if installing within a specific app/package:
# RUN pnpm install --frozen-lockfile --filter=@your-org/web

# Copy the rest of the application code
COPY . .

# Expose any ports if your application needs to run inside the container
# For VRT, typically the app runs externally, and Playwright connects to it.
# EXPOSE 3000

# Define a default command (optional, can be overridden)
CMD ["pnpm", "test:visual"]

docker build -t playwright-vrt-env .

# Example: Running Playwright tests to update baselines
# Assuming your Playwright config points to 'test-results' for diffs
# and 'screenshots' for baselines.
docker run --rm -v "$(pwd):/app" playwright-vrt-env pnpm playwright test --update-snapshots

// playwright.config.ts
import { defineConfig, devices } from '@playwright/test';
import path from 'path';

// Determine if running in CI
const isCI = !!process.env.CI;

export default defineConfig({
  testDir: './e2e', // Directory where your visual tests reside
  outputDir: './test-results', // Directory for test artifacts (screenshots, videos, traces)
  snapshotDir: './e2e/snapshots', // Directory for baseline screenshots

  fullyParallel: true, // Run tests in parallel
  forbidOnly: isCI, // Forbid .only in CI
  retries: isCI ? 2 : 0, // Retry tests in CI to mitigate flakiness
  workers: process.env.CI ? 1 : undefined, // Limit workers in CI for stability, or use all available

  reporter: 'html', // Use HTML reporter for easy review

  use: {
    baseURL: 'http://localhost:3000', // Base URL of your application under test
    trace: 'on-first-retry', // Capture trace on first retry failure
    screenshot: 'only-on-failure', // Only capture screenshots on failure
    video: 'on-first-retry', // Capture video on first retry failure

    // Playwright's default browser context options
    // Ensure consistent viewport for screenshots
    viewport: { width: 1280, height: 720 },

    // Emulate a consistent color scheme
    colorScheme: 'light',

    // Use a consistent timezone to prevent date/time rendering differences
    timezoneId: 'America/Los_Angeles',

    // Use a consistent locale
    locale: 'en-US',

    // Use a consistent user agent for consistent font rendering
    userAgent: 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36',

    // Playwright's default browser options
    // headless: true, // Always run headless in CI
  },

  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },
    // Add other browsers if needed, but for VRT, consistency is key.
    // Often, one browser (e.g., Chromium) is sufficient for visual baselines.
  ],

  // Web server to run before tests.
  // This assumes your app is a Next.js app running on port 3000.
  webServer: {
    command: 'pnpm --filter=@your-org/web dev', // Command to start your web app
    url: 'http://localhost:3000',
    reuseExistingServer: !isCI, // Reuse server locally, but start fresh in CI
    timeout: 60 * 1000, // 60 seconds timeout for server to start
  },
});

// e2e/home.spec.ts
import { test, expect } from '@playwright/test';

test.describe('Home Page Visual Regression', () => {
  test('should match the home page screenshot', async ({ page }) => {
    await page.goto('/');

    // Mask dynamic elements like timestamps, user avatars, or ads
    // This prevents false positives due to content changes.
    await page.locator('.dynamic-timestamp').evaluate(node => node.style.visibility = 'hidden');
    await page.locator('.user-avatar').evaluate(node => node.style.visibility = 'hidden');

    // Wait for fonts to load, if applicable, to prevent FOUT/FOIT issues
    await page.waitForLoadState('networkidle');

    // Take a full page screenshot
    await expect(page).toHaveScreenshot('home-page.png', {
      fullPage: true,
      maxDiffPixelRatio: 0.01, // Allow 1% of pixels to differ
      threshold: 0.1, // Pixelmatch threshold (0-1, lower is stricter)
      // You can also specify a custom diff algorithm if needed,
      // but Playwright's default (based on pixelmatch) is usually sufficient.
      // diffPixels: 100, // Max number of differing pixels
    });
  });

  test('should match the login form screenshot', async ({ page }) => {
    await page.goto('/login');

    // Mask the input field for password, as its content might be dynamic (e.g., autofill)
    await page.locator('input[type="password"]').evaluate(node => node.style.visibility = 'hidden');

    await page.waitForLoadState('networkidle');

    await expect(page).toHaveScreenshot('login-form.png', {
      maxDiffPixelRatio: 0.02, // Slightly more lenient for forms
      threshold: 0.05,
      // You can also specify a specific region to screenshot
      // clip: { x: 0, y: 0, width: 800, height: 600 },
    });
  });
});

// Using mask option
await expect(page).toHaveScreenshot('home-page.png', {
  mask: [
    page.locator('.dynamic-timestamp'),
    page.locator('.user-avatar'),
  ],
  maxDiffPixelRatio: 0.01,
});

// package.json (root)
{
  "name": "my-monorepo",
  "private": true,
  "workspaces": [
    "apps/*",
    "packages/*"
  ],
  "scripts": {
    "test:visual": "pnpm --filter=@your-org/e2e test",
    "test:visual:update": "pnpm --filter=@your-org/e2e test --update-snapshots"
  }
}

// apps/e2e/package.json
{
  "name": "@your-org/e2e",
  "version": "0.0.0",
  "private": true,
  "scripts": {
    "test": "playwright test",
    "test:ci": "playwright test --reporter=github --forbid-only --retries=2"
  },
  "devDependencies": {
    "@playwright/test": "^1.45.0",
    "@types/node": "^20.14.9"
  }
}

# .github/workflows/visual-regression.yml
name: Visual Regression Tests

on:
  pull_request:
    branches:
      - main
  push:
    branches:
      - main

jobs:
  visual-regression:
    runs-on: ubuntu-latest
    container:
      # Use the same Docker image as for baseline generation
      image: mcr.microsoft.com/playwright/chromium:v1.45.0-jammy
      options: --user 0:0 # Run as root inside container for permissions

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup pnpm
        uses: pnpm/action-setup@v3
        with:
          version: 8
          run_install: false # We'll run install manually in the container

      - name: Get pnpm store directory
        shell: bash
        run: |
          echo "PNPM_CACHE_DIR=$(pnpm store path)" >> $GITHUB_ENV

      - name: Cache pnpm dependencies
        uses: actions/cache@v4
        with:
          path: ${{ env.PNPM_CACHE_DIR }}
          key: ${{ runner.os }}-pnpm-${{ hashFiles('**/pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-pnpm-

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      - name: Build application (if necessary)
        # Replace with your actual build command for the app under test
        run: pnpm --filter=@your-org/web build

      - name: Run Playwright Visual Regression Tests
        run: pnpm --filter=@your-org/e2e test:ci

      - name: Upload Playwright Test Report
        if: always() # Upload even if tests fail
        uses: actions/upload-artifact@v4
        with:
          name: playwright-report
          path: playwright-report/
          retention-days: 30

      - name: Upload Playwright Test Results (screenshots, videos, traces)
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: playwright-test-results
          path: test-results/
          retention-days: 30

// Example of mocking API response
await page.route('**/api/users/*', async route => {
  await route.fulfill({
    status: 200,
    contentType: 'application/json',
    body: JSON.stringify({ name: 'Test User', avatar: 'mock-avatar.png' }),
  });
});
await page.goto('/profile');
await expect(page).toHaveScreenshot('profile-page.png');

/* In your app's test CSS or a global style */
body.test-env * {
  transition: none !important;
  animation: none !important;
}

// playwright.config.ts
projects: [
  {
    name: 'chromium-desktop',
    use: { ...devices['Desktop Chrome'], viewport: { width: 1280, height: 720 } },
  },
  {
    name: 'chromium-mobile',
    use: { ...devices['Pixel 5'], viewport: { width: 390, height: 844 } }, // Example mobile viewport
  },
],