Migrate from Playwright toHaveScreenshot to Argos

Move from Playwright's built-in toHaveScreenshot() snapshots to Argos. Stop committing PNG baselines to Git and review visual changes on the pull request.

If you use Playwright's built-in toHaveScreenshot(), you already have visual tests — you're just storing the baselines in your repository and diffing them on the CI machine. This guide moves those tests to Argos so baselines live in the cloud, review happens on the pull request, and you stop fighting cross-platform PNG mismatches.

Why teams move off native snapshots

Playwright's snapshots work, but they push three problems onto your team:

• Baselines are committed PNGs. Every screenshot lives in a *-snapshots/ folder in Git. They bloat the repo, clutter diffs, and cause merge conflicts.
• Snapshots are platform-specific. A baseline captured on macOS won't match Linux CI (-darwin vs -linux suffixes), so teams end up running snapshots only in Docker or CI to stay consistent.
• There is no review UI. A failing toHaveScreenshot() is a red test. To accept an intended change you re-run with --update-snapshots and commit new PNGs — there's no place to see the before/after or have a teammate approve it.

Argos keeps your Playwright tests but removes all three: baselines are selected from your Git history in the cloud, rendering happens the same way every run, and changes are reviewed and approved on the pull request.

What changes semantically

With native snapshots, a visual difference fails the test. With Argos, argosScreenshot uploads the image and the comparison runs in Argos — the visual result becomes a commit status and PR check you review and approve, decoupled from whether the test itself passed. This is what lets you approve intended changes without editing files.

Concept mapping

Playwright native	Argos
expect(page).toHaveScreenshot("name.png")	argosScreenshot(page, "name")
expect(locator).toHaveScreenshot()	argosScreenshot(locator, "name")
Committed *-snapshots/ PNG folders	Cloud baselines from Git history
--update-snapshots	Approve in the Argos review UI
maxDiffPixels / threshold	Diff algorithm
Diff fails the test	Diff becomes a PR check to review + approve

Migrate the project

1

Install the Argos Playwright SDK

npm

npm i --save-dev @argos-ci/playwright

yarn

yarn add --dev @argos-ci/playwright

pnpm

pnpm add --save-dev @argos-ci/playwright

bun

bun add --dev @argos-ci/playwright

2

Add the Argos reporter

playwright.config.ts

import { defineConfig } from "@playwright/test";
import { createArgosReporterOptions } from "@argos-ci/playwright/reporter";

export default defineConfig({
  reporter: [
    process.env.CI ? ["dot"] : ["list"],
    [
      "@argos-ci/playwright/reporter",
      createArgosReporterOptions({
        uploadToArgos: !!process.env.CI,
      }),
    ],
  ],
  use: {
    // No longer needed to match CI, but still good for stable text.
    launchOptions: {
      args: ["--disable-lcd-text", "--font-render-hinting=none"],
    },
  },
});

3

Replace toHaveScreenshot() with argosScreenshot()

Before (native)

import { test, expect } from "@playwright/test";

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

After (Argos)

import { test } from "@playwright/test";
import { argosScreenshot } from "@argos-ci/playwright";

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

To screenshot a single element, pass a locator: await argosScreenshot(page.getByRole("dialog"), "dialog").

4

Delete committed baselines

Remove the snapshot folders Playwright generated and stop tracking them:

git rm -r "**/*-snapshots"

If you set a custom snapshotPathTemplate, remove it too. You no longer commit baseline images — Argos stores them.

5

Seed the baseline and wire up CI

Run your tests in CI with ARGOS_TOKEN set. Run on your default branch first so Argos has a baseline; until then, pull request builds stay orphan.

- run: npx playwright install --with-deps chromium
- run: npx playwright test
  env:
    ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}

ARGOS_TOKEN comes from Settings → General → Token. On GitHub Actions you can use OIDC or tokenless authentication instead.

Frequently asked questions

Can I keep some toHaveScreenshot() assertions?

Yes — the two can coexist during migration. But the whole point is to stop committing and diffing PNGs locally, so we recommend converting each toHaveScreenshot() to argosScreenshot and deleting the committed baselines.

Do I still need Docker to keep screenshots consistent?

No. Because comparison happens in Argos against a baseline captured the same way, you don't need to render locally in the same OS as CI just to match committed PNGs. You still want stable rendering, which the launchOptions flags above handle.

How do I accept an intended visual change now?

Open the build in Argos and approve it in the review UI. No --update-snapshots, no committing new images.

What about maxDiffPixels and threshold?

Argos applies its own diff algorithm with tolerance for anti-aliasing and sub-pixel noise, so you rarely need per-assertion tuning. If a specific screenshot needs a different sensitivity, pass the threshold option to argosScreenshot (between 0 and 1).

Next steps

• Playwright quickstart
• Keep your screenshots stable
• Responsive viewports
• Argos vs Playwright screenshots — a side-by-side comparison with toHaveScreenshot().