To send Cypress screenshots to Argos CI for visual review, install @argos-ci/cypress, register its task in Cypress’s Node event setup, import its support file, and call cy.argosScreenshot() after the page reaches the state you want to compare. Argos adds the baseline and visual-diff workflow; Cypress’s built-in screenshot command alone does not compare images.
What Argos adds to Cypress screenshots
Cypress can save screenshots during a test run, including failure screenshots, but it does not perform image comparison itself. Argos captures screenshots during Cypress runs and provides a review workflow for visual changes, including CI and pull-request integration. See Cypress’s visual testing guide and the Argos Cypress integration reference.
As an Amazon Associate I earn from qualifying purchases.
The setup below uses the official JavaScript package, @argos-ci/cypress. The package registry’s version can change, so check its npm page before pinning a version. The code follows the documented integration pattern; it is not a claim of independent testing.
Install and configure the Cypress integration
1. Add the package
From the project root, install the package as a development dependency:
npm install --save-dev @argos-ci/cypress2. Register the Argos task
In cypress.config.js, register registerArgosTask inside setupNodeEvents. This CommonJS example enables uploads when the CI environment variable is present, while allowing local runs without uploading:
const { defineConfig } = require("cypress");
const { registerArgosTask } = require("@argos-ci/cypress/task");
module.exports = defineConfig({
e2e: {
setupNodeEvents(on, config) {
registerArgosTask(on, config, {
uploadToArgos: !!process.env.CI,
});
return config;
},
},
});If your configuration uses ES modules or a different Cypress configuration structure, preserve the same integration steps but adapt the module syntax to your project.
3. Load the support file
Import the Argos support module from the Cypress support file, conventionally cypress/support/e2e.js:
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemsimport "@argos-ci/cypress/support";4. Capture a named checkpoint in a test
Visit the page and establish the intended state before taking the Argos screenshot. Use a stable, descriptive name that identifies the same visual checkpoint across runs:
// cypress/e2e/home.cy.js
it("captures the homepage", () => {
cy.visit("http://localhost:3000");
cy.argosScreenshot("homepage");
});The sample assumes the application is available at http://localhost:3000; replace it with the URL appropriate to your test environment.
Enable uploads safely in CI
Configure the Argos project token in your CI provider’s secret or environment-variable settings according to Argos’s project setup. Do not commit the token to the repository. With uploadToArgos: !!process.env.CI, screenshots upload when CI is set and do not upload in an ordinary local run. Consult Argos’s Cypress documentation for current authentication and project setup details.
Make visual comparisons reliable
A screenshot can differ even when the intended UI has not changed. Stabilize the page and its rendering environment before treating a diff as a product regression.
Free tools Windows power users keep installed
One-click scans. No signup required.
Wait for the right application state
- Wait for the data and UI state under test, then assert that state before capturing. Avoid snapshots taken while rendering, animation, or network work is still in progress.
- Use fixtures or network stubs when API responses would otherwise vary from run to run.
- Control the clock and time-dependent content, such as timestamps, countdowns, or rotating promotions.
Keep rendering conditions consistent
- Set an explicit Cypress viewport and use consistent CI rendering conditions for baselines and comparison runs.
- Where possible, keep browser versions pinned and use the same browser and environment for both runs.
- Use a meaningful page or element checkpoint rather than capturing incidental states throughout the test.
Use Argos stabilization options deliberately
Argos documents stabilization behavior including waiting for fonts and images, waiting for elements marked aria-busy to clear, hiding text carets and scrollbars, pausing GIFs, and stabilizing sticky or fixed elements. Its screenshot API also documents element capture, viewport sets, injected CSS, tags, alternate baseName values, and a comparison threshold whose reference default is 0.5. These details and defaults may change, so check the current API reference before relying on a particular default.
Hide or modify only the dynamic regions you cannot make deterministic. Argos provides CSS utilities for concealing or modifying dynamic content; masking too much can hide genuine visual regressions.
Handle headless viewport inconsistencies
Argos notes that Cypress viewport behavior can be inconsistent in some headless configurations. If screenshots have the wrong dimensions or vary between headless runs, set the browser dimensions in Cypress’s before:browser:launch hook before the browser starts. The Argos reference provides examples for Chrome, Electron, and Firefox; use the matching example for the browser you run and confirm the resulting viewport in CI.
Combine Argos with existing Cypress event handlers
Cypress supports only one handler per event. If another plugin already registers the relevant event handlers, do not simply add a second competing handler. Argos documents calling its argosAfterScreenshot and argosAfterRun handlers from your existing custom handlers so both integrations can run.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →When to use Cypress screenshots versus Argos
Cypress’s cy.screenshot() saves images in interactive and run modes, and Cypress automatically captures screenshots on test failure during cypress run. The default output directory is cypress/screenshots; Cypress clears it before a run unless trashAssetsBeforeRuns is disabled. Use these built-in captures when you need artifacts for debugging. Use Argos when you also need a visual baseline and review workflow.
For broader visual testing, Cypress lists integrations including Argos, Applitools, Chromatic, Happo, LambdaTest SmartUI, Percy, Sauce Labs Visual, SmartBear VisualTest, and Wopee.io. The integration list establishes that these providers support Cypress, not their current prices or which service fits a particular project. Compare whether captures render in the test browser or through a service, how baselines and reviews work, which browsers and viewport widths are covered, and what controls exist for dynamic content. Verify current commercial terms directly with each provider.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Troubleshooting
No Argos screenshots appear in the build
- Confirm that
registerArgosTaskruns insidesetupNodeEventsand that the support import is loaded by the Cypress support file. - Check that the test calls
cy.argosScreenshot()and thatCIis set in the CI job when uploads are intended. - Verify the Argos project authentication is configured in CI secrets, not only on a developer’s machine.
The screenshot is captured too early or diffs on every run
Assert the required page state before capture. Control variable API responses and time-dependent content, wait for fonts and images where needed, and remove only uncontrolled dynamic regions with CSS. Keep viewport and browser conditions consistent.
The headless capture has unexpected dimensions
Set browser dimensions in before:browser:launch for the browser used in CI. Cypress viewport settings and the launched browser’s dimensions are separate parts of the rendering setup; confirm both when diagnosing mismatches.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →An event plugin stops working after adding Argos
Check for duplicate Cypress handlers. Keep one handler for the event and invoke Argos’s documented after-screenshot and after-run callbacks from it where applicable.
Local screenshots are missing after a run
Cypress clears cypress/screenshots before runs by default. Set trashAssetsBeforeRuns to false if retaining that directory between runs is required; otherwise copy or process artifacts as part of the test workflow.
Or skip the browser setup
If your goal is a website screenshot rather than a Cypress visual-regression test, ScreenshotNeo can return an image or PDF from one request. Its capture flow accepts cookie banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each cleanup step can be disabled. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers report the page verdict and billing status. ScreenshotNeo also provides an MCP server for AI agents.
cURL example; see the ScreenshotNeo API documentation for parameters:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo is a separate screenshot API, not an Argos visual-diff integration; it returns a capture and does not replace Argos’s Cypress baseline-review workflow. Its free plan includes 1,000 screenshots per month with no card, and paid plans start at $5 for 3,000. Sign up for ScreenshotNeo free.
Frequently Asked Questions
Does Cypress compare screenshots by itself?
No. Cypress can capture screenshots, but visual baseline comparison requires a separate tool or service such as Argos.
Can I use Argos screenshots locally without uploading them?
Yes. The documented configuration can set uploads to run only when the CI environment variable is present, so local runs need not upload.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
