Cypress plugin reference

Everything about @wopee-io/wopee.cy that Getting started leaves out. Applies to version 4.13.1.

Install

npm install -D @wopee-io/wopee.cy dotenv

Supported Cypress versions: 13 to 16. Cypress is a peer dependency: the plugin uses your project's Cypress and installs no copy of its own. Cypress 16 needs Node.js 22 or 24.

Version 4.12.2 and older support Cypress 13 and 14 only: on Cypress 15 and newer the spec fails to load with Class extends value undefined is not a constructor or null. They also install their own copy of Cypress 13, which downloads an extra Cypress binary during npm install. Update with npm install -D @wopee-io/wopee.cy@latest.

Configuration

The plugin reads only the wopee object in the env section of the Cypress config. Register it with addWopeePlugin(on, config) in setupNodeEvents and the commands with addWopeeCommands() in the support file (see Getting started).

env: {
  wopee: {
    apiUrl: process.env.WOPEE_API_URL,
    apiKey: process.env.WOPEE_API_KEY,
    projectUuid: process.env.WOPEE_PROJECT_UUID,
    branchName: process.env.WOPEE_BRANCH_NAME,
  },
},

WOPEE_* variables that are not mapped into this object have no effect.

Commands

cy.wopeeTrack() options:

The responseCallback receives { stepName, imageUrl, status }:

cy.wopeeTrack({ stepName: "Products" }, (result) => {
  cy.task("log", `${result.stepName}: ${result.status}`);
});

cy.task("log") needs a log task registered in setupNodeEvents.

One element

Chain cy.wopeeTrack() after cy.get() to capture one element:

cy.get(".inventory_list").wopeeTrack({ stepName: "Product list" });

Wait for fonts and images

From 4.13.4, cy.wopeeTrack() loads every web font face and decodes every image of the page before it takes the screenshot, for up to waitForAssetsTimeout ms. A font or image that fails to load is skipped; one still loading at the timeout is written to the command log and the screenshot is taken anyway, so the test does not fail.

• Lazy images (loading="lazy") outside the viewport and CSS background images are not awaited. Wait for such content with cy.get(...).should("be.visible") before the track.
• Set waitForAssets and waitForAssetsTimeout for every track in the wopee object, or for one step in cy.wopeeTrack(); the step option wins.
• 4.13.3 and older take the screenshot right away. Update the plugin, or wait for the fonts and images yourself as in Wait for fonts and images before tracking.

Branches and suites

• Baselines are kept per branch. Set branchName from your CI, for example branchName: process.env.WOPEE_BRANCH_NAME with WOPEE_BRANCH_NAME=$GITHUB_REF_NAME.
• A suite is identified by its name and branch: the same suite name on the same branch adds to the existing entry in Runs. Use a timestamp or build number in the suite name.
• See Baselines and branches for merging and managing baselines.

Run in CI

Wopee.io works with any CI system. Set WOPEE_PROJECT_UUID and WOPEE_API_KEY as secrets of your CI (plus WOPEE_API_URL for a self-hosted instance) and run npx cypress run as usual. Cypress' own guides: Continuous Integration.

The repository Wopee.io creates for a Cypress project runs from Commander (Runs › Start testing), not on push; see Template project › Run from Commander.

Known issues in 4.13.1

• An unresolved step never fails the test, also with enableSoftAssert set. Use the responseCallback to act on the status.
• Ignore areas passed to cy.wopeeTrack() are not sent. Draw ignore areas in the Commander comparison view instead.
• The npm README Quick Start is outdated: it uses flat WOPEE_* keys in cypress.env.json and cy.wopeeTrack('name'). Use the setup on this page.