Snapvisor
Start free

Guide

Visual regression testing for Playwright

Keep your Playwright tests. @snapvisor/playwright adds a reporter that uploads screenshots when the run finishes and an argosScreenshot call that captures them. Snapvisor compares each screenshot with the approved baseline and posts the result as a status check on your pull request.

Install the package

@snapvisor/playwright is the Playwright adapter. The @snapvisor packages are drop-in forks of the upstream SDKs and keep the ARGOS_* environment variable names on purpose, so a pipeline already wired for the upstream SDKs works unchanged.

shell
npm install --save-dev @snapvisor/playwright

Create a project in the Snapvisor app and copy its project token (ARGOS_TOKEN) from the project settings. Store it as a CI secret, never in the repository.

Register the reporter

The reporter uploads the screenshots when the run finishes. With uploadToArgos: !!process.env.CI it uploads on CI only, so local runs stay local.

playwright.config.ts
// playwright.config.ts
import { defineConfig } from "@playwright/test";
import { createArgosReporterOptions } from "@snapvisor/playwright/reporter";

export default defineConfig({
  reporter: [
    process.env.CI ? ["dot"] : ["list"],
    [
      "@snapvisor/playwright/reporter",
      createArgosReporterOptions({ uploadToArgos: !!process.env.CI }),
    ],
  ],
});

Capture screenshots in your tests

tests/example.spec.ts
// tests/example.spec.ts
import { test } from "@playwright/test";
import { argosScreenshot } from "@snapvisor/playwright";

test("screenshot homepage", async ({ page }) => {
  await page.goto("http://localhost:3000");
  await argosScreenshot(page, "homepage");
});

argosScreenshot stabilizes the page before it captures: it waits for web fonts, images and aria-busy regions to settle, hides carets and scrollbars and normalizes font anti-aliasing. It is on by default.

  • Viewports. viewports takes complete viewport sizes, not bare widths, and you can name a preset such as iphone-6 (example below).
  • Masking. mask is Playwright's own option and is passed through.
  • Extra CSS. argosCSS applies CSS during the screenshot process.
  • Custom steps. beforeScreenshot runs your own code at the right moment if a page needs more than the default stabilization.
viewports
await argosScreenshot(page, "homepage", {
  viewports: [
    "iphone-6",
    { width: 1280, height: 800 },
  ],
});

To cover Chromium, Firefox and WebKit, run them as Playwright projects.

Run it in CI

Nothing wraps the test command. Run Playwright as you normally do; the token comes from the environment.

GitHub Actions
- run: npm run build
- run: npx playwright test # captures via argosScreenshot, uploads via the reporter
  env:
    ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}
A green CI job after the upload means the screenshots arrived, not that they are unchanged. The gate is the status check Snapvisor posts to the pull request, so require it in your branch protection rules.

On GitHub Actions you can skip the token with tokenless authentication. Large suites can shard their uploads across CI jobs and be reviewed as one build.

Read more: GitHub tokenless authentication, Parallel testing, GitHub, GitLab, Review workflow.

What the first build does

The first build on your base branch has nothing to compare against, so it becomes the baseline and is approved automatically. Run it on a base branch that already looks right. Later builds are diffed against the last approved build on the base branch, and approving a change promotes it to the new baseline for that branch.

With the project's ignore changes setting turned on, reviewers can mark a recurring change as ignored, and you can let the app auto-ignore changes that keep reappearing.

Read more: Baseline builds, Flaky test detection.

Frequently asked questions

No. You keep Playwright as your test runner and your existing specs. Register the reporter in playwright.config.ts and add argosScreenshot calls where you want a screenshot compared.

@snapvisor/playwright. It exports argosScreenshot from the package root and the reporter from @snapvisor/playwright/reporter. To upload any folder of images instead, there is also @snapvisor/cli.

Only if you let it. In the example config uploadToArgos is true only when the CI environment variable is set, so local runs do not upload.

ARGOS_TOKEN, your project token. The @snapvisor packages keep the ARGOS_ variable names on purpose so pipelines wired for the upstream SDKs work unchanged. On GitHub Actions you can skip the token with tokenless authentication.

No. It means the screenshots arrived. The gate is the status check Snapvisor posts to the pull request, so require that check in branch protection.

toHaveScreenshot compares against golden files that live with your tests. Snapvisor stores baselines server-side per reference branch and adds a review UI with pull request status checks. The sourced side-by-side is on the Snapvisor vs Playwright page.

Where to go next

Snapvisor vs PlaywrightPlaywright's built-in screenshot comparison and Snapvisor, side by side.
Visual regression testing in GitHub pull requestsWhat appears on the pull request and how a reviewer clears it.
Storybook visual regression testingThe same workflow for Storybook.
Cypress visual regression testingThe same workflow for Cypress.

Sources

Every command, package name and option on this page comes from the Snapvisor documentation and the published @snapvisor packages:

Try Snapvisor free

Start free Getting started guideAll SDKs