Argos CI with Cypress: Setup Guide for Indian Web Development Teams

To add Argos visual reviews to an existing Cypress suite, install @argos-ci/cypress, register registerArgosTask in Cypress’s setupNodeEvents, and call cy.argosScreenshot after asserting that the page has reached the state you want to review. In CI, gate uploads with uploadToArgos: !!process.env.CI and wait for your application server to be ready before Cypress starts.

The integration does not require an India-specific Cypress configuration. The official material cited here does not establish India-specific Argos pricing, taxes, payment methods, data residency, or contract terms; verify those directly with the provider before choosing a hosted service.

1. Install and register the Argos Cypress task

Install the SDK as a development dependency using your project’s package manager:

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

In a typical Cypress project using cypress.config.js, add the task registration to your existing end-to-end configuration. Keep any existing plugin setup and return the configuration object as before.

const { defineConfig } = require('cypress');
const { registerArgosTask } = require('@argos-ci/cypress');

module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      registerArgosTask(on, config, {
        uploadToArgos: !!process.env.CI,
      });

      // Retain and run any existing setupNodeEvents registrations here.
      return config;
    },
  },
});

For component tests, put the registration in the component configuration’s setupNodeEvents instead. The Argos reference supports registering under either end-to-end or component configuration.

The uploadToArgos setting is true when the environment has a truthy CI variable, which is a common way to upload only from CI. If your CI provider uses a different environment variable, set CI there or use the variable your pipeline provides in this expression. Local runs can then exercise the Cypress test without uploading visual results.

TypeScript module resolution

If TypeScript reports the documented ts(1479) import issue, Argos identifies moduleResolution: "Bundler" as the comprehensive approach. Apply it in the appropriate TypeScript configuration after checking the effect on the rest of your project’s module resolution. The Argos documentation also shows a targeted @ts-expect-error moduleResolution comment as a workaround; use that only where the specific import triggers the diagnostic.

2. Capture named screenshots after meaningful assertions

Use cy.argosScreenshot([name][, options]) to capture the view. Choose names that describe the page or state so reviewers can distinguish screenshots in the pull request.

describe('pricing page visual review', () => {
  it('captures the loaded pricing state', () => {
    cy.visit('/pricing');
    cy.get('[data-testid="pricing-table"]').should('be.visible');

    cy.argosScreenshot('pricing-page');
  });
});

Keep the assertion: screenshot stabilization helps control rendering, but it does not prove the application reached the intended state. Assert on a meaningful element or state first, then capture.

The documented screenshot options include element selection, a list of viewports, CSS injection, a comparison threshold, and stabilization controls. Use these where the review needs them. An element capture is useful for a focused component; a full-page capture is better when the page layout and below-the-fold content are part of the change. Set viewports deliberately if responsive layout matters.

Stabilization and changing data

Argos enables stabilization by default. Its controls can wait for fonts and images, wait for aria-busy to be removed, and hide carets or scrollbars. These controls reduce irrelevant variation, but they cannot make different application data equivalent.

For unstable values such as dates or clocks, Argos documents data-visual-test helpers including transparent, removed, and blackout. Mask only the dynamic content that is irrelevant to the visual assertion. Keep the surrounding layout and meaningful visible behavior in the comparison so that real regressions remain detectable.

For example, apply the supported helper value to the changing element in the application markup according to the Argos documentation, then capture as usual:

<time data-visual-test="blackout">2026-10-04 09:30</time>

Choose a viewport list when the same state needs review at multiple sizes. Use CSS injection only to normalize or adjust presentation that is intentionally outside the test’s purpose; do not hide the component or layout whose changes the test is meant to catch. Set a comparison threshold only when small rendering differences are expected and understood.

3. Run Cypress reliably in CI

The test runner needs the application server to be accepting requests before Cypress begins. Starting the server in the background and immediately starting tests creates a readiness race: the first test can visit the app before it is available.

Cypress documents readiness approaches including its GitHub Action’s start and wait-on inputs, start-server-and-test, and wait-on. For a GitHub Actions workflow, the maintained Cypress action accepts a build command and a server start command, then waits on the configured URL:

name: Cypress visual tests

on:
  pull_request:

jobs:
  cypress:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - uses: cypress-io/github-action@v7
        with:
          build: npm run build
          start: npm run start -- --port 3000
          wait-on: 'http://localhost:3000'
          wait-on-timeout: 120
          browser: chrome

This example assumes your project defines the shown build and start scripts and serves the app at that URL. Adapt the commands, URL, runner, Node version, browser, and action version to the project and recheck current Cypress guidance before publication or adoption; action and browser recommendations can change.

Preview URL association

If the pull request has a deployed preview, Argos can associate the result with it. Configure ARGOS_PREVIEW_URL in the CI environment or provide the previewUrl Cypress option. A preview URL helps reviewers move between the visual result and the running change.

Parallel jobs

Cypress documents splitting installation from worker jobs for parallel execution. The cited setup requires recording to Cypress Cloud for parallel Cypress execution. Decide whether that recording and its service requirements fit your team’s workflow before adding workers; do not assume that simply launching more jobs will coordinate test distribution.

4. Keep screenshots comparable

A visual difference may come from an application change or from changing test data, timing, fonts, browser, operating system, or viewport. Keep those rendering inputs consistent, wait for the page’s meaningful state, and use Argos stabilization for fonts, images, busy state, carets, and scrollbars as appropriate.

Headless viewport differences can also affect results. Argos documents configuring the window size and device scale factor in Cypress’s before:browser:launch event. Set these values consistently when your CI browser renders at a different size or scale than expected. Treat stabilization as a way to remove incidental noise, not as a substitute for assertions or a stable test environment.

Reviewing a visual change

Confirm the test assertion passed and that the screenshot represents the intended state.
Review the diff in the context of the pull request and the associated preview, if configured.
Approve an intentional design change through your team’s review process.
If the diff is unexpected, check dynamic content, readiness, fonts, viewport, browser, and scale before changing thresholds or masking more content.

5. Choose hosted review or self-managed comparisons

Cypress describes two broad approaches. Open-source visual testing plugins keep image comparison and baseline management in your own infrastructure, often using pixel-by-pixel comparisons. Your team owns review flow and the consistency of the rendering environment. Hosted visual testing services manage more of capture, storage, comparison, and review, often with pull-request workflows and cross-browser or viewport rendering, in exchange for subscription cost.

Cypress lists Argos, Applitools Eyes, Chromatic, Happo, LambdaTest SmartUI, Percy, SmartBear VisualTest, and Wopee.io as services with Cypress integrations. Compare services using criteria that matter to your team: cost, baseline ownership, review workflow, infrastructure and data requirements, browser and viewport coverage, and the stabilization controls available. The sources used for this guide do not verify regional commercial terms for these providers.

Or skip the browser setup

If your task is to get a screenshot of a URL rather than add pull-request visual regression review to Cypress, ScreenshotNeo is a website screenshot API and MCP server for developers. One GET request returns a PNG, JPEG, WebP, or PDF. It complements this Argos workflow; it does not replace Argos’s Cypress visual review.

For example, this cURL request saves a WebP screenshot. See the ScreenshotNeo API docs for the available options.

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

Python:

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)

Node.js:

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

ScreenshotNeo accepts cookie and consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers report the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots a month without a card; paid plans start at $5 for 3,000 shots. Sign up free for 1,000 screenshots a month, with no card required.

Troubleshooting

Symptom	Likely cause	What to do
Argos task is unavailable or screenshots do not upload	`registerArgosTask` was not called in the active Cypress configuration, or upload gating is false.	Register it in the relevant end-to-end or component `setupNodeEvents`; inspect the CI environment and the value of `uploadToArgos`.
TypeScript reports `ts(1479)`	Module resolution is incompatible with the import shape.	Use the documented `moduleResolution: "Bundler"` configuration after considering project impact, or the targeted documented suppression workaround.
Tests fail to visit the local application at startup	Cypress began before the server was ready.	Use a readiness check such as the Cypress Action’s `wait-on`, `start-server-and-test`, or `wait-on`.
Screenshots differ on every run	Changing data, timing, fonts, viewport, scale, browser, or operating system.	Assert on the intended state, wait for required content, stabilize supported rendering inputs, and mask only irrelevant changing values.
Images or fonts appear missing in the capture	The page was captured before resources finished loading.	Use the stabilization controls for images and fonts and assert that the relevant page state is ready before capture.
Headless CI layout differs from local layout	Window size or device scale factor differs.	Configure window size and scale factor through Cypress’s `before:browser:launch` event and keep the CI browser consistent.
Too many diffs are hidden after masking	Masking covers meaningful content or layout.	Reduce the masked area and retain the surrounding structure so the comparison still catches meaningful regressions.

Performance, reliability, and cost

For more dependable runs, capture only states that carry review value, wait for server readiness, and avoid unnecessary viewport variants. Multiple viewport captures increase the amount of visual output to review. Parallel Cypress workers can reduce elapsed test time when properly coordinated, but the documented Cypress parallel setup requires Cypress Cloud recording.

Reliable comparisons depend on stable application data and rendering inputs. Argos stabilization can wait for common resources and busy-state signals, but it cannot guarantee identical output if the application, test data, or browser environment changes.

The cited Argos and Cypress documents do not establish the current Argos price, India-specific taxes or payment options, data residency, or contractual terms. Check those details with the provider. When comparing hosted review against self-managed baselines, include both subscription costs and the engineering work needed to maintain infrastructure and review flow.

FAQ

Does an Indian team need a different Cypress or Argos setup?

The documented integration is based on the JavaScript package and Cypress configuration. These sources describe no India-specific installation procedure.

Can I capture a Cypress screenshot locally without uploading it?

Yes. The documented CI-only pattern sets uploadToArgos from the CI environment variable, so local execution can leave uploads disabled.

Does Argos stabilization remove all visual flakiness?

No. It can stabilize certain rendering conditions, but tests still need meaningful assertions and controlled data and render environments.

Do the available sources confirm Argos data residency in India?

No. The reviewed official setup material does not establish India-specific data-location or contract terms. Ask the provider directly before relying on a particular arrangement.

Primary references: Argos Cypress integration; Cypress documentation for GitHub Actions, continuous integration, and visual testing.