Ctrlk
x-twitter
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Playwright visual testing quickstart

Set up visual testing in your Playwright tests with the Argos Playwright SDK.

To add visual testing to Playwright, install @argos-ci/playwright, add the Argos reporter to playwright.config.ts, call argosScreenshot(page, "name") in your tests, and run npx playwright test in CI with the ARGOS_TOKEN environment variable set. Argos compares every screenshot with a baseline build picked from your Git history and reports the changes as a check on your pull request.

What Argos adds over toHaveScreenshot()

Playwright's built-in toHaveScreenshot() already compares screenshots. Argos keeps your Playwright tests and changes what happens around them:

  • No baselines in your repository. toHaveScreenshot() stores reference PNGs in *-snapshots/ folders that you commit, with a separate image per platform. Argos picks the baseline from your Git history, so there are no images to commit or keep in sync.

  • Review on the pull request. A toHaveScreenshot() mismatch fails the test until you re-run with --update-snapshots and commit new images. Argos turns visual changes into a pull request check that your team approves or rejects.

  • Fewer flaky diffs. argosScreenshot waits for fonts, images, and aria-busy loaders before capturing, and Argos flags unstable tests with a flaky badge and a stability score.

Already using toHaveScreenshot()? Follow Migrate from Playwright toHaveScreenshot to Argos, or read the Argos vs Playwright screenshots comparison.

Prerequisites

1

Install

Install the Argos Playwright SDK:

npm i --save-dev @argos-ci/playwright
yarn add --dev @argos-ci/playwright
pnpm add --save-dev @argos-ci/playwright
bun add --dev @argos-ci/playwright
2

Add the Argos reporter to your Playwright config

The Argos reporter uploads screenshots and traces to Argos as your tests run:

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

export default defineConfig({
  // ... other configuration

  // Reporter to use
  reporter: [
    // Use "dot" reporter on CI, "list" otherwise (Playwright default).
    process.env.CI ? ["dot"] : ["list"],
    // Add Argos reporter.
    [
      "@argos-ci/playwright/reporter",
      createArgosReporterOptions({
        // Upload to Argos on CI only.
        uploadToArgos: !!process.env.CI,
      }),
    ],
  ],

  // Start your app before the tests run, locally and on CI.
  webServer: {
    command: "npm run start",
    url: "http://localhost:3000",
    reuseExistingServer: !process.env.CI,
  },

  // Setup recording option to enable test debugging features.
  use: {
    // Resolve relative URLs like page.goto("/") against your app.
    baseURL: "http://localhost:3000",

    // Collect trace when retrying the failed test.
    trace: "on-first-retry",

    // Capture screenshot after each test failure.
    screenshot: "only-on-failure",

    // Stabilize text rendering so screenshots match across macOS and CI.
    launchOptions: {
      args: ["--disable-lcd-text", "--font-render-hinting=none"],
    },
  },
});

webServer starts your app before the tests run, on your machine and on CI, so page.goto("/") reaches it. Replace npm run start with the command that serves your app, and the URL with the one it listens on.

With trace and screenshot enabled, Playwright records failure screenshots and traces — the reporter uploads them to Argos automatically, so you can debug failed tests visually.

The launchOptions above disable subpixel text and font hinting, so glyphs render identically on your machine and on CI. This single change prevents one of the most common causes of flaky screenshots — learn why in Stabilize text rendering.

3

Capture screenshots

Use the argosScreenshot helper to capture stable screenshots in your tests:

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

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

Screenshots are written to the ./screenshots directory by default. Add ./screenshots to your .gitignore file to avoid committing them.

Tip: Check out our guides to screenshot multiple pages or capture multiple viewports.

4

Set up CI

Run your Playwright tests in CI with ARGOS_TOKEN set. The Argos reporter uploads screenshots automatically when it detects a CI environment:

.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
        with:
          node-version: 22
      - run: npm ci
      - run: npx playwright install --with-deps chromium
      - run: npx playwright test
        env:
          ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}

ARGOS_TOKEN is the project token from Settings → General → Token. On GitHub Actions, you can also use OIDC or tokenless authentication to avoid managing a secret. On other CI providers, pass the token with the ARGOS_TOKEN environment variable or the reporter's token option. For GitLab CI, CircleCI, Buildkite, and other providers, see Run Argos in CI.

You're all set

Push your changes and open a pull request — the Argos check appears on it once the build is uploaded. Review the visual changes, approve or reject them, and merge with confidence.

Argos needs a baseline to compare against. Until a build runs on your default branch, pull request builds are marked as orphan. Merge this setup or run the workflow once on your default branch to establish the baseline.

Frequently asked questions

How do I update the baseline after an intended change?

You don't update any file. Review the build in Argos and approve the changes: an approved build is eligible as a baseline. Once you merge, the build on your default branch, which Argos approves automatically by default, becomes the baseline for the pull requests that follow. See Baseline build.

Why do screenshots differ between my machine and CI?

Fonts, text rendering, and browser versions depend on the operating system, so the same page renders slightly differently on macOS and on a Linux CI runner. The Argos reporter uploads to Argos only from CI (uploadToArgos: !!process.env.CI), so Argos only compares screenshots captured on CI, and the launchOptions flags make text render the same way on every machine. See Stabilize text rendering and Browser glitches.

Next steps

Need help? Join our Discord, open an issue on GitHub, or send us an email.

Last updated

Was this helpful?