Use Percy with Playwright toHaveScreenshot

Send the screenshots from your existing Playwright toHaveScreenshot tests to Percy without changing your tests.

Playwright compares toHaveScreenshot() screenshots locally by default. It stores a screenshot file on the machine that runs the test and compares later runs against that file, so the result depends on the operating system, fonts, and screen size of that machine.

Percy captures these screenshots and compares them in the cloud instead. Percy maintains the base build, reports each visual change for review, and keeps your comparisons consistent across the machines that run your tests.

Prerequisites

Before you start, ensure you have the following:

• A Percy project of the type Web, and its project token. To create a project, see Create a Percy project. For your first run on a new project, use the full access token from Project settings > Tokens. The default write-only token can’t read the build status, so Percy can’t wait for your base build before your tests start.
• A Playwright test suite written in JavaScript or TypeScript that calls toHaveScreenshot().
• Node version 18 or later.
• The @playwright/test package, version 1.60 or later.
• The @percy/cli package, version 1.32.6 or later.
• The @percy/playwright package, version 1.1.2 or later.

Set up Percy for your existing tests

To use Percy for the screenshots in your existing tests, follow these steps:

Things to know

Review the following behavior before you run your tests.

How Percy sets your base build

We recommend that you create a new Percy project. Percy finds the screenshots you already committed and uses them to create the base build. Your next run compares against that base build and shows real visual changes.

Percy uses your committed screenshots only when your Playwright configuration meets the following conditions:

• Your configuration is in the default playwright.config.js or playwright.config.ts file. Percy doesn’t read a configuration that you pass with the --config option.
• Every project sets use.browserName and use.viewport.width.
• You don’t set a custom snapshotPathTemplate or expect.toHaveScreenshot.pathTemplate.
• Your snapshot names are text values, such as toHaveScreenshot('home page.png'), and not a list of folders.

If you use a Percy project that already has builds, your tests run as usual and Percy logs the following message:

To use your committed screenshots as the base build instead, run the following command. Your tests don’t run for this command, and Percy approves the resulting build:

Use the same command when you run your tests as a parallel build, or when you want to reset the base build to your current screenshots. If you don’t have committed screenshots yet, run npx playwright test --update-snapshots and commit the results first.

How your test results change

Playwright fails a toHaveScreenshot() check when the screenshots differ, or when the screenshot file is missing on a fresh clone. With Percy, the check passes and you review the visual change in your Percy project, so a passing test run no longer means that your pages look the same. Review your Percy build after each run, or see Fail your pipeline on visual changes to fail your pipeline on unapproved changes.

Fail your pipeline on visual changes

Playwright’s local comparison fails your pipeline when a screenshot changes. Percy reports the change for review instead, so your pipeline passes and the change waits for someone to approve or reject it. If your pipeline currently blocks a merge on visual changes, add a wait step after your test command to keep that behavior:

The percy exec step prints the build ID, so pass that value to the wait step. The wait step reads the build status, so use the full access token from Project settings > Tokens. With the default write-only token, this step fails with a 403 error.

The wait step fails your pipeline when the finished build has visual changes that nobody approved.

If Percy created your base build from your committed screenshots, your first test run can report changes to review. Approve them once, and later runs pass.

Percy on Automate

You can also send your toHaveScreenshot() screenshots to a Percy on Automate project. Set up the SDK as shown in the preceding steps, use your Percy on Automate project token, and run your tests on BrowserStack. For the Percy on Automate setup, see Integrate functional and visual tests.

Percy on Automate captures each screenshot on the remote browser in your BrowserStack session, so the following differences apply:

• Your tests must run on BrowserStack. If you use a Percy on Automate token with a browser on your machine, every check fails with a configuration error.
• Percy sets your base build from your first run, not from the screenshots you committed. Comparisons pair on the browser and resolution of your BrowserStack session, so approve your first build to set the base build.
• Percy captures the full page for a Locator. Element screenshots aren’t available for Percy on Automate.
• Percy ignores the mask and clip options. The fullPage option works as expected.
• Percy on Automate runs need @playwright/test version 1.61. BrowserStack doesn’t support version 1.62 yet.

Troubleshoot

Find the problem you’re seeing in the following table:

Related topics

• Integrate Percy with Playwright and Javascript
• Create a Percy project
• Baseline management
• Percy configuration options