import { test, expect } from '@playwright/test';

test('user can complete checkout', async ({ page }) => {
  await page.goto('/products');
  await page.getByRole('button', { name: 'Add to cart' }).click();
  await page.getByRole('link', { name: 'Checkout' }).click();
  await page.getByLabel('Email').fill('test@example.com');
  await page.getByRole('button', { name: 'Submit' }).click();
  await expect(page.getByRole('heading', { name: 'Order confirmed' })).toBeVisible();
});

const checkout = new CheckoutPage(page);
await checkout.fillEmail('test@example.com');
await checkout.submit();
await checkout.expectConfirmation();

npx playwright init-agents --loop=claude    # For Claude Code

import AxeBuilder from '@axe-core/playwright';

test('page meets WCAG 2.2 AA', async ({ page }) => {
  await page.goto('/');
  const results = await new AxeBuilder({ page })
    .withTags(['wcag2a', 'wcag2aa', 'wcag22aa'])
    .analyze();
  expect(results.violations).toEqual([]);
});

await expect(page).toHaveScreenshot('checkout-page.png', {
  maxDiffPixels: 100,
  mask: [page.locator('.dynamic-content')],
});

import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';

test('page has no a11y violations', async ({ page }) => {
  await page.goto('/');
  const results = await new AxeBuilder({ page })
    .withTags(['wcag2a', 'wcag2aa', 'wcag22aa'])
    .analyze();
  expect(results.violations).toEqual([]);
});

test('modal state has no violations', async ({ page }) => {
  await page.goto('/');
  await page.click('[data-testid="open-modal"]');
  await page.waitForSelector('[role="dialog"]');

  const results = await new AxeBuilder({ page })
    .include('[role="dialog"]')
    .withTags(['wcag2a', 'wcag2aa'])
    .analyze();
  expect(results.violations).toEqual([]);
});

test('page has no violations', async ({ page }) => {
  await page.goto('/');
  const results = await new AxeBuilder({ page }).analyze();
  expect(results.violations).toEqual([]);
});

test('page meets WCAG 2.2 AA', async ({ page }) => {
  await page.goto('/');
  const results = await new AxeBuilder({ page })
    .withTags(['wcag2a', 'wcag2aa', 'wcag22aa'])
    .analyze();
  expect(results.violations).toEqual([]);
});

# .github/workflows/accessibility.yml
name: Accessibility
on: [pull_request]

jobs:
  a11y:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20', cache: 'npm' }
      - run: npm ci
      - run: npm run test:a11y
      - run: npm run build
      - run: npx playwright install --with-deps chromium
      - run: npm start & npx wait-on http://localhost:3000
      - run: npx playwright test e2e/accessibility

// BAD: Excluding too much
new AxeBuilder({ page })
  .exclude('body')  // Defeats the purpose
  .analyze();

// BAD: No CI enforcement
// Accessibility tests exist but don't block PRs

// BAD: Manual-only testing
// Relying solely on human review

# .github/workflows/test.yml
- run: npm run test:a11y  # Runs but doesn't block on failures
- run: npm run test:unit

# .github/workflows/accessibility.yml
on: [pull_request]
jobs:
  a11y:
    runs-on: ubuntu-latest
    steps:
      - run: npm run test:a11y  # Exits with code 1 on violations
      - run: npx playwright test e2e/accessibility  # Blocks merge

// jest.setup.ts
import { toHaveNoViolations } from 'jest-axe';
expect.extend(toHaveNoViolations);

import { render } from '@testing-library/react';
import { axe } from 'jest-axe';

it('has no a11y violations', async () => {
  const { container } = render(<Button>Click me</Button>);
  expect(await axe(container)).toHaveNoViolations();
});

// BAD: Disabling rules globally
const results = await axe(container, {
  rules: { 'color-contrast': { enabled: false } }  // NEVER disable rules
});

// BAD: Only testing happy path
it('form is accessible', async () => {
  const { container } = render(<Form />);
  expect(await axe(container)).toHaveNoViolations();
  // Missing: error state, loading state, disabled state
});

it('form is accessible', async () => {
  const { container } = render(<LoginForm />);
  expect(await axe(container)).toHaveNoViolations();
  // Missing: error, loading, disabled states
});

it('form is accessible in all states', async () => {
  const { container, rerender } = render(<LoginForm />);
  expect(await axe(container)).toHaveNoViolations();

  rerender(<LoginForm error="Invalid email" />);
  expect(await axe(container)).toHaveNoViolations();

  rerender(<LoginForm loading={true} />);
  expect(await axe(container)).toHaveNoViolations();
});

npx playwright init-agents --loop=claude    # For Claude Code
npx playwright init-agents --loop=vscode    # For VS Code (v1.105+)
npx playwright init-agents --loop=opencode  # For OpenCode

1. PLANNER   --> Explores app --> Creates specs/checkout.md
                 (uses seed.spec.ts)
2. GENERATOR --> Reads spec --> Tests live app --> Outputs tests/checkout.spec.ts
                 (verifies selectors actually work)
3. HEALER    --> Runs tests --> Fixes failures --> Updates selectors/waits
                 (self-healing)

// .mcp.json in project root
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

// Missing tests/seed.spec.ts
// AI agents have no example to understand app structure
npx playwright init-agents --loop=claude

// tests/seed.spec.ts
import { test } from '@playwright/test';

test('example checkout flow', async ({ page }) => {
  await page.goto('/');
  await page.getByRole('button', { name: 'Add to cart' }).click();
  await page.getByRole('link', { name: 'Checkout' }).click();
  // Agents learn selectors and patterns from this
});

// pages/CheckoutPage.ts
import { Page, Locator } from '@playwright/test';

export class CheckoutPage {
  readonly page: Page;
  readonly emailInput: Locator;
  readonly submitButton: Locator;
  readonly confirmationHeading: Locator;

  constructor(page: Page) {
    this.page = page;
    this.emailInput = page.getByLabel('Email');
    this.submitButton = page.getByRole('button', { name: 'Submit' });
    this.confirmationHeading = page.getByRole('heading', { name: 'Order confirmed' });
  }

  async fillEmail(email: string) {
    await this.emailInput.fill(email);
  }

  async submit() {
    await this.submitButton.click();
  }

  async expectConfirmation() {
    await expect(this.confirmationHeading).toBeVisible();
  }
}

// Capture and compare visual snapshots
await expect(page).toHaveScreenshot('checkout-page.png', {
  maxDiffPixels: 100,
  mask: [page.locator('.dynamic-content')],
});

test('checkout flow', async ({ page }) => {
  await page.getByLabel('Email').fill('test@example.com');
  await page.getByRole('button', { name: 'Submit' }).click();
});

test('another checkout test', async ({ page }) => {
  await page.getByLabel('Email').fill('user@example.com');  // Duplicated
  await page.getByRole('button', { name: 'Submit' }).click();  // Duplicated
});

const checkout = new CheckoutPage(page);
await checkout.fillEmail('test@example.com');
await checkout.submit();
await checkout.expectConfirmation();

// PREFERRED: Role-based locators (most resilient)
await page.getByRole('button', { name: 'Add to cart' }).click();
await page.getByRole('link', { name: 'Checkout' }).click();

// GOOD: Label-based for form controls
await page.getByLabel('Email').fill('test@example.com');

// ACCEPTABLE: Test IDs for stable anchors
await page.getByTestId('checkout-button').click();

// AVOID: CSS selectors and XPath (fragile)

import { test, expect } from '@playwright/test';

test('user can complete checkout', async ({ page }) => {
  await page.goto('/products');
  await page.getByRole('button', { name: 'Add to cart' }).click();
  await page.getByRole('link', { name: 'Checkout' }).click();
  await page.getByLabel('Email').fill('test@example.com');
  await page.getByRole('button', { name: 'Submit' }).click();
  await expect(page.getByRole('heading', { name: 'Order confirmed' })).toBeVisible();
});

// Flaky test detection
export default defineConfig({ failOnFlakyTests: true });

// Assert individual class names
await expect(page.locator('.card')).toContainClass('highlighted');

// IndexedDB storage state
await page.context().storageState({ path: 'auth.json', indexedDB: true });

// NEVER use hardcoded waits
await page.waitForTimeout(2000);

// NEVER use CSS selectors for user interactions
await page.click('.submit-btn');

// ALWAYS use semantic locators + auto-wait
await page.getByRole('button', { name: 'Submit' }).click();
await expect(page.getByRole('alert')).toBeVisible();

await page.click('.submit-button');
await page.waitForTimeout(2000);
await expect(page.locator('.success-message')).toBeVisible();

await page.getByRole('button', { name: 'Submit' }).click();
await expect(page.getByRole('alert', { name: /success/i })).toBeVisible();

// Manual type definitions that can drift from schema
interface User {
  id: string
  name: string
  // Missing 'email' field that database has
}

// No type connection between client and server
const response = await fetch('/api/users')
const users = await response.json() // type: any

import { initTRPC } from '@trpc/server'
import { z } from 'zod'

const t = initTRPC.create()

export const appRouter = t.router({
  getUser: t.procedure
    .input(z.object({ id: z.string() }))
    .query(async ({ input }) => {
      return await db.user.findUnique({ where: { id: input.id } })
    }),

  createUser: t.procedure
    .input(z.object({ email: z.string().email(), name: z.string() }))
    .mutation(async ({ input }) => {
      return await db.user.create({ data: input })
    })
})

export type AppRouter = typeof appRouter
// Client gets full type inference from server without code generation

from typing import NewType
from uuid import UUID
from pydantic import BaseModel, EmailStr

AnalysisID = NewType("AnalysisID", UUID)
ArtifactID = NewType("ArtifactID", UUID)

def delete_analysis(id: AnalysisID) -> None: ...
delete_analysis(artifact_id)  # Error with mypy/ty

class CreateUserRequest(BaseModel):
    email: EmailStr
    name: str = Field(min_length=2, max_length=100)

# Type-safe extraction from untyped dict
result = {"findings": {...}, "confidence_score": 0.85}
findings: dict[str, object] | None = (
    cast("dict[str, object]", result.get("findings"))
    if isinstance(result.get("findings"), dict) else None
)

// Test that schema rejects invalid data
describe('UserSchema', () => {
  test('rejects invalid email', () => {
    const result = UserSchema.safeParse({ email: 'not-email', name: 'Test' })
    expect(result.success).toBe(false)
  })

  test('rejects missing required fields', () => {
    const result = UserSchema.safeParse({})
    expect(result.success).toBe(false)
    expect(result.error.issues).toHaveLength(2)
  })
})

npm install --save-dev jest-axe @testing-library/react @testing-library/jest-dom

// test-utils/axe.ts
import { configureAxe } from 'jest-axe';

export const axe = configureAxe({
  rules: {
    // Disable rules if needed (use sparingly)
    'color-contrast': { enabled: false }, // Only if manual testing covers this
  },
  reporter: 'v2',
});

// vitest.setup.ts or jest.setup.ts
import { toHaveNoViolations } from 'jest-axe';
expect.extend(toHaveNoViolations);

import { render } from '@testing-library/react';
import { axe } from './test-utils/axe';

test('Button has no accessibility violations', async () => {
  const { container } = render(<Button>Click me</Button>);
  const results = await axe(container);
  expect(results).toHaveNoViolations();
});

// Test form with specific WCAG level
test('Form meets WCAG 2.1 Level AA', async () => {
  const { container } = render(<ContactForm />);
  const results = await axe(container, {
    runOnly: {
      type: 'tag',
      values: ['wcag2a', 'wcag2aa', 'wcag21aa'],
    },
  });
  expect(results).toHaveNoViolations();
});

// Test only keyboard navigation
test('Modal is keyboard accessible', async () => {
  const { container } = render(<Modal isOpen />);
  const results = await axe(container, {
    runOnly: ['keyboard', 'focus-order-semantics'],
  });
  expect(results).toHaveNoViolations();
});

npm install --save-dev @axe-core/playwright

// tests/a11y.setup.ts
import { test as base } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';

export const test = base.extend<{ makeAxeBuilder: () => AxeBuilder }>({
  makeAxeBuilder: async ({ page }, use) => {
    const makeAxeBuilder = () =>
      new AxeBuilder({ page })
        .withTags(['wcag2a', 'wcag2aa', 'wcag21aa'])
        .exclude('#third-party-widget');
    await use(makeAxeBuilder);
  },
});

export { expect } from '@playwright/test';

import { test, expect } from './a11y.setup';

test('homepage is accessible', async ({ page, makeAxeBuilder }) => {
  await page.goto('/');

  const accessibilityScanResults = await makeAxeBuilder().analyze();

  expect(accessibilityScanResults.violations).toEqual([]);
});

test('modal maintains accessibility after opening', async ({ page, makeAxeBuilder }) => {
  await page.goto('/dashboard');

  // Initial state
  const initialScan = await makeAxeBuilder().analyze();
  expect(initialScan.violations).toEqual([]);

  // After opening modal
  await page.getByRole('button', { name: 'Open Settings' }).click();
  const modalScan = await makeAxeBuilder().analyze();
  expect(modalScan.violations).toEqual([]);

  // Focus should be trapped in modal
  await page.keyboard.press('Tab');
  const focusedElement = await page.evaluate(() => document.activeElement?.tagName);
  expect(focusedElement).not.toBe('BODY');
});

test('scan page excluding third-party widgets', async ({ page, makeAxeBuilder }) => {
  await page.goto('/');

  const results = await makeAxeBuilder()
    .exclude('#ads-container')
    .exclude('[data-third-party]')
    .analyze();

  expect(results.violations).toEqual([]);
});

# .github/workflows/a11y.yml
name: Accessibility Tests

on: [push, pull_request]

jobs:
  a11y:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Run unit accessibility tests
        run: npm run test:a11y

      - name: Install Playwright
        run: npx playwright install --with-deps chromium

      - name: Build application
        run: npm run build

      - name: Start server
        run: npm run start &
        env:
          PORT: 3000

      - name: Wait for server
        run: npx wait-on http://localhost:3000

      - name: Run E2E accessibility tests
        run: npx playwright test tests/a11y/

      - name: Upload accessibility report
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: a11y-report
          path: playwright-report/
          retention-days: 30

#!/bin/sh
# .husky/pre-commit

# Run accessibility tests on staged components
STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep "\.tsx\?$")

if [ -n "$STAGED_FILES" ]; then
  echo "Running accessibility tests on changed components..."
  npm run test:a11y -- --findRelatedTests $STAGED_FILES
  if [ $? -ne 0 ]; then
    echo "❌ Accessibility tests failed. Please fix violations before committing."
    exit 1
  fi
fi

{
  "scripts": {
    "test:a11y": "vitest run tests/**/*.a11y.test.{ts,tsx}",
    "test:a11y:watch": "vitest watch tests/**/*.a11y.test.{ts,tsx}",
    "test:a11y:e2e": "playwright test tests/a11y/",
    "test:a11y:all": "npm run test:a11y && npm run test:a11y:e2e"
  }
}

# lighthouserc.js
module.exports = {
  ci: {
    collect: {
      url: ['http://localhost:3000', 'http://localhost:3000/dashboard'],
      numberOfRuns: 3,
    },
    assert: {
      preset: 'lighthouse:recommended',
      assertions: {
        'categories:accessibility': ['error', { minScore: 0.95 }],
        'categories:best-practices': ['warn', { minScore: 0.9 }],
      },
    },
    upload: {
      target: 'temporary-public-storage',
    },
  },
};

# Install
npm install -g @axe-core/cli

# Scan a URL
axe http://localhost:3000 --tags wcag2a,wcag2aa

# Save results
axe http://localhost:3000 --save results.json

# Check multiple pages
axe http://localhost:3000 \
    http://localhost:3000/dashboard \
    http://localhost:3000/profile \
    --tags wcag21aa

// Buttons
await page.getByRole('button', { name: 'Submit' }).click();
await page.getByRole('button', { name: /submit/i }).click(); // Regex

// Links
await page.getByRole('link', { name: 'Home' }).click();

// Headings
await expect(page.getByRole('heading', { name: 'Welcome' })).toBeVisible();
await expect(page.getByRole('heading', { level: 1 })).toHaveText('Welcome');

// Form controls
await page.getByRole('textbox', { name: 'Email' }).fill('test@example.com');
await page.getByRole('checkbox', { name: 'Remember me' }).check();
await page.getByRole('combobox', { name: 'Country' }).selectOption('US');

// Lists
await expect(page.getByRole('list')).toContainText('Item 1');
await expect(page.getByRole('listitem')).toHaveCount(3);

// Navigation
await page.getByRole('navigation').getByRole('link', { name: 'About' }).click();

// Form inputs with labels
await page.getByLabel('Email').fill('test@example.com');
await page.getByLabel('Password').fill('secret123');
await page.getByLabel('Remember me').check();

// Partial match
await page.getByLabel(/email/i).fill('test@example.com');

// Text content
await page.getByText('Welcome back').click();
await page.getByText(/welcome/i).isVisible();

// Placeholder
await page.getByPlaceholder('Enter email').fill('test@example.com');

// When semantic locators aren't possible
await page.getByTestId('custom-widget').click();

// Configure test ID attribute
// playwright.config.ts
export default defineConfig({
  use: {
    testIdAttribute: 'data-test-id',
  },
});

// React/Vue component selectors - Before
await page.locator('_react=MyComponent').click();
await page.locator('_vue=MyComponent').click();

// After - Use semantic locators or test IDs
await page.getByRole('button', { name: 'My Component' }).click();
await page.getByTestId('my-component').click();

// :light selector - Before
await page.locator('.card:light').click();

// After - Just use the selector directly
await page.locator('.card').click();

// DevTools option - Before
const browser = await chromium.launch({ devtools: true });

// After - Use args
const browser = await chromium.launch({
  args: ['--auto-open-devtools-for-tabs']
});

// Optimized CDP connection for local debugging
const browser = await chromium.connectOverCDP({
  endpointURL: 'http://localhost:9222',
  isLocal: true  // NEW: Optimizes for local connections
});

// Use for connecting to locally running Chrome instances
// Reduces latency and improves reliability

// playwright.config.ts
export default defineConfig({
  reporter: [['html', { open: 'never' }]],
});

// The HTML report shows:
// - Test execution sequence
// - Parallel test distribution
// - Time spent in each test phase
// - Performance bottlenecks

// Assert individual class names (1.57+)
await expect(page.locator('.card')).toContainClass('highlighted');
await expect(page.locator('.card')).toContainClass(['active', 'visible']);

// Visibility
await expect(page.getByRole('button')).toBeVisible();
await expect(page.getByRole('button')).toBeHidden();
await expect(page.getByRole('button')).toBeEnabled();
await expect(page.getByRole('button')).toBeDisabled();

// Text content
await expect(page.getByRole('heading')).toHaveText('Welcome');
await expect(page.getByRole('heading')).toContainText('Welcome');

// Attribute
await expect(page.getByRole('link')).toHaveAttribute('href', '/home');

// Count
await expect(page.getByRole('listitem')).toHaveCount(5);

// Screenshot
await expect(page).toHaveScreenshot('page.png');
await expect(page.locator('.hero')).toHaveScreenshot('hero.png');

# Initialize agents for your preferred AI tool
npx playwright init-agents --loop=claude    # For Claude Code
npx playwright init-agents --loop=vscode    # For VS Code (requires v1.105+)
npx playwright init-agents --loop=opencode  # For OpenCode

// playwright.config.ts
export default defineConfig({
  use: {
    aiAgents: {
      enabled: true,
      model: 'claude-sonnet-4-6',  // or local Ollama
      autoHeal: true,              // Auto-repair on CI failures
    }
  }
});

// Save auth state
await page.context().storageState({ path: 'playwright/.auth/user.json' });

// Use saved state
const context = await browser.newContext({
  storageState: 'playwright/.auth/user.json'
});

// Save storage state including IndexedDB
await page.context().storageState({
  path: 'auth.json',
  indexedDB: true  // Include IndexedDB in storage state
});

// Restore with IndexedDB
const context = await browser.newContext({
  storageState: 'auth.json'  // Includes IndexedDB automatically
});

// playwright.config.ts
export default defineConfig({
  projects: [
    {
      name: 'setup',
      testMatch: /.*\.setup\.ts/,
    },
    {
      name: 'logged-in',
      dependencies: ['setup'],
      use: {
        storageState: 'playwright/.auth/user.json',
      },
    },
  ],
});

// playwright.config.ts
export default defineConfig({
  // Fail CI if any flaky tests detected
  failOnFlakyTests: true,

  // Retry configuration
  retries: process.env.CI ? 2 : 0,

  // Web server with regex-based ready detection
  webServer: {
    command: 'npm run dev',
    wait: /ready in \d+ms/,  // Wait for this log pattern
  },
});

test('visual regression', async ({ page }) => {
  await page.goto('/');

  // Full page screenshot
  await expect(page).toHaveScreenshot('homepage.png');

  // Element screenshot
  await expect(page.locator('.hero')).toHaveScreenshot('hero.png');

  // With options
  await expect(page).toHaveScreenshot('page.png', {
    maxDiffPixels: 100,
    threshold: 0.2,
  });
});

// Describe locators for trace viewer
const submitBtn = page.getByRole('button', { name: 'Submit' });
submitBtn.describe('Main form submit button');

// Shows in trace viewer for debugging

# Install browsers (includes Chrome for Testing)
npx playwright install

# No code changes needed - better Chrome compatibility

npm install --save-dev @playwright/test
npx playwright install  # Install browsers (Chromium, Firefox, WebKit)

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

# Initialize the three agents (planner, generator, healer)
npx playwright init-agents --loop=claude
# OR for VS Code: --loop=vscode
# OR for OpenCode: --loop=opencode

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

test.beforeEach(async ({ page }) => {
  // Your app initialization
  await page.goto('http://localhost:3000');

  // Login if needed
  // await page.getByLabel('Email').fill('test@example.com');
  // await page.getByLabel('Password').fill('password123');
  // await page.getByRole('button', { name: 'Login' }).click();
});

test('seed test - app is accessible', async ({ page }) => {
  await expect(page).toHaveTitle(/MyApp/);
  await expect(page.getByRole('navigation')).toBeVisible();
});

your-project/
├── specs/              <- Planner outputs test plans here (Markdown)
├── tests/              <- Generator outputs test code here (.spec.ts)
│   └── seed.spec.ts    <- Your initialization test (REQUIRED)
├── playwright.config.ts
└── .mcp.json           <- MCP server config

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

export default defineConfig({
  testDir: './tests',
  fullyParallel: true,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,

  use: {
    baseURL: 'http://localhost:3000',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
  },

  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
  ],
});

npx playwright test                 # Run all tests
npx playwright test --ui            # UI mode
npx playwright test --debug         # Debug mode
npx playwright test --headed        # See browser

# Quick visual verification
agent-browser open http://localhost:5173
agent-browser snapshot -i
agent-browser screenshot /tmp/screenshot.png
agent-browser close

import { test, expect } from '@playwright/test';

test('homepage visual regression', async ({ page }) => {
  await page.goto('/');
  await expect(page).toHaveScreenshot('homepage.png');
});

import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './e2e',

  // Snapshot configuration
  snapshotPathTemplate: '{testDir}/__screenshots__/{testFilePath}/{arg}{ext}',
  updateSnapshots: 'missing', // 'all' | 'changed' | 'missing' | 'none'

  expect: {
    toHaveScreenshot: {
      // Tolerance settings
      maxDiffPixelRatio: 0.01,  // Allow 1% pixel difference
      threshold: 0.2,           // Per-pixel color threshold (0-1)

      // Animation handling
      animations: 'disabled',   // Freeze CSS animations

      // Caret handling (text cursors)
      caret: 'hide',
    },
  },

  // CI-specific settings
  workers: process.env.CI ? 1 : undefined,
  retries: process.env.CI ? 2 : 0,

  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },
    // Only run screenshots on Chromium for consistency
    {
      name: 'firefox',
      use: { ...devices['Desktop Firefox'] },
      ignoreSnapshots: true,  // Skip VRT for Firefox
    },
  ],
});

test('page screenshot', async ({ page }) => {
  await page.goto('/');
  await expect(page).toHaveScreenshot('page-name.png');
});

test('full page screenshot', async ({ page }) => {
  await page.goto('/');
  await expect(page).toHaveScreenshot('full-page.png', {
    fullPage: true,
  });
});

test('component screenshot', async ({ page }) => {
  await page.goto('/');
  const header = page.locator('header');
  await expect(header).toHaveScreenshot('header.png');
});

test('page with masked dynamic content', async ({ page }) => {
  await page.goto('/');

  await expect(page).toHaveScreenshot('page.png', {
    mask: [
      page.locator('[data-testid="timestamp"]'),
      page.locator('[data-testid="random-avatar"]'),
      page.locator('time'),
    ],
    maskColor: '#FF00FF',  // Pink mask (default)
  });
});

// e2e/fixtures/screenshot.css
// Hide dynamic elements during screenshots
[data-testid="timestamp"],
[data-testid="loading-spinner"] {
  visibility: hidden !important;
}

* {
  animation: none !important;
  transition: none !important;
}

test('page with custom styles', async ({ page }) => {
  await page.goto('/');

  await expect(page).toHaveScreenshot('styled.png', {
    stylePath: './e2e/fixtures/screenshot.css',
  });
});

const viewports = [
  { name: 'mobile', width: 375, height: 667 },
  { name: 'tablet', width: 768, height: 1024 },
  { name: 'desktop', width: 1280, height: 800 },
];

for (const viewport of viewports) {
  test(`homepage - ${viewport.name}`, async ({ page }) => {
    await page.setViewportSize({
      width: viewport.width,
      height: viewport.height
    });
    await page.goto('/');
    await expect(page).toHaveScreenshot(`homepage-${viewport.name}.png`);
  });
}

test('homepage dark mode', async ({ page }) => {
  await page.goto('/');

  // Toggle dark mode
  await page.evaluate(() => {
    document.documentElement.classList.add('dark');
    localStorage.setItem('theme', 'dark');
  });

  // Wait for theme to apply
  await page.waitForTimeout(100);

  await expect(page).toHaveScreenshot('homepage-dark.png');
});

test('page after animations complete', async ({ page }) => {
  await page.goto('/');

  // Wait for network idle
  await page.waitForLoadState('networkidle');

  // Wait for specific content
  await page.waitForSelector('[data-testid="content-loaded"]');

  // Playwright auto-waits for 2 consecutive stable screenshots
  await expect(page).toHaveScreenshot('stable.png');
});

name: Visual Regression Tests

on:
  pull_request:
    branches: [main, dev]

jobs:
  visual-regression:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Install Playwright browsers
        run: npx playwright install chromium --with-deps

      - name: Run visual regression tests
        run: npx playwright test --project=chromium e2e/specs/visual-regression.spec.ts

      - name: Upload test results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: playwright-report
          path: playwright-report/
          retention-days: 7

      - name: Upload screenshots on failure
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: screenshot-diffs
          path: e2e/__screenshots__/
          retention-days: 7

# Separate workflow for updating baselines
name: Update Visual Baselines

on:
  workflow_dispatch:  # Manual trigger only

jobs:
  update-baselines:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup and install
        run: |
          npm ci
          npx playwright install chromium --with-deps

      - name: Update snapshots
        run: npx playwright test --update-snapshots

      - name: Commit updated snapshots
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add e2e/__screenshots__/
          git commit -m "chore: update visual regression baselines" || exit 0
          git push

// playwright.config.ts
export default defineConfig({
  // Only update snapshots in CI
  updateSnapshots: process.env.CI ? 'missing' : 'none',
});

# Run tests in same container as CI
docker run --rm -v $(pwd):/work -w /work mcr.microsoft.com/playwright:v1.58.0-jammy \
  npx playwright test --project=chromium

expect: {
  toHaveScreenshot: {
    maxDiffPixelRatio: 0.05,  // 5% tolerance
    threshold: 0.3,           // Higher per-pixel tolerance
  },
},

npx playwright show-report

e2e/__screenshots__/
├── homepage.png              # Expected (baseline)
├── homepage-actual.png       # Actual (current run)
└── homepage-diff.png         # Difference highlighted

// playwright.config.ts
export default defineConfig({
  use: {
    trace: 'on-first-retry',  // Capture trace on failures
  },
});

// Good - semantic selectors
await page.waitForSelector('[data-testid="content"]');

// Avoid - fragile selectors
await page.waitForSelector('.css-1234xyz');

// Ensure page is ready before screenshot
await page.waitForLoadState('networkidle');
await page.waitForSelector('[data-loaded="true"]');

// Always mask timestamps, avatars, random content
mask: [
  page.locator('time'),
  page.locator('[data-testid="avatar"]'),
],

// Global in config
animations: 'disabled',

// Or per-test with CSS
stylePath: './e2e/fixtures/no-animations.css',

// Only Chromium for visual tests - most consistent
projects: [
  {
    name: 'chromium',
    use: { ...devices['Desktop Chrome'] },
  },
],

// Good - descriptive names
await expect(page).toHaveScreenshot('checkout-payment-form-error.png');

// Avoid - generic names
await expect(page).toHaveScreenshot('test1.png');

// Before (Percy)
import { percySnapshot } from '@percy/playwright';
await percySnapshot(page, 'Homepage - Light Mode');

// After (Playwright)
// No import needed
await expect(page).toHaveScreenshot('homepage-light.png');

# .gitattributes
e2e/__screenshots__/**/*.png filter=lfs diff=lfs merge=lfs -text

<!-- Before -->
<img src="logo.png">

<!-- After -->
<img src="logo.png" alt="Company Logo">

<!-- Before -->
<input type="email" placeholder="Email">

<!-- After -->
<label for="email">Email</label>
<input type="email" id="email">

/* Before */
color: #999; /* 2.8:1 ratio */

/* After */
color: #767676; /* 4.5:1 ratio */

// Before
<div onClick={handleClick}>Click me</div>

// After
<button onClick={handleClick}>Click me</button>

/* Before */
button:focus { outline: none; }

/* After */
button:focus-visible {
  outline: 2px solid blue;
  outline-offset: 2px;
}