Cypress

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 visility 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_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. Default to 0.5.

• 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. Default to true.

• options.stabilize.disableSpellCheck: Disable spell check before taking the screenshot. Default to true.

• options.stabilize.fontAntialiasing: Force font antialiasing. Default to true.

• options.stabilize.hideCarets: Hide text carets before taking the screenshot. Default to true.

• options.stabilize.hideScrollbars: Hide scrollbars before taking the screenshot. Default to true.

• options.stabilize.loadImageSrcset: Force the loading of images with srcset attributes when the viewport changes. Default to true.

• options.stabilize.roundImageSize: Round image sizes to the nearest integer. Default to true.

• options.stabilize.stabilizeSticky: Stabilize sticky and fixed elements by switching to position: absolute. Default to true.

• options.stabilize.waitForAriaBusy: Wait for the aria-busy attribute to be removed from the document. Default to true.

• options.stabilize.waitForFonts: Wait for fonts to be loaded. Default to true.

• options.stabilize.waitForImages: Wait for images to be loaded. Default to true.

• 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 (visiblity: 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