example-percy-playwright

Example app showing integration of Percy visual testing into Playwright tests.

New: This repo ships an advanced/ example covering the full applicable Percy SDK feature surface for @percy/playwright. See the Percy SDK Feature Matrix for cross-SDK coverage.

Based on the TodoMVC VanillaJS app, forked at commit 4e301c7014093505dcf6678c8f97a5e8dee2d250.

Examples

Example	What it shows	Run command
./ (basic, at repo root)	Minimum viable integration: a percySnapshot(page, name) call per test. Start here.	npm run test-web
playwright.config.js + ./tests/dropin/	Drop-in for toHaveScreenshot() (beta): plain Playwright visual assertions routed through Percy — one config line, zero Percy imports in the spec.	npm run test-dropin
playwright.dropin.automate.config.js + ./tests/dropin-automate/	The same drop-in on a Percy on Automate project — captures happen on a real BrowserStack browser through the session.	npm run test-dropin-automate
./advanced/	Full applicable Percy SDK feature surface: widths, percyCSS, regions, readiness, discovery, domTransformation, etc. See advanced/README.md for the matrix-row coverage table.	cd advanced && npm install && npx playwright install --with-deps chromium && npm run test:advanced

Playwright Tutorial

The tutorial assumes you're already familiar with JavaScript and Playwright and focuses on using it with Percy. You'll still be able to follow along if you're not familiar with Playwright, but we won't spend time introducing Playwright concepts.

The tutorial also assumes you have Node 18+ with npm and git installed.

Step 1

Clone the example application and install dependencies:

$ git clone git@github.com:percy/example-percy-playwright.git
$ cd example-percy-playwright
$ npm install

The example app and its tests will now be ready to go. You can explore the app by opening the index.html file in a browser.

Step 2

Sign in to Percy and create a new project. You can name the project "todo" if you'd like. After you've created the project, you'll be shown a token environment variable.

Step 3

In the shell window you're working in, export the token environment variable:

Unix

$ export PERCY_TOKEN="<your token here>"

Windows

$ set PERCY_TOKEN="<your token here>"

# PowerShell
$ $Env:PERCY_TOKEN="<your token here>"

Note: Usually this would only be set up in your CI environment, but to keep things simple we'll configure it in your shell so that Percy is enabled in your local environment.

Step 4

Check out a new branch for your work in this tutorial (we'll call this branch tutorial-example), then run tests & take snapshots:

$ git checkout -b tutorial-example
$ npm run test-web

This will run the app's Playwright tests, which contain calls to create Percy snapshots. The snapshots will then be uploaded to Percy for comparison. Percy will use the Percy token you used in Step 2 to know which organization and project to upload the snapshots to.

You can view the screenshots in Percy now if you want, but there will be no visual comparisons yet. You'll see that Percy shows you that these snapshots come from your tutorial-example branch.

Step 5

Use your text editor to edit index.html and introduce some visual changes. For example, you can add inline CSS to bold the "Clear completed" button on line 32. After the change, that line looks like this:

<button class="clear-completed" style="font-weight:bold">Clear completed</button>

Step 6

Commit the change:

$ git commit -am "Emphasize 'Clear completed' button"

Step 7

Run the tests with snapshots again:

$ npm run test-web

This will run the tests again and take new snapshots of our modified application. The new snapshots will be uploaded to Percy and compared with the previous snapshots, showing any visual diffs.

At the end of the test run output, you will see logs from Percy confirming that the snapshots were successfully uploaded and giving you a direct URL to check out any visual diffs.

Step 8

Visit your project in Percy and you'll see a new build with the visual comparisons between the two runs. Click anywhere on the Build 2 row. You can see the original snapshots on the left, and the new snapshots on the right.

Percy has highlighted what's changed visually in the app! Snapshots with the largest changes are shown first You can click on the highlight to reveal the underlying screenshot.

If you scroll down, you'll see that no other test cases were impacted by our changes to the 'Clear completed' button. The unchanged snapshots appear grouped together at the bottom of the list.

Finished! 😀

From here, you can try making your own changes to the app and tests, if you like. If you do, re-run the tests and you'll see any visual changes reflected in Percy.

Percy drop-in for toHaveScreenshot() (beta)

If your suite already uses Playwright's built-in visual assertions, the drop-in routes them through Percy — one config line, no test rewrites. See playwright.config.js (the repo's default Playwright config) and tests/dropin/todomvc_tohavescreenshot.spec.js: the spec imports nothing from Percy, only @playwright/test.

// playwright.config.js
require('@percy/playwright/dropin');

Run it with a Percy Web project token:

$ export PERCY_TOKEN=<your web project token>   # use the project's FULL ACCESS token for the first run
$ npm run test-dropin

Your suite passes as usual — on a brand-new project the snapshots appear as "new" in Percy's review dashboard (there's nothing to compare against yet); approve the build once and later runs diff against it. The drop-in also suppresses Playwright's native missing-baseline failure, so a clean clone passes without any committed *-snapshots directories.

First-run baseline seeding: if the repo has Playwright's committed baseline screenshots and the Percy project is empty, percy exec uploads them as an auto-approved build #1 first — so your very first run shows real diffs instead of "new" snapshots. To try it here:

$ npx playwright test tests/dropin/ --update-snapshots
$ git add tests/dropin && git commit -m "playwright baselines"
$ npm run test-dropin

Note: baseline discovery reads Playwright's default config — which is why the drop-in lives in this repo's playwright.config.js rather than a custom --config file. If your project loads Playwright config from a non-default path, first-run seeding and playwright:setup-baseline can't map your screenshots.

The first run is best done with the project's full access token — the default write-only token can't read build status, so Percy can't hold the run until the baseline finishes (the CLI prints a warning explaining exactly this). To deliberately re-baseline an established project from committed screenshots: npx percy playwright:setup-baseline.

Drop-in on Percy on Automate

The same drop-in works with a Percy on Automate (auto_…) token when the suite runs on BrowserStack — each toHaveScreenshot() is captured on the remote BrowserStack browser through your Automate session. See playwright.dropin.automate.config.js and tests/dropin-automate/ (the browser fixture connects via BrowserStack's Playwright endpoint; the spec still imports nothing from Percy):

$ export BROWSERSTACK_USERNAME=<your browserstack username>
$ export BROWSERSTACK_ACCESS_KEY=<your browserstack access key>
$ export PERCY_TOKEN=<your percy on automate project token>
$ npm run test-dropin-automate

Baseline seeding doesn't apply to Automate projects (comparison identity comes from the live session) — the first run establishes the baseline; approve it in the dashboard, exactly like standard Percy on Automate onboarding. Running the automate config with a locally-launched browser fails each assertion with a pointer to run on BrowserStack.

Versions

This example pins @percy/cli@1.32.6, @percy/playwright@1.1.2 (exact, per this repo's save-exact npmrc) and @playwright/test@1.61.1. The drop-in requires @percy/cli >= 1.32.6 and @percy/playwright >= 1.1.2; @playwright/test 1.60 or later (use 1.61 for Percy on Automate — 1.62 is not yet supported by BrowserStack's Playwright endpoint).

Playwright with Automate Tutorial

The tutorial assumes you're already familiar with JavaScript and Playwright and focuses on using it with Percy. You'll still be able to follow along if you're not familiar with Playwright, but we won't spend time introducing Playwright concepts.

The tutorial also assumes you have Node 18+ with npm and git installed.

Minimum required @percy/cli version is 1.28.8-beta.3 for this to work correctly. If you already have @percy/cli or @percy/webdriver-utils installed please update it to latest or minium required version.

Step 1

Clone the example application and install dependencies:

$ git clone git@github.com:percy/example-percy-playwright.git
$ cd example-percy-playwright
$ npm install

This tutorial specifically uses Browserstack Automate to run playwright test.

For automate you will need credentials so refer to following instructions to get the same

1. You will need a BrowserStack username and access key. To obtain your access credentials, sign up for a free trial or purchase a plan.

2. Please get your username and access key from profile page.

Step 2

Sign in to Percy and create a new project. You can name the project "PercyOnAutomateTest" if you'd like. After you've created the project, you'll be shown a token environment variable.

Step 3

In the shell window you're working in, export the token environment variable:

Unix

$ export PERCY_TOKEN="<your token here>"

Windows

$ set PERCY_TOKEN="<your token here>"

# PowerShell
$ $Env:PERCY_TOKEN="<your token here>"

Note: Usually this would only be set up in your CI environment, but to keep things simple we'll configure it in your shell so that Percy is enabled in your local environment.

Set the necessary BROWSERSTACK ENVIRONMENT variables

Unix

$ export BROWSERSTACK_USERNAME="<your browserstack user_name>"
$ export BROWSERSTACK_ACCESS_KEY="<your browserstack access_key>"

Windows

$ set BROWSERSTACK_USERNAME="<your browserstack access_key>"
$ set BROWSERSTACK_ACCESS_KEY="<your browserstack access_key>"

# PowerShell
$ $Env:BROWSERSTACK_USERNAME="<your browserstack access_key>"
$ $Env:BROWSERSTACK_ACCESS_KEY="<your browserstack access_key>"

Alternatively you can also update USER_NAME, ACCESS_KEY with Browserstack User name, Access key in the script as well.

Step 4

Considering all the above steps are done, we will run our tests, which will create automate session as well as percy build.

$ npm run test-automate-before

Your First Percy on Automate build is created. On completion of the script, you would be able to see the your percy build. Since we ran for the first time, we would see these are new screenshots and hence there would be no comparisons.

Step 5

Now in order to make comparisons happen we need to make changes to the existing website so that a visual change can occur.

$ npm run test-automate-after

On completion of this script, this build would get compared to the previous build and hence we can see the visual changes which percy detected.

Finished! 😀

From here, you can try making your own changes to the website and functional tests, if you like. If you do, re-run the tests and you'll see any visual changes reflected in Percy.