# Visual regression testing for Cypress

> Add visual regression testing to Cypress with @snapvisor/cypress: register one task, call cy.argosScreenshot, and review the diffs on your pull requests.

Source: https://snapvisor.io/cypress

Guide

Keep your Cypress specs. @snapvisor/cypress adds a task that uploads screenshots when the run finishes and a cy.argosScreenshot command that captures them. Snapvisor compares each screenshot with the approved baseline and posts the result as a status check on your pull request.

## Install the package

shell

```
npm install --save-dev @snapvisor/cypress
```

The package declares Cypress 12 up to, but not including, 16 as its peer range (`cypress >=12 <16`).

Create a project in the Snapvisor app and copy its project token (`ARGOS_TOKEN`) from the project settings. Store it as a CI secret, never in the repository.

## Register the task and the command

Register the task in your Cypress config. It uploads the screenshots when the run finishes:

cypress.config.js

```
// cypress.config.js
const { defineConfig } = require("cypress");
const { registerArgosTask } = require("@snapvisor/cypress/task");

module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      registerArgosTask(on, config, {
        // Upload the screenshots only on CI.
        uploadToArgos: !!process.env.CI,
      });
      return config;
    },
  },
});
```

Then import the command in your support file:

cypress/support/e2e.js

```
// cypress/support/e2e.js
import "@snapvisor/cypress/support";
```

## Capture screenshots in your specs

Cypress spec

```
describe("Homepage", () => {
  it("renders", () => {
    cy.visit("http://localhost:3000");
    cy.viewport(768, 1024);
    cy.argosScreenshot("homepage-768");
    cy.viewport(1200, 900);
    cy.argosScreenshot("homepage-1200");
  });
});
```

Resizing with `cy.viewport()` between calls is plain Cypress. `cy.argosScreenshot` stabilizes the UI before it captures unless you set `stabilize: false`.

Its options include `viewports`, `argosCSS`, `threshold`, `stabilize` and `tag`, on top of Cypress's own screenshot options. To keep an element out of a screenshot, hide it with `argosCSS`.

## Run it in CI

Nothing wraps the test command. Run `npx cypress run` as you normally do; the token comes from the environment.

GitHub Actions

```
- run: npm run build
- run: npx cypress run
  env:
    ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}
```

A green CI job after the upload means the screenshots arrived, not that they are unchanged. The gate is the status check Snapvisor posts to the pull request, so require it in your branch protection rules.

On GitHub Actions you can skip the token with tokenless authentication. Large suites can shard their uploads across CI jobs and be reviewed as one build.

Read more: [GitHub tokenless authentication](https://snapvisor.io/docs/learn/integrations/github-tokenless-authentication), [Parallel testing](https://snapvisor.io/docs/parallel-testing), [GitHub](https://snapvisor.io/docs/github), [GitLab](https://snapvisor.io/docs/gitlab), [Review workflow](https://snapvisor.io/docs/review-workflow).

## What the first build does

The first build on your base branch has nothing to compare against, so it becomes the baseline and is approved automatically. Run it on a base branch that already looks right. Later builds are diffed against the last approved build on the base branch, and approving a change promotes it to the new baseline for that branch.

Read more: [Baseline builds](https://snapvisor.io/docs/baseline-build), [Flaky test detection](https://snapvisor.io/docs/flaky-test-detection).

## Frequently asked questions

### Do I have to rewrite my Cypress specs?

No. You keep your specs and your Cypress config. Register the Snapvisor task, import the support file, and call cy.argosScreenshot where you want a screenshot compared.

### Which Cypress versions does the package support?

@snapvisor/cypress declares a peer dependency on Cypress 12 up to, but not including, 16.

### Does the task upload from my laptop?

Only if you let it. In the example config uploadToArgos is true only when the CI environment variable is set.

### How do I capture a page at several widths?

Resize with cy.viewport between calls and take one cy.argosScreenshot per size, as in the example. The command also accepts a viewports option.

### Does a green CI job mean nothing changed?

No. It means the screenshots arrived. The gate is the status check Snapvisor posts to the pull request, so require that check in branch protection.

## Where to go next

[**Visual regression testing in GitHub pull requests**What appears on the pull request and how a reviewer clears it.](https://snapvisor.io/visual-regression-testing-github) [**Visual regression testing guide**How the capture, compare and review loop works.](https://snapvisor.io/visual-regression-testing)

## Sources

Every command, package name and option on this page comes from the Snapvisor documentation and the published `@snapvisor` packages:

- [SDKs](https://snapvisor.io/docs/sdks)
- [Migrate from Percy](https://snapvisor.io/docs/migrate-from-percy)
- [Getting started](https://snapvisor.io/docs/getting-started)
- [CI integration](https://snapvisor.io/docs/ci-integration)
- [Baseline builds](https://snapvisor.io/docs/baseline-build)
- [Review workflow](https://snapvisor.io/docs/review-workflow)

## Try Snapvisor free

[Start free](https://app.snapvisor.io/signup) [Getting started guide](https://snapvisor.io/docs/getting-started) [All SDKs](https://snapvisor.io/docs/sdks) [See pricing](https://snapvisor.io/pricing)

## Related pages

Guides [How visual regression testing works](https://snapvisor.io/visual-regression-testing) [Self-hosted visual regression testing](https://snapvisor.io/self-hosted-visual-regression-testing) [Visual regression testing in GitHub pull requests](https://snapvisor.io/visual-regression-testing-github) [Snapvisor MCP server](https://snapvisor.io/mcp)

Test runner and CI setup [Playwright visual testing setup](https://snapvisor.io/playwright) [Storybook visual testing setup](https://snapvisor.io/storybook) [Puppeteer visual testing setup](https://snapvisor.io/puppeteer) [Visual regression testing in GitLab CI](https://snapvisor.io/gitlab-ci)

Compare Snapvisor [Snapvisor vs Percy](https://snapvisor.io/compare/percy) [Snapvisor vs Chromatic](https://snapvisor.io/compare/chromatic) [Snapvisor vs Applitools](https://snapvisor.io/compare/applitools) [Snapvisor vs Argos](https://snapvisor.io/compare/argos) [Snapvisor vs Lost Pixel](https://snapvisor.io/compare/lost-pixel) [Snapvisor vs Happo](https://snapvisor.io/compare/happo) [Snapvisor vs Playwright snapshots](https://snapvisor.io/compare/playwright) [Visual regression testing pricing compared](https://snapvisor.io/visual-regression-testing-pricing) [Alternatives to other visual testing tools](https://snapvisor.io/alternatives)

Free tools [Image diff checker](https://snapvisor.io/tools/image-diff) [Screenshot calculator](https://snapvisor.io/tools/screenshot-calculator)
