Playwright Visual Testing

You are a QA automation engineer. The user wants to set up visual comparison testing with Playwright to detect unintended UI changes through screenshot comparisons.

What to check first

• Run npm list playwright to confirm Playwright is installed (v1.40+ recommended for stable visual comparisons)
• Check if you have a playwright.config.ts file in your project root
• Verify you have a baseline screenshots directory ready (or plan to create one with npx playwright test --update-snapshots)

Steps

1. Install Playwright with npm install -D @playwright/test if not already present
2. Create a test file (e.g., tests/visual.spec.ts) that imports test and expect from @playwright/test
3. Configure webServerUrl or baseURL in playwright.config.ts to point to your app's test environment
4. Write a test that navigates to a page and calls expect(page).toHaveScreenshot() with a descriptive snapshot name
5. Run npx playwright test --update-snapshots once to generate baseline images in tests/__screenshots__/ directory
6. Add snapshot comparison assertions for different viewport sizes using page.setViewportSize() before screenshots
7. Run npx playwright test in CI/CD; Playwright will compare current screenshots against baselines and fail if pixel differences exceed the threshold
8. Review failed visual tests with npx playwright show-report to see side-by-side diffs of expected vs actual

Code

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

test.describe('Visual Testing', () => {
  test.beforeEach(async ({ page }) => {
    await page.goto('https://example.com');
  });

  test('homepage full page snapshot', async ({ page }) => {
    // Wait for critical elements to load
    await page.waitForLoadState('networkidle');
    
    // Take full page screenshot
    await expect(page).toHaveScreenshot('homepage-full.png', {
      fullPage: true,
      maxDiffPixelRatio: 0.1, // Allow 10% pixel difference
    });
  });

  test('hero section snapshot', async ({ page }) => {
    // Isolate and compare specific components
    const heroSection = page.locator('[data-testid="hero"]');
    await expect(heroSection).toHaveScreenshot('hero-section.png', {
      maxDiffPixels: 50, // Allow max 50 different pixels
    });
  });

  test('responsive design - mobile', async ({ page }) => {
    // Test at mobile viewport
    await page.setViewportSize({ width: 375, height: 667 });
    await page.waitForLoadState('networkidle');
    
    await expect(page).toHaveScreenshot('homepage-mobile.png', {
      fullPage: true,
    });
  });

  test('responsive design - tablet

Note: this example was truncated in the source. See the GitHub repo for the latest full version.

Common Pitfalls

• Treating this skill as a one-shot solution — most workflows need iteration and verification
• Skipping the verification steps — you don't know it worked until you measure
• Applying this skill without understanding the underlying problem — read the related docs first

When NOT to Use This Skill

• When a simpler manual approach would take less than 10 minutes
• On critical production systems without testing in staging first
• When you don't have permission or authorization to make these changes

How to Verify It Worked

• Run the verification steps documented above
• Compare the output against your expected baseline
• Check logs for any warnings or errors — silent failures are the worst kind

Production Considerations

• Test in staging before deploying to production
• Have a rollback plan — every change should be reversible
• Monitor the affected systems for at least 24 hours after the change