Playwright

Visual testing for Playwright

Q: How do I add visual testing to Playwright?

Install @argos-ci/playwright, add the Argos reporter to playwright.config.ts, and call argosScreenshot(page, name) where you want a screenshot. Run the tests in CI with ARGOS_TOKEN set: Argos compares each screenshot with its baseline and posts the result on the pull request. The quickstart walks through it.

Q: Do I still need toHaveScreenshot()?

No. argosScreenshot() replaces it: Argos stores the baselines and runs the comparison, so you stop committing PNG files and keeping one set per operating system. You can switch test by test; the migration guide shows the swap.

Q: Does Argos work with Playwright sharding?

Yes. The reporter detects --shard and merges every shard into a single Argos build, with no extra configuration.

Argos adds visual regression testing to your Playwright suite. Install @argos-ci/playwright, call argosScreenshot() in your tests, and every pull request gets its visual changes diffed against a baseline from your Git history, with traces for the tests that fail. Open source, and free for personal projects.

Start for free Get a demo

Setup

Set up Argos with Playwright

4 steps, then every pull request gets a visual check. The quickstart covers every option.

Playwright quickstart SDK reference

Step 1

Install the SDK

The Playwright SDK ships a reporter that uploads your screenshots and the argosScreenshot() helper that captures them.

Terminal

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

Step 2

Add the Argos reporter

The reporter uploads the screenshots when the tests run in CI, along with the traces and failure screenshots Playwright records. The launch options make text render the same on macOS and on Linux CI.

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({
        // Upload to Argos on CI only.
        uploadToArgos: !!process.env.CI,
      }),
    ],
  ],
  use: {
    trace: "on-first-retry",
    screenshot: "only-on-failure",
    launchOptions: {
      args: ["--disable-lcd-text", "--font-render-hinting=none"],
    },
  },
});

Step 3

Capture screenshots

Call argosScreenshot() wherever you want a screenshot. It waits for fonts, images and aria-busy to settle and hides carets and scrollbars before it captures. Pass viewports to capture several sizes in one call.

tests/homepage.spec.ts

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");
});

Step 4

Run it in CI

Set ARGOS_TOKEN to your project token, or use GitHub Actions OIDC and skip the secret. Argos posts a check on the pull request that links to the diffs to review.

.github/workflows/argos.yml

name: Argos
on:
  pull_request:
  push:
    branches: [main]
jobs:
  argos:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
      - run: npm ci
      - run: npx playwright install --with-deps chromium
      - run: npx playwright test
        env:
          ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}

Compared

What Argos adds over toHaveScreenshot()

Playwright's built-in assertion is a good start on a solo project. In a team, committed baselines and per-platform rendering are what slow it down.

Topic	toHaveScreenshot()	Argos
Baselines	PNG files committed to the repository, one set per browser and operating system	Picked from your Git history, nothing committed
Updating a baseline	Re-run with `--update-snapshots`, then commit the images	Approve the change in the review UI
Rendering differences	Baselines only match the machine that produced them, so teams regenerate them in Docker	CI captures are compared with CI captures, so a laptop never produces a baseline
Review	Diff images in the HTML report or the Git diff	A diff viewer on every pull request, with comments and a GitHub check
Noise	Tune `maxDiffPixels` and retry	Capture stabilization, a 0 to 1 threshold, flaky test detection
Cost	Free	Free for personal projects, Pro at $100/month

Sources: Playwright visual comparisons, checked October 2026.

Why Playwright teams use Argos

Raw capture

34 diffs

Argos SDK

Deterministic capture

2 diffs

Screenshots that don't flake

Before each capture, the SDK waits for fonts, images and aria-busy to settle, hides carets and scrollbars, pauses GIFs on their first frame and pins sticky elements. The same page gives the same pixels on every run.

Learn more

checkout.spec.ts

Failed

Something went wrong

Captured on failure

Error: expect(getByText('Order total')).toBeVisible()

Attempt 1retry: 0

Attempt 2retry: 1

Attempt 3retry: 2

Build #214Failed after 3 attempts

Failed tests come with their trace

The reporter uploads Playwright traces and failure screenshots, so you open a failing test in Argos and step through it instead of downloading CI artifacts.

Learn more

Sharding works as is

Argos detects Playwright's --shard and merges the shards into one build. Nothing to configure.

Learn more

Mask what changes on every run

data-visual-test="blackout" masks a date or an avatar, transparent hides it and keeps its space, removed drops it from the layout.

Learn more

ARIA snapshots too

Pass ariaSnapshot: true to capture the accessibility tree along with the screenshot and review it as a text diff.

Learn more

Playwright visual testing FAQ

How do I add visual testing to Playwright?

Install @argos-ci/playwright, add the Argos reporter to playwright.config.ts, and call argosScreenshot(page, name) where you want a screenshot. Run the tests in CI with ARGOS_TOKEN set: Argos compares each screenshot with its baseline and posts the result on the pull request. The quickstart walks through it.

Do I still need toHaveScreenshot()?

No. argosScreenshot() replaces it: Argos stores the baselines and runs the comparison, so you stop committing PNG files and keeping one set per operating system. You can switch test by test; the migration guide shows the swap.

Where do the baselines come from?

From your Git history. For each build, Argos picks the most recent approved build on the commits your branch started from (the merge base with your base branch), so every change is compared with the code you branched from. Nothing is committed to your repository.

Does Argos work with Playwright sharding?

Yes. The reporter detects --shard and merges every shard into a single Argos build, with no extra configuration.

Which CI providers are supported?

Any CI that runs Playwright. The SDK detects GitHub Actions, GitLab CI, CircleCI, Buildkite, Travis CI, Bitrise and Heroku on its own; anywhere else, set ARGOS_COMMIT and ARGOS_BRANCH. On GitHub Actions you can authenticate with OIDC instead of a token.

How much does it cost?

Argos is free for personal projects up to 5,000 screenshots a month. Teams use Pro: $100 a month with 35,000 screenshots included, then $0.004 per screenshot. Argos is open source under the MIT license.

Keep reading

Playwright visual regression testing in CI

The full setup: sharding, baselines, stabilization and review.

Learn more

Argos vs toHaveScreenshot()

When the built-in assertion is enough, and when it stops scaling.

Learn more

Why Playwright visual testing doesn't scale

What committed baselines cost a team over time.

Learn more

Supercharge your product quality

See every change your team and your agents make. Review with confidence, and merge faster.