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.
Set up Argos with Cypress
5 steps, then every pull request gets a visual check. The quickstart covers every option.
Install the SDK
The Cypress SDK adds the cy.argosScreenshot() command and a task that uploads the screenshots.
npm i --save-dev @argos-ci/cypressAdd 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.
import "@argos-ci/cypress/support";Register the Argos task
The task uploads the screenshots once the run is over. Register it in component too if you visual-test components.
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,
});
},
},
});Capture screenshots
cy.argosScreenshot() waits for fonts, images and aria-busy to settle and hides carets and scrollbars before it captures.
it("homepage", () => {
cy.visit("http://localhost:3000/");
cy.argosScreenshot("homepage");
});Run it in CI
Set ARGOS_TOKEN to your project token, or use GitHub Actions OIDC and skip the secret.
- 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.
| Topic | 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, checked October 2026.
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.
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.
Several viewports per call
cy.argosScreenshot(name, { viewports }) captures each size, so responsive layouts take one line.
A threshold you set
threshold runs from 0 to 1 (default 0.5): the higher it is, the less sensitive the comparison.
Mask what changes on every run
data-visual-test="blackout" masks dynamic content, transparent hides it and keeps its space.
Cypress visual testing FAQ
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.
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.
Cypress visual regression testing guide
Plugins, services and the setup that holds up in CI.
Learn moreSupercharge your product quality
See every change your team and your agents make. Review with confidence, and merge faster.