Snapvisor
Start free

Guide

Visual regression testing for Puppeteer

Keep your Puppeteer scripts. @snapvisor/puppeteer adds an argosScreenshot call that stabilizes the page and saves a screenshot, and one CLI command uploads the folder. Snapvisor compares each screenshot with the approved baseline and posts the result as a status check on your pull request.

Install the packages

@snapvisor/puppeteer is the Puppeteer adapter and @snapvisor/cli uploads the screenshots it saves. 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/puppeteer @snapvisor/cli

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.

Capture screenshots in your script

your Puppeteer script
import puppeteer from "puppeteer";
import { argosScreenshot } from "@snapvisor/puppeteer";

const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto("http://localhost:3000");
await argosScreenshot(page, "homepage");
await browser.close();

argosScreenshot stabilizes the UI before it captures, unless you set stabilize: false. It builds on Puppeteer's own screenshot options and adds a few of its own.

  • Viewports. viewports captures the page at more than one viewport size (example below).
  • Extra CSS. argosCSS applies CSS during the screenshot process.
  • Sensitivity. threshold runs from 0 to 1; the higher it is, the less sensitive the diff.
  • Tags. tag attaches one tag or several to the screenshot.
viewports
await argosScreenshot(page, "homepage", {
  viewports: [
    { width: 375, height: 812 },
    { width: 1280, height: 800 },
  ],
});

Upload with the CLI

Unlike the Playwright reporter and the Cypress task, the Puppeteer adapter does not upload by itself. It saves the screenshots locally, in ./screenshots/argos, and you upload that folder with the CLI, usually as the last step of the CI job.

shell
export ARGOS_TOKEN="<your project token>"
npx @snapvisor/cli upload ./screenshots/argos
upload exits 0 once the build has been created, whether or not it contains changes. A non-zero exit means the upload itself failed, for example a bad token, an unresolvable commit or a network error.

Run it in CI

Run your script, then the upload step. The token comes from the environment.

GitHub Actions
- run: npm run build
- run: node screenshots.mjs # your Puppeteer script, captures via argosScreenshot
- run: npx @snapvisor/cli upload ./screenshots/argos
  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.

Read more: Baseline builds, Flaky test detection.

Frequently asked questions

Yes. The Snapvisor documentation lists Puppeteer among the official adapters, and the package is @snapvisor/puppeteer. It exports argosScreenshot, which you call with your Puppeteer page.

No. You keep your script and add an argosScreenshot call wherever you want a screenshot compared, then upload the saved folder with the CLI.

The Puppeteer adapter saves the screenshots locally and does not upload them itself, unlike the Playwright reporter and the Cypress task. The package saves them in ./screenshots/argos; upload that folder with npx @snapvisor/cli upload ./screenshots/argos, usually at the end of the CI job.

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.

Where to go next

Visual regression testing in GitHub pull requestsWhat appears on the pull request and how a reviewer clears it.
Visual regression testing guideHow the capture, compare and review loop works.
Playwright visual regression testingThe same workflow for Playwright.
Storybook visual regression testingThe same workflow for Storybook.
Cypress visual regression testingThe same workflow for Cypress.
GitLab CI visual regression testingRunning it from GitLab CI and merge requests.

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 SDKsSee pricing