# Visual testing for Playwright

> 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.

Canonical: https://argos-ci.com/integrations/playwright

Quickstart: https://argos-ci.com/docs/quickstart/playwright-quickstart
SDK reference: https://argos-ci.com/docs/reference/playwright

## Set up Argos with Playwright

### 1. Install the SDK

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

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

### 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`:

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

### 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`:

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

### 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`:

```yaml
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 }}
```

## 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.

| | 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](https://playwright.dev/docs/test-snapshots) (checked 2026-10-05).

## Why Playwright teams use Argos

- **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. (https://argos-ci.com/docs/reference/playwright#api-overview)
- **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. (https://argos-ci.com/docs/reference/playwright#setup-tests-debugging)
- **Sharding works as is**: Argos detects Playwright's `--shard` and merges the shards into one build. Nothing to configure. (https://argos-ci.com/docs/reference/playwright#tests-sharding)
- **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. (https://argos-ci.com/docs/reference/playwright#helper-attributes-for-visual-testing)
- **ARIA snapshots too**: Pass `ariaSnapshot: true` to capture the accessibility tree along with the screenshot and review it as a text diff. (https://argos-ci.com/docs/reference/playwright#aria-snapshots)

## Frequently asked questions

### 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](https://argos-ci.com/docs/quickstart/playwright-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](https://argos-ci.com/docs/learn/how-to-guides/migrate-to-argos/from-playwright-native-screenshots) 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](https://argos-ci.com/blog/playwright-visual-regression-testing-ci): The full setup: sharding, baselines, stabilization and review.
- [Argos vs toHaveScreenshot()](https://argos-ci.com/compare/playwright): When the built-in assertion is enough, and when it stops scaling.
- [Why Playwright visual testing doesn't scale](https://argos-ci.com/blog/playwright-visual-testing-limits): What committed baselines cost a team over time.