Skip to main content

Integrating Argos with Cypress for Visual Testing

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.

1. Setting Up​

Installation of Packages​

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

Add cy.argosScreenshot command​

And add this line to your cypress/support/index.js file.

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

2. Use in your tests​

cy.argosScreenshot command stabilizes the UI before capturing the screenshot.

describe("Homepage", () => {
  it("screenshots the page", () => {
    // Screenshot a full page
    cy.argosScreenshot("home");

    // Screenshot a component
    cy.get("main div.breadcrumb").argosScreenshot("home-breadcrumb");
  });
});

By default screenshots are stored in cypress/screenshots folder, relative to current directory.

3. Upload screenshots to Argos​

Look at Argos doc to know how to configure your CI to send screenshots to Argos.

As Cypress store the screenshots into the "cypress/screenshots" folder by default, have to specify it when you use Argos CLI command: npx @argos-ci/cli upload cypress/screenshots.

TypeScript support​

Typings should be added as follows in tsconfig.json:

{
  "compilerOptions": {
    "types": ["cypress", "@argos-ci/cypress"]
  }
}

You can find library definition here.

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.

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>

Additional Resources​