# Visual testing for Cypress

> Argos adds visual regression testing to Cypress. Register the Argos task, call `cy.argosScreenshot()` in your tests, and every pull request gets its visual changes diffed against the baseline from your Git history and reviewed on GitHub. Open source, and free for personal projects.

Canonical: https://argos-ci.com/integrations/cypress

Quickstart: https://argos-ci.com/docs/quickstart/cypress-quickstart
SDK reference: https://argos-ci.com/docs/reference/cypress

## Set up Argos with Cypress

### 1. Install the SDK

The Cypress SDK adds the `cy.argosScreenshot()` command and a task that uploads the screenshots.

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

### 2. Add the command

Import the support file to register `cy.argosScreenshot()`. With TypeScript, also add `@argos-ci/cypress/support` to the `types` of your `tsconfig.json`.

`cypress/support/e2e.js`:

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

### 3. Register the Argos task

The task uploads the screenshots once the run is over. Register it in `component` too if you visual-test components.

`cypress.config.js`:

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

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

### 4. Capture screenshots

`cy.argosScreenshot()` waits for fonts, images and `aria-busy` to settle and hides carets and scrollbars before it captures.

`cypress/e2e/homepage.cy.js`:

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

### 5. Run it in CI

Set `ARGOS_TOKEN` to your project token, or use GitHub Actions OIDC and skip the secret.

`.github/workflows/argos.yml`:

```yaml
- uses: cypress-io/github-action@v6
  with:
    start: npm start # serves your app
  env:
    ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}
```

## What Argos adds over image snapshot plugins

Cypress has no visual assertion of its own. Teams usually start with a plugin such as cypress-image-snapshot, which compares against images in the repository.

| | Image snapshot plugins | Argos |
| --- | --- | --- |
| Baselines | Image files committed to the repository | Picked from your Git history, nothing committed |
| Updating a baseline | Re-run in update mode, then commit the images | Approve the change in the review UI |
| Stable captures | Up to you: waits, `cy.clock()`, hiding elements | Built in: waits for fonts, images and `aria-busy`, hides carets and scrollbars |
| Several viewports | One `cy.viewport()` and one capture per size | `viewports` captures every size in one call |
| Review | Diff images in the run's artifacts | A diff viewer on every pull request, with comments and a GitHub check |
| Cost | Free | Free for personal projects, Pro at $100/month |

Sources: [Cypress visual testing guide](https://docs.cypress.io/app/tooling/visual-testing) (checked 2026-10-05).

## Why Cypress teams use Argos

- **Screenshots that don't flake**: Before each capture, the SDK waits for fonts, images and `aria-busy` to settle, hides carets and scrollbars and pins sticky elements, so the same page gives the same pixels on every run. (https://argos-ci.com/docs/reference/cypress)
- **The verdict lands on the pull request**: Argos posts a GitHub check you can make required. Reviewers open the diffs from it, approve or request changes, and the check follows their verdict. (https://argos-ci.com/review)
- **Several viewports per call**: `cy.argosScreenshot(name, { viewports })` captures each size, so responsive layouts take one line. (https://argos-ci.com/docs/learn/how-to-guides/visual-coverage/responsive-viewports)
- **A threshold you set**: `threshold` runs from 0 to 1 (default 0.5): the higher it is, the less sensitive the comparison. (https://argos-ci.com/docs/reference/cypress)
- **Mask what changes on every run**: `data-visual-test="blackout"` masks dynamic content, `transparent` hides it and keeps its space. (https://argos-ci.com/docs/learn/reliability-and-flakiness/flaky-tests/argos-helpers)

## Frequently asked questions

### How do I add visual testing to Cypress?

Install @argos-ci/cypress, import @argos-ci/cypress/support in your support file, register the Argos task in cypress.config.js, and call cy.argosScreenshot(name) in your tests. Run Cypress in CI with ARGOS_TOKEN set and Argos posts the visual changes on the pull request. See the [Cypress quickstart](https://argos-ci.com/docs/quickstart/cypress-quickstart).

### Which Cypress versions are supported?

Cypress 12 to 15.

### Does it work with component testing?

Yes. Register the Argos task in the component section of cypress.config.js as well, and call cy.argosScreenshot() in your component tests.

### Do I need a plugin like cypress-image-snapshot?

No. cy.argosScreenshot() replaces it: Argos stores the baselines and compares the screenshots, so nothing is committed to your repository and changes are reviewed on the pull request.

### How much does it cost?

Argos is free for personal projects up to 5,000 screenshots a month. Pro is $100 a month with 35,000 screenshots included, then $0.004 per screenshot.

## Keep reading

- [Cypress visual regression testing guide](https://argos-ci.com/blog/cypress-visual-regression-testing): Plugins, services and the setup that holds up in CI.
- [Argos vs Percy](https://argos-ci.com/compare/percy): The other service Cypress teams often compare.
- [How to fix flaky visual tests](https://argos-ci.com/blog/fix-flaky-visual-tests): Every root cause of a flaky screenshot, and its fix.