# Cypress plugin reference

Everything about `@wopee-io/wopee.cy` that [Getting started](<https://docs.wopee.io/cypress/01-getting-started/index.md>) leaves out. Applies to version 4.13.1.

## Install

```shell
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](<https://docs.wopee.io/cypress/01-getting-started/#4-register-the-plugin>)).

```javascript
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 |
| `waitForAssets`, `waitForAssetsTimeout` | no | Defaults for every track, see [Wait for fonts and images](<#wait-for-fonts-and-images>) |

`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 |
| `waitForAssets` | Wait for the page's web fonts and images before the screenshot. Default `true`. |
| `waitForAssetsTimeout` | How long that wait may take, in ms. Default `5000`. After that the screenshot is taken anyway. |
| `retryLimit` | How many times an `unresolved` step is tracked again. Default `0` since 4.13.4, so one attempt (4.13.3 and older: `2`). |
| Cypress screenshot options | For example `capture: "viewport"` |

The `responseCallback` receives `{ stepName, imageUrl, status }`:

```javascript
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:

```javascript
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](<https://docs.wopee.io/visual-testing/#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](<https://docs.wopee.io/visual-testing/#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](<https://docs.cypress.io/guides/continuous-integration/introduction>).

The repository Wopee.io creates for a Cypress project runs from Commander (**Runs** › **Start testing**), not on push; see [Template project › Run from Commander](<https://docs.wopee.io/cypress/02-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.