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 CSSoptions.threshold
: Sensitivity threshold between 0 and 1. The higher the threshold, the less sensitive the diff will be. Default to0.5
.
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.
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:
-
Update your
tsconfig.json
by settingmoduleResolution
to"Bundler"
. This method leverages TypeScript's support for newer module resolution strategies, aligning with Node.js'sexports
feature used by Argos to distribute optimized SDKs. -
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.