No Result Found
Get your setup working faster. Join our Discord for optimisation tips from elite testers. Join our DiscordJoin our Discord

Integrate your Playwright and JavaScript screenshots with App Percy

Send the screenshots from your existing Playwright toHaveScreenshot tests to App Percy for visual comparison.

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. Add @percy/playwright/dropin to your Playwright configuration to send those screenshots to App Percy instead. App Percy compares them against your base build and reports each visual change for review.

App Percy doesn’t support Playwright as a test framework for mobile apps. This page covers only how App Percy compares the screenshots that your Playwright tests capture. To automate mobile apps, use one of the frameworks in the preceding framework selector.

Prerequisites

Before you start, ensure you have the following:

  • An App Percy project and its project token. To create a project, see Create a 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 App 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.

Integrate your test suite

To send the screenshots from your existing tests to App Percy, follow these steps:

Install the dependencies
Install the Percy CLI and the Percy Playwright SDK by running the following command:

Copy icon Copy

Import the SDK in your Playwright configuration
Add the @percy/playwright/dropin import to your playwright.config.js file. Place it above your configuration so that App Percy applies to your tests when the test runner starts:

Copy icon Copy

You don’t have to change your test files. App Percy applies to every toHaveScreenshot() call in your test suite.

Run your tests
Set your App Percy project token and run your existing Playwright command through percy exec:

Copy icon Copy

App Percy prints the build URL when the run finishes. Open the URL to review your screenshots.

Things to know

Review the following behavior before you run your tests.

How App Percy compares your screenshots

App Percy uploads the screenshot that Playwright captured and compares it against your base build. App Percy doesn’t render your page again, so your screenshots are compared on the browser and screen size that your test used.

App Percy sets your base build from the screenshots you already committed. Percy finds the PNG files in your Playwright snapshot directories, uploads them as an approved first build, and your next run shows real visual changes. This applies 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 project that already has builds, App Percy doesn’t create the base build for you. To set the base build from your committed screenshots, run the following command. Your tests don’t run for this command, and App Percy approves the resulting build:

Copy icon Copy

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 App Percy, the check passes and you review the visual change in your App Percy project, so a passing test run no longer means that your pages look the same. Review your App Percy build after each run.

To use Playwright’s local comparison again, set the PERCY_DROPIN_DISABLE environment variable to true.

Troubleshoot

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

Problem Solution
Your tests pass but App Percy doesn’t create a build. Set a valid PERCY_TOKEN and run your test command through percy exec.
Percy logs requires a web, app, or automate project token. Use a token from an App Percy project.
Percy logs this token cannot read build status. Use the full access token from Project settings > Tokens and run your tests again, or approve the base build in your App Percy project.
Percy logs this project already has builds. Run npx percy playwright:setup-baseline to set the base build from your committed screenshots.
App Percy doesn’t create a base build. Run your command with --verbose to see the reason. Check the conditions listed under How App Percy compares your screenshots, then run npx percy playwright:setup-baseline.
All snapshots show as new in your second build. Approve the base build in your App Percy project. Later runs compare against it.
You want Playwright to compare the screenshots again. Set the PERCY_DROPIN_DISABLE environment variable to true.

We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked





Thank you for your valuable feedback

Is this page helping you?

Yes
No

We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked





Thank you for your valuable feedback!

Talk to an Expert
Download Copy Check Circle