Skip to content

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,
  },
},
Option Required Description
apiKey yes API key from More › Settings › API Keys
projectUuid yes Project UUID from the same page
apiUrl no Default https://api.wopee.io
branchName no Branch of the run. Default master.
baselineBranchName no Branch to compare with when the current branch has no baseline yet
pixelToPixelDiffTolerance no Difference in percent that still counts as a match
customTags, comment no Free text stored with each step
os, browser, device, viewport no Labels that separate baselines per environment

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

Commands

Command Description
cy.wopeeStartSuite(name) Starts a suite. Required before the first cy.wopeeTrack().
cy.wopeeStartScenario(name) Starts a scenario inside the suite.
cy.wopeeTrack(options, responseCallback?) Takes a screenshot and sends it for comparison.
cy.wopeeStopScenario() Closes the scenario.

cy.wopeeTrack() options:

Option Description
stepName Required. Part of the baseline key <scenario name>-<step name>.
comment, customTags, viewport, pixelToPixelDiffTolerance, baselineBranchName Override the configuration for this one step
retryLimit How many times an unresolved step is tracked again. Default 2, so up to three attempts. Set 0 to track once.
Cypress screenshot options For example capture: "viewport"

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

Cypress screenshots right away. Call cy.pageReady() from Getting started › Wait until the page is ready before every track. The sample test of the template project runs the same wait inline.

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.