Cypress

Combine Argos with Cypress to stabilize screenshots, wait for fonts and images, and surface test failures.

Boost your visual testing capabilities by combining Argos with your Cypress tests.

While Cypress inherently provides screenshot functionality, the Argos Cypress integration enhances this by:

• Ensuring all images are fully loaded.
• Ensuring all fonts are rendered.
• Confirming the absence of any aria-busy (loading) elements on the page.
• Concealing scrollbars.
• Obscuring text cursors or carets.
• Providing CSS utilities to simplify content hiding.
• Gives you visibility on test failures.

Get started

Please refer to our Quickstart guide to get started with Argos and Cypress.

Set a Preview URL

Argos displays the URL of the page when a screenshot is taken, helping you understand the screenshot’s context in the Argos UI. If you run tests locally and deploy your pull requests (PRs) to a preview URL, you can link the two by setting the ARGOS_PREVIEW_BASE_URL environment variable or configuring the previewUrl option in the Cypress configuration.

Example Configuration

cypress.config.js

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

module.exports = defineConfig({
  e2e: {
    async setupNodeEvents(on, config) {
      registerArgosTask(on, config, {
        uploadToArgos: !!process.env.CI,
        previewUrl: {
          baseUrl: "https://my-site.com", // Use a dynamic value here for different environments if needed.
        },
      });
    },
  },
});

Setup individual Cypress events

Cypress only supports one handler per event. If you need to set up other handlers for the same event, you can call the individual functions provided by the SDK.

const { defineConfig } = require("cypress");
const {
  argosAfterScreenshot,
  argosAfterRun,
} = require("@argos-ci/cypress/task");

module.exports = defineConfig({
  // setupNodeEvents can be defined in either
  // the e2e or component configuration
  e2e: {
    async setupNodeEvents(on, config) {
      const argosConfig = {
        uploadToArgos: !!process.env.CI,
      };

      on("after:screenshot", async (details) => {
        // Your custom logic...

        return argosAfterScreenshot(config, details, argosConfig);
      });

      on("after:run", async (results) => {
        // Your custom logic...

        return argosAfterRun(config, results, argosConfig);
      });
    },
  },
});

API Overview

cy.argosScreenshot([name][, options])

• name: Unique name for the screenshot.
• options: Explore cy.screenshot command options for details.
• options.element: Use an ElementHandle or string selector to capture a specific element's screenshot.
• options.viewports: Define specific viewports for capturing screenshots. More on viewports configuration.
• options.argosCSS: Specific CSS applied during the screenshot process. More on injecting CSS
• options.threshold: Sensitivity threshold between 0 and 1. The higher the threshold, the less sensitive the diff will be. Defaults to 0.5.
• options.baseName: Name, or list of names, to compare this screenshot against instead of its own name. Useful to compare a variant against an existing screenshot. More on fallback baselines.
• options.stabilize: Wait for the UI to stabilize before taking the screenshot. Set to false to disable stabilization. Pass an object to customize the stabilization. Defaults to true.
• options.stabilize.disableSpellCheck: Disable spell check before taking the screenshot. Defaults to true.
• options.stabilize.fontAntialiasing: Force font antialiasing. Defaults to true.
• options.stabilize.hideCarets: Hide text carets before taking the screenshot. Defaults to true.
• options.stabilize.hideScrollbars: Hide scrollbars before taking the screenshot. Defaults to true.
• options.stabilize.loadImageSrcset: Force the loading of images with srcset attributes when the viewport changes. Defaults to true.
• options.stabilize.pauseGifs: Pause animated GIFs on their first frame so they don't capture a random frame on each run. Defaults to true. Flag GIFs served from extension-less URLs with data-image-type="gif" so they're detected too.
• options.stabilize.roundImageSize: Round image sizes to the nearest integer. Defaults to true.
• options.stabilize.stabilizeSticky: Stabilize sticky and fixed elements by switching to position: absolute. Defaults to true.
• options.stabilize.waitForAriaBusy: Wait for the aria-busy attribute to be removed from the document. Defaults to true.
• options.stabilize.waitForFonts: Wait for fonts to be loaded. Defaults to true.
• options.stabilize.waitForImages: Wait for images to be loaded. Defaults to true.
• options.stabilize.waitForBackgroundImages: Wait for CSS background images (including ::before/::after) to load before taking the screenshot. Enabled by default, scoped to elements flagged with the data-visual-test-wait-bg-img attribute (and their descendants). Pass true to scan the whole document, { selector: string } to target a custom selector, or false to disable it. A failed image (e.g. a 404) is treated as loaded so it never blocks stabilization.
• options.tag: Tag or array of tags to attach to the screenshot for filtering in Argos.

Helper Attributes for Visual Testing

For tailored visual testing, the data-visual-test attributes provide control over how elements appear in Argos screenshots. This can be especially useful for obscuring or modifying elements with dynamic content, like dates.

• [data-visual-test="transparent"]: Renders the element transparent (visibility: hidden).
• [data-visual-test="removed"]: Removes the element from view (display: none).
• [data-visual-test="blackout"]: Masks the element with a blackout effect.
• [data-visual-test-no-radius]: Strips the border radius from the element.

Example: Using a helper attribute to hide a div from the captured screenshot:

<div id="clock" data-visual-test="transparent">...</div>

registerArgosTask(on, config[, options])

• on: Cypress plugin events.
• config: Cypress config.
• options: All upload parameters.
• options.uploadToArgos: Upload results and create a build on Argos, true by default.

cypress.config.js

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

module.exports = defineConfig({
  // setupNodeEvents can be defined in either
  // the e2e or component configuration
  e2e: {
    async setupNodeEvents(on, config) {
      registerArgosTask(on, config, {
        uploadToArgos: !!process.env.CI,
      });

      // include any other plugin code...
    },
  },
});

argosAfterScreenshot(config, details[, options])

Cypress "after:screenshot" event handler.

• config: Cypress config.
• details: Screenshot details provided by Cypress.
• options: All upload parameters.
• options.uploadToArgos: Upload results and create a build on Argos, true by default.

cypress.config.js

const { defineConfig } = require("cypress");
const { argosAfterScreenshot } = require("@argos-ci/cypress/task");

module.exports = defineConfig({
  // setupNodeEvents can be defined in either
  // the e2e or component configuration
  e2e: {
    async setupNodeEvents(on, config) {
      on("after:screenshot", async (details) => {
        // Your custom logic...

        return argosAfterScreenshot(config, details, {
          uploadToArgos: !!process.env.CI,
        });
      });

      // include any other plugin code...
    },
  },
});

argosAfterRun(config, results[, options])

Cypress "after:run" event handler.

• config: Cypress config.
• results: Run results provided by Cypress.
• options: All upload parameters.
• options.uploadToArgos: Upload results and create a build on Argos, true by default.

cypress.config.js

const { defineConfig } = require("cypress");
const { argosAfterRun } = require("@argos-ci/cypress/task");

module.exports = defineConfig({
  // setupNodeEvents can be defined in either
  // the e2e or component configuration
  e2e: {
    async setupNodeEvents(on, config) {
      on("after:run", async (results) => {
        // Your custom logic...

        await argosAfterRun(config, results, {
          uploadToArgos: !!process.env.CI,
        });
      });

      // include any other plugin code...
    },
  },
});

Troubleshooting

Error while importing @argos-ci/cypress/task in cypress.config.ts

To address the ts(1479) error when importing @argos-ci/cypress/task in your cypress.config.ts, you have two main strategies:

1

Update your tsconfig.json

Set moduleResolution to "Bundler". This method leverages TypeScript's support for newer module resolution strategies, aligning with Node.js's exports feature used by Argos to distribute optimized SDKs.

2

Suppress the error in cypress.config.ts

Add the line // @ts-expect-error moduleResolution right above the import statement. This tells TypeScript to expect an error at this line and ignore it, offering a quick workaround without adjusting your project's module resolution strategy.

The first option is a more comprehensive solution, dealing with the TypeScript bug through adopting the new moduleResolution: "Bundler" setting, which is designed for such cases. The second option is simpler and quicker but bypasses the issue rather than solving it at its core.

Viewports option not working

When running Cypress in headless mode, the Cypress.viewport command (used internally by @argos-ci/cypress) may not behave as expected. This is because headless browsers don’t render a visible viewport, which can result in incorrect or inconsistent screenshots.

To ensure a consistent viewport size, configure it via setupNodeEvents in your cypress.config.js. This approach sets the viewport before the browser launches, avoiding visual regressions.

cypress.config.js

import { defineConfig } from "cypress";

export default defineConfig({
  // setupNodeEvents can be defined in either
  // the e2e or component configuration
  e2e: {
    setupNodeEvents(on, config) {
      on("before:browser:launch", (browser, launchOptions) => {
        if (browser.name === "chrome" && browser.isHeadless) {
          // fullPage screenshot size is 1400x1200 on non-retina screens
          // and 2800x2400 on retina screens
          launchOptions.args.push("--window-size=1400,1200");

          // force screen to be non-retina (1400x1200 size)
          launchOptions.args.push("--force-device-scale-factor=1");

          // force screen to be retina (2800x2400 size)
          // launchOptions.args.push('--force-device-scale-factor=2')
        }

        if (browser.name === "electron" && browser.isHeadless) {
          // fullPage screenshot size is 1400x1200
          launchOptions.preferences.width = 1400;
          launchOptions.preferences.height = 1200;
        }

        if (browser.name === "firefox" && browser.isHeadless) {
          // menubars take up height on the screen
          // so fullPage screenshot size is 1400x1126
          launchOptions.args.push("--width=1400");
          launchOptions.args.push("--height=1200");
        }

        return launchOptions;
      });
    },
  },
});

Reference: Cypress Docs – Set screen size when running headless

Additional Resources

• Quickstart with Argos + Cypress
• Example of Argos + Cypress
• @argos-ci/cypress on GitHub
• @argos-ci/cypress on npm