Visual testing with any test framework

Set up visual testing with any test framework by uploading screenshots with the Argos CLI.

To add visual testing to any test framework, save your screenshots to a folder, install @argos-ci/cli, and run npm exec -- argos upload ./screenshots 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.

Argos works with any tool that produces screenshots. If your framework has no dedicated Argos SDK, capture screenshots however you like and upload the folder with the Argos CLI.

What Argos adds

• Baselines from your Git history. There are no reference images to commit or update.
• Review on the pull request. Visual changes become a pull request check that your team approves or rejects.
• Diff more than images. The CLI also uploads text files such as JSON, HTML, or Markdown with --files — see Compare non-image files.

Prerequisites

• Node.js 22 or later
• Your tests capture screenshots into a folder (e.g. ./screenshots)
• Your tests run on CI
• A project created in Argos

1

Install

Install the Argos CLI:

npm

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

yarn

yarn add --dev @argos-ci/cli

pnpm

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

bun

bun add --dev @argos-ci/cli

2

Set up CI

Run your tests, then upload the screenshots folder 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
        with:
          node-version: 22
      - run: npm ci
      - name: Run tests and capture screenshots
        run: npm test

      - name: Upload screenshots to Argos
        run: npm exec -- argos upload ./screenshots
        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, set ARGOS_TOKEN as a secret environment variable. For GitLab CI, CircleCI, Buildkite, and other providers, see Run Argos in CI.

The CLI detects your CI context (commit, branch, pull request) automatically. See the CLI reference for all options.

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 workflow above uploads screenshots only from CI, so Argos only compares screenshots captured on CI. Keep your CI on the same image and browser version from one run to the next. See Browser glitches and Stabilize screenshots.

Next steps

• Stabilize screenshots – Prevent flaky diffs before they reach your pull requests
• CLI reference – All upload options
• Screenshot metadata – Enrich screenshots with context shown on the build page

---

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