Skip to main content

Argos Cypress SDK

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.

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.ariaBusy: Wait for the aria-busy attribute to be removed from the document. Default to true.
  • options.stabilize.fonts: Wait for fonts to be loaded. Default to true.
  • options.stabilize.images: Wait for images to be loaded. Default to true.

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

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 by setting 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. Alternatively, suppress the error in cypress.config.ts by adding 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.

Additional Resources​