How to Use Argos CI with Cypress Screenshots

To use Argos CI with Cypress, install @argos-ci/cypress, register its task in Cypress setupNodeEvents, import its support file, and call cy.argosScreenshot() after the page reaches the state you want to compare. Enable uploads in CI and keep the browser, viewport, data, and page state consistent between runs. Cypress can capture screenshots; Argos adds visual comparison and a review workflow.

1. Install and configure the Argos Cypress integration

Install the integration as a development dependency. Check the npm package page and the Argos Cypress documentation for the current release and API details before pinning versions; both can change.

npm install --save-dev @argos-ci/cypress

Register the Argos task in Cypress’s Node event setup. The following CommonJS example follows the documented integration pattern and only uploads when the CI environment variable is set:

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;
    },
  },
});

Import the Argos support module in the support file Cypress loads for end-to-end specs. The conventional path is cypress/support/e2e.js:

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

If the project uses a different support file, add the import to that configured file. Keep the Node task registration in the Cypress config and the support import in the browser-side support file.

2. Capture a named visual checkpoint

Visit the application, wait for a meaningful state, assert that state, and then capture it. A stable screenshot name identifies the same checkpoint across runs:

// cypress/e2e/home.cy.js
it("captures the homepage", () => {
  cy.visit("http://localhost:3000");
  cy.get("h1").should("be.visible");
  cy.argosScreenshot("homepage");
});

Use a local URL that the CI job can reach, and start the application before running Cypress. The example assumes the app serves its homepage at that address; adjust it to the test environment. Do not put changing values such as timestamps or random identifiers in the screenshot name. Argos uses the name to associate a visual checkpoint with later captures.

3. Enable uploads in CI and protect credentials

Configure the Argos project token in the CI provider’s secret store according to the Argos project setup instructions. Do not commit the token to source control or print it in job logs. The task option uploadToArgos controls whether captures are uploaded; the sample uses CI so local runs can execute without uploading.

Run Cypress in the same CI environment used for comparable baseline and pull request captures. Make sure the application is ready before Cypress starts, and ensure the CI environment sets CI to a non-empty value when uploads should be enabled.

4. Stabilize the page before comparing it

A visual diff is only useful when it compares equivalent states. Cypress recommends waiting for the application state under test and asserting that state before capturing. Use fixed fixtures or stub network responses when live data can change. Control time-dependent content, reduce animations, and use a consistent browser version and viewport for baseline and comparison runs. Cypress’s guidance covers visual testing and screenshot reliability.

Wait for readiness: assert that important content is visible or that a loading indicator is gone before taking a screenshot.
Make data repeatable: use fixtures or network stubs when API responses, account data, or ordering can vary.
Control time: freeze or otherwise stabilize dates and clocks when the page displays time-sensitive content.
Keep rendering consistent: set an explicit viewport and use the same browser and CI setup when comparing captures.
Handle motion: wait for transitions to finish or disable animation through test-only styles where appropriate.
Mask sparingly: hide or modify only content that cannot reasonably be controlled. Masking large areas can conceal actual regressions.
Choose deliberate checkpoints: capture a page or meaningful element after the test establishes its state, rather than taking incidental snapshots throughout setup.

Argos documents stabilization behavior for fonts, images, background images, aria-busy elements, carets, scrollbars, GIFs, and sticky or fixed elements. It also documents options for element capture, viewport sets, injected CSS, sensitivity threshold, alternate base names, stabilization controls, and tags. Check the current API reference for exact names, accepted values, and defaults before relying on any option: SDK behavior can change. The documented default threshold is 0.5, but confirm it in the live reference for the version installed.

5. Tune capture scope and comparison behavior

Start with the page-level capture and default stabilization. Add options only to solve a specific need:

Element capture: target a component when the page contains unrelated dynamic regions. Keep the selector unique and ensure the element is visible.
Viewport sets: capture configured viewport sizes when responsive behavior is part of the checkpoint. Keep those sizes consistent across runs.
Injected CSS: suppress motion or adjust known dynamic regions for capture. Treat injected styles as part of the test contract, since they can hide defects.
Threshold: use the documented sensitivity option to tune pixel-difference handling. A more permissive threshold may reduce noise but can also make small changes harder to detect.
Base name and tags: use these to organize or associate captures where the current SDK reference supports them. Keep the logical checkpoint stable from run to run.
Stabilization controls: leave useful waits enabled unless they conflict with the application, then change individual controls deliberately and document why.

For preview deployments, Argos documents ARGOS_PREVIEW_BASE_URL or a previewUrl.baseUrl Cypress configuration option. Follow the current reference for the expected URL and behavior.

6. Combine Argos with other Cypress event handlers

Cypress allows only one handler for an event. If another plugin already registers handlers that Argos needs, combine the work in a single handler and invoke the Argos hooks as documented, including argosAfterScreenshot and argosAfterRun where applicable. Do not register competing handlers and assume both will run. See the Argos integration reference for the current composition pattern.

7. Understand Cypress screenshots versus visual testing

cy.screenshot() saves a screenshot from Cypress. Cypress also takes screenshots for failed tests in cypress run; by default, these are stored in cypress/screenshots, and Cypress clears that directory before a run unless trashAssetsBeforeRuns is disabled. A screenshot alone does not compare the image with a baseline. The Cypress documentation explicitly says Cypress does not perform image comparison itself. Argos captures screenshots during Cypress runs and provides a workflow to review visual changes.

Choose the approach that matches the workflow you need:

Approach	What it provides	What your team manages
Cypress screenshot only	Image files for debugging or artifacts	Any comparison, baseline storage, and review process
Local visual comparison	Comparison within your own test infrastructure	Baseline images, image-diff tooling, CI artifacts, and review conventions
Argos with Cypress	Captures uploaded for hosted visual comparison and review workflow	Integration configuration, project credentials, and stable test inputs

Cypress lists other providers with Cypress integrations, including Applitools, Chromatic, Happo, LambdaTest SmartUI, Percy, Sauce Labs Visual, SmartBear VisualTest, and Wopee.io. Their presence on the integration list does not establish current prices or feature parity. Compare capture models, baseline ownership, review workflow, browser and viewport coverage, reliability controls, and current commercial terms before choosing a service.

8. Troubleshooting

Symptom	Likely cause	What to check
No Argos capture or upload appears	The support import or Node task was not loaded, or uploads are disabled locally.	Confirm the configured Cypress support file imports `@argos-ci/cypress/support`, the config calls `registerArgosTask`, and `CI` is set in the uploading job.
Upload fails in CI	The project credential is missing, invalid, or unavailable to the job.	Check the Argos project setup and CI secret mapping. Keep the token out of the repository and logs.
Screenshot is blank or incomplete	The app was not ready, the CI job could not reach its URL, or rendering resources had not loaded.	Verify the app starts before Cypress, visit the correct host, assert page readiness, and review image/font stabilization settings.
Visual diffs vary from run to run	Dynamic data, clock values, animation, fonts, viewport, or browser versions differ.	Use fixtures or stubs, control time and motion, set an explicit viewport, and align the CI rendering environment.
Headless captures have the wrong dimensions	Some headless browser configurations can produce inconsistent viewport sizing.	Set browser dimensions in Cypress’s `before:browser:launch` hook before launch, using the Argos reference’s example for the selected Chrome, Electron, or Firefox browser.
A plugin’s screenshot hook stops running	Two plugins registered competing Cypress handlers for the same event.	Use one handler and call the Argos after-screenshot and after-run hooks alongside the existing plugin behavior.
Old screenshots disappear between local runs	Cypress clears its screenshot output directory before a run by default.	Copy artifacts elsewhere before cleanup or configure `trashAssetsBeforeRuns` if retaining that directory is needed.
Changes are missed or too many diffs appear	The comparison threshold, capture scope, or masking is poorly matched to the page.	Review the current threshold semantics, narrow capture to a meaningful element when appropriate, and mask only uncontrollable content.

9. Performance, reliability, and cost

Visual capture adds browser work to the Cypress run, and uploading adds network work. Keep the number of checkpoints tied to important UI states, use element capture when a full page is unnecessary, and avoid waiting on unrelated application activity. Stabilization waits improve repeatability but can extend a test when resources never settle, so diagnose readiness conditions instead of adding arbitrary long delays.

Reliability depends on repeatable application state as much as on the screenshot service. Pin or otherwise keep browser and dependency versions consistent, use the same viewport, make fixture data deterministic, and review changes against the intended baseline. Store credentials as CI secrets. For current Argos plan costs and limits, consult its pricing information directly; no price is established by this guide’s sources.

Or skip the browser setup

If the goal is simply to capture a clean screenshot from a URL, ScreenshotNeo is a website screenshot API and MCP server. It can capture PNG, JPEG, WebP, or PDF, while Argos is the Cypress visual-testing workflow described above. See the ScreenshotNeo API documentation for options.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await require('node:fs/promises').writeFile('shot.webp', Buffer.from(await res.arrayBuffer()));

Cookie banners, popups, and chat widgets are removed before the shot; each cleanup step can be turned off.
Bot checks, blank pages, failed loads, timeouts, and cache hits are never billed, and response headers report the page verdict and billing outcome.
An MCP server lets AI agents use take_screenshot, get_page_info, and capture_pdf.
1,000 screenshots a month are free with no card; paid plans start at $5 for 3,000. Every feature is on every plan.

FAQ

Does Cypress compare screenshots by itself?

No. Cypress captures screenshots, but visual comparison requires a separate tool or service such as Argos.

Can I run the Argos command locally?

The documented setup can run Cypress locally; the example sets uploads off unless CI is present. Configure credentials and upload behavior according to your project’s needs.

Should every Cypress test take a visual screenshot?

No. Capture deliberate checkpoints that cover meaningful UI states. Excess snapshots add review work without necessarily improving coverage.

Can an Argos screenshot replace Cypress failure screenshots?

They serve different purposes. Cypress failure screenshots help diagnose test failures; Argos captures support visual comparison and review.