Puppeteer Quickstart

Set up visual testing in your Puppeteer scripts with the Argos Puppeteer SDK.

Set up Argos with Puppeteer to run visual tests on every pull request: capture screenshots with the SDK, then upload them with the Argos CLI.

Prerequisites

• Puppeteer set up in your project
• A project created in Argos

1

Install

Install the Argos CLI and the Argos Puppeteer SDK:

npm

npm i --save-dev @argos-ci/cli @argos-ci/puppeteer

yarn

yarn add --dev @argos-ci/cli @argos-ci/puppeteer

pnpm

pnpm add --save-dev @argos-ci/cli @argos-ci/puppeteer

bun

bun add --dev @argos-ci/cli @argos-ci/puppeteer

No configuration is needed — the SDK works directly in your scripts.

2

Capture screenshots

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

screenshot.mjs

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

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

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

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

3

Set up CI

Run your Puppeteer tests in CI, then upload the screenshots to Argos with the CLI:

.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
      - name: Run Puppeteer tests
        run: npm test

      - name: Upload screenshots to Argos
        run: npm exec -- argos upload ./screenshots/argos
        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.

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.

Next steps

• Stabilize screenshots – Prevent flaky diffs before they reach your pull requests
• Puppeteer SDK reference – All options and helpers
• Puppeteer example – A complete working setup

---

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