Playwright Visual Regression Testing with Percy and Chromatic Integration

Modern web applications require thorough testing strategies that account for regional requirements, diverse user bases, and complex technical architectures. This guide provides actionable Playwright patterns for your specific context.

Introduction

Integrate Playwright with Percy and Chromatic visual testing platforms for automated screenshot diffing and visual change approval workflows. This guide covers the essential patterns, configurations, and strategies to handle this scenario reliably in your Playwright test suite.

Understanding the nuances of this topic allows your team to ship with confidence, reduce flakiness, and maintain high-quality automation across different environments.

Architecture Overview

graph TD
    Test["Playwright Test"] --> Screenshot["Percy Screenshot"]
    Screenshot --> Percy["Percy Cloud"]
    Percy --> Diff["Visual Diff"]
    Diff --> Review["Human Review"]
    Review --> Approve["Baseline Updated"]

This structure ensures clean separation of concerns and maintainable test code.

Implementation Flow

sequenceDiagram
    participant Test as Playwright Test
    participant App as Application
    participant API as Backend / Mock API

    Test->>App: Navigate and interact
    App->>API: Trigger API call
    API-->>App: Return response
    App-->>Test: UI state updated
    Test->>Test: Assert outcome

Step-by-Step Guide

Follow this implementation to set up the pattern in your test suite.

1. Core Implementation

import { percySnapshot } from '@percy/playwright';

test('homepage visual snapshot matches baseline', async ({ page }) => {
  await page.goto('/');
  await page.waitForLoadState('networkidle');
  // Percy captures and diffs the screenshot
  await percySnapshot(page, 'Homepage - Desktop', {
    widths: [1440, 1024, 768, 375]
  });
  // Also run standard Playwright assertion
  await expect(page).toHaveTitle(/PlaywrightPad/);
});

2. Run and Verify

# Run this specific test file
npx playwright test --grep "Playwright Visual Regression"

Run with UI mode for debugging
npx playwright test --ui

Run across all browsers
npx playwright test --project=chromium --project=firefox --project=webkit

3. View Test Report

npx playwright show-report

Reference Table

Best Practices

Common Pitfalls

Frequently Asked Questions

What is the difference between Percy and Playwright's built-in visual comparison?

Percy provides cloud hosting, approval workflows, and cross-browser diffing. Playwright's is local and simpler.

How to handle dynamic content in Percy snapshots?

Use CSS to hide dynamic elements like timestamps before taking Percy snapshots.

Can I use both Percy and Playwright visual comparison together?

Yes, use Percy for approved visual change workflow and Playwright's toHaveScreenshot for CI fast-fail checks.

How to configure Percy for responsive testing?

Pass a widths array to percySnapshot() and Percy will capture the page at each specified viewport width.

What is Chromatic and when to use it?

Chromatic is a visual testing service by Storybook. Use it for component libraries with Storybook integration.

Summary

Integrate Playwright with Percy and Chromatic visual testing platforms for automated screenshot diffing and visual change approval workflows. By following these patterns, your team can build a reliable, maintainable automation suite that works across environments and handles edge cases gracefully.

Related Articles