Guide
Visual regression testing for Cypress
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
npm install --save-dev @snapvisor/cypressThe 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
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
import "@snapvisor/cypress/support";Capture screenshots in your specs
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.
- run: npm run build
- run: npx cypress run
env:
ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}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, Parallel testing, GitHub, GitLab, 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, Flaky test detection.
Frequently asked questions
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.
@snapvisor/cypress declares a peer dependency on Cypress 12 up to, but not including, 16.
Only if you let it. In the example config uploadToArgos is true only when the CI environment variable is set.
Resize with cy.viewport between calls and take one cy.argosScreenshot per size, as in the example. The command also accepts a viewports option.
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
Sources
Every command, package name and option on this page comes from the Snapvisor documentation and the published @snapvisor packages: