How to Perform Visual Regression Testing Using Playwright

Visual regression testing is used to identify unexpected changes in a website’s layout, styling, or overall appearance. It compares the current UI against a baseline to catch visual bugs that functional tests may miss. With Playwright, teams can automate this process to ensure UI consistency across browsers and screen sizes.

This article explains how to use Playwright for visual regression testing by capturing, comparing, and validating UI snapshots.

What is Visual Regression Testing?

Visual regression testing is a method used to detect unintended visual changes in a web application’s interface after code updates. It captures screenshots of web pages and compares them with baseline images from previous versions.

If there are differences, such as changes in layout, colors, or missing elements, the test highlights them for review. Unlike functional testing, which checks how the application works, visual regression testing ensures that its appearance stays consistent across releases.

How does Visual Regression Testing in Playwright work?

During the first run, the visual comparison tool captures the snapshot called the base image. The subsequent run compares the base image if there is no difference test is passed, and if there is a difference, the test is considered as failed. Visual Regression is also called Visual Comparison Testing.

Create Simple Visual Tests using Playwright

In your tests folder, create a new javascript file example demo.spec.jspage.screenshot() function takes the screenshot, and expect in the @playwright/test module provides the assertion for matching the images that are .toMatchSnapshot().

Inside the newly created javascript file, create a new test that performs the visual comparison like below.

// example.spec.js

const { test, expect } = require('@playwright/test');

test('Visual Comparison Test Demo', async ({ page }) => {

  await page.goto('https://playwright.dev');

  expect(await page.screenshot()).toMatchSnapshot();

});

In the above code, we navigate to the official Playwright website and compare visually by taking a snapshot.

Run your First Visual Regression Tests

Run your visual comparison tests using the below command

npx playwright test

The first time the test is run, it fails, as there is no base image.

As seen below, the directory containing the base image file gets created inside the tests folder.

Run the Spec again; it passes

Visual Snapshot Comparison in Playwright Ignore Minor Differences

The above comparison technique matches the screenshot pixel by pixel, which means each pixel should match exactly. This behavior can be modified by passing the argument maxDiffPixels = <pixel_value>.

Example:

const { test, expect } = require('@playwright/test');

test('Visual Comparison Test Demo', async ({ page }) => {

  await page.goto('https://playwright.dev');

  expect(await page.screenshot()).toMatchSnapshot({ maxDiffPixels: 200 });

});

In the above example

We have specified the maxDiffPixels value as 200, which means the maximum pixel difference can be  200.

Image Comparison in Playwright with Threshold option

Playwright toMatchSnapshot() accepts threshold, threshold ranges from 0 to 1, default value is 0.2. The threshold is tolerance of image differences.

Example Code:

const { test, expect } = require('@playwright/test');

test('Visual Comparison Test Demo', async ({ page }) => {

  await page.goto('https://playwright.dev/');

  expect(await page.screenshot()).toMatchSnapshot({threshold:0.5});

});

In the above code, the threshold is mentioned as 0.5.

Playwright Visual Comparison Tips & Tricks

Here are some valuable tips and best practices to improve accuracy and efficiency when performing visual comparisons using Playwright:

• Use Stable Selectors: Avoid dynamic or frequently changing elements in screenshots,  such as timestamps or animations, as they can cause false positives.

• Set Consistent Viewports: Always define a fixed viewport size to ensure consistent rendering across runs. This helps avoid differences due to screen dimensions.

• Mask Unstable Elements: Mask or hide elements that change frequently (like ads or user-specific data) using Playwright’s mask or ignore options during screenshot comparison.
• Wait for UI Stability: Use proper wait conditions, such as page.waitForSelector() or page.waitForLoadState(), to ensure the page is fully loaded before capturing screenshots.

• Compare Specific Elements: Instead of full-page screenshots, compare specific sections or components to narrow the scope and reduce noise.
• Use Thresholds Wisely: Set an appropriate pixel difference threshold to allow minor acceptable differences, especially for anti-aliasing or rendering quirks across browsers.
• Run Tests in Headless Mode: Consistently run visual tests in headless mode to avoid UI differences caused by OS-level rendering or browser UI.

• Review Baseline Images Carefully: Always validate and approve your initial baseline images, as all future comparisons will use them as the reference.

Visual Testing with Playwright using Percy

BrowserStack is a cloud testing platform that provides access to real browsers and devices for automated and manual testing. Percy, part of the BrowserStack suite, is a visual testing tool that captures and compares screenshots to detect UI changes. It integrates seamlessly with Playwright, allowing teams to include visual regression checks in their end-to-end tests.

Below is a step-by-step guide to implementing visual testing using Percy with Playwright:

Step 1: Install Percy Modules

Install the required Percy dependencies for Playwright by running:

npm install --save-dev @percy/cli @percy/playwright

Step 2: Write a Playwright Test with Percy

Create a test file (such as demo.spec.js) with the following content:

const { chromium } = require('playwright');

const percySnapshot = require('@percy/playwright');

(async () => {

  const browser = await chromium.launch();

  const page = await browser.newPage();

  await page.goto('https://www.browserstack.com/', { waitUntil: 'networkidle' });

  await percySnapshot(page, 'Example Site');

  await browser.close();

})();

This script launches a browser, navigates to the URL, takes a snapshot using Percy, and closes the browser.

Step 3: Set Up a Percy Project

Log in to Percy, create a new project, and copy the Percy Token generated.

Step 4: Set the Percy Token

Set the PERCY_TOKEN environment variable in your terminal:

• PowerShell / VS Code Terminal

$env:PERCY_TOKEN = "your_token"

• Windows Command Prompt

set PERCY_TOKEN="your_token"

• Unix / Linux / macOS

export PERCY_TOKEN="your_token"

Step 5: Run the Test with Percy

Execute your test using the Percy CLI:

npx percy exec -- node tests/demo.spec.js

Replace tests/demo.spec.js with the actual path to your test file.

Step 6: Review Visual Results

Once execution finishes, Percy will log a build URL to the console. Open this URL in a browser to review the snapshots.

• If no changes are found, Percy will show a “No Changes” status.
• If visual differences are detected, Percy will display a side-by-side comparison highlighting the changes.

Talk to an Expert

Conclusion

Visual regression testing using Playwright allows teams to automatically capture and compare UI snapshots, making it easier to detect visual bugs before they reach production. With features like automated screenshot comparison and support for multiple browsers, Playwright simplifies maintaining a consistent user interface across releases.

When combined with BrowserStack, visual testing becomes even more powerful. Percy enhances Playwright tests by providing cloud-based visual comparisons, an easy-to-use dashboard, and cross-browser coverage on 3,500+ real Android, iOS, Windows, and macOS devices.

Try Percy for Free