Cypress visual testing quickstart

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

To add visual testing to Cypress, install @argos-ci/cypress, import @argos-ci/cypress/support in your support file, register the Argos task with registerArgosTask() in cypress.config.js, call cy.argosScreenshot("name") in your tests, and run Cypress 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 to Cypress

Cypress takes screenshots with cy.screenshot(), but it doesn't compare them with a baseline. Argos adds:

• Visual comparison with automatic baselines. Argos picks the baseline from your Git history, so there are no images to commit.
• Review on the pull request. Visual changes become a pull request check that your team approves or rejects.
• Stable screenshots. cy.argosScreenshot waits for images and fonts to load before capturing.

Coming from another tool? Follow Migrate from Percy to Argos or Migrate from Applitools to Argos; both cover Cypress.

Prerequisites

• Node.js 22 or later
• Cypress set up in your project
• Cypress running on your CI
• A project created in Argos

1

Install

Install the Argos Cypress SDK:

npm

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

yarn

yarn add --dev @argos-ci/cypress

pnpm

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

bun

bun add --dev @argos-ci/cypress

2

Set up Argos in your Cypress config

Two pieces wire Argos into Cypress: the support file adds the cy.argosScreenshot command, and the task uploads the captured screenshots.

Add the command to your cypress/support/e2e.js file:

cypress/support/e2e.js

import "@argos-ci/cypress/support";

If you use TypeScript, add the types to your tsconfig.json:

tsconfig.json

{
  "compilerOptions": {
    "types": ["cypress", "@argos-ci/cypress/support"]
  }
}

Then register the Argos task in your Cypress config:

cypress.config.js

const { defineConfig } = require("cypress");
const { registerArgosTask } = require("@argos-ci/cypress/task");

module.exports = defineConfig({
  // setupNodeEvents can also be defined in "component"
  e2e: {
    async setupNodeEvents(on, config) {
      registerArgosTask(on, config, {
        // Upload to Argos on CI only.
        uploadToArgos: !!process.env.CI,
      });

      // include any other plugin code...
    },
  },
});

3

Capture screenshots

Use the cy.argosScreenshot command to capture stable screenshots in your tests:

cypress/e2e/homepage.cy.js

it("screenshot homepage", () => {
  cy.visit("http://localhost:3000/");
  cy.argosScreenshot("homepage");
});

Screenshots are written to the /cypress/screenshots directory. Add /cypress/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 Cypress tests in CI with ARGOS_TOKEN set. The Argos task 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
      - name: Run Cypress tests
        uses: cypress-io/github-action@v6
        with:
          start: npm start # command that serves your app
        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 task'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 task uploads only from CI (uploadToArgos: !!process.env.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
• Cypress SDK reference – All options and helpers
• Cypress example – A complete working setup
• Cypress visual regression testing – The guide on the Argos blog

---

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