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>