Cypress Plugin

The @pxdiff/cypress package integrates pxdiff into Cypress E2E tests. Take screenshots during tests and get instant diff results against baselines.

Installation

npm install --save-dev @pxdiff/cypress

Peer dependency: cypress >= 13

Setup

1. Configure Plugin

Register the pxdiff plugin in your Cypress config:

cypress.config.ts

import { pxdiffPlugin } from "@pxdiff/cypress/plugin";
import { defineConfig } from "cypress";

export default defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      return pxdiffPlugin(on, config, {
        suite: "my-app",
      });
    },
  },
});

2. Register Command

Import @pxdiff/cypress in your support file:

cypress/support/e2e.ts

import { setupPxdiff } from "@pxdiff/cypress";
setupPxdiff();

This registers the cy.pxdiff() custom command.

3. Set Environment Variables

export PXDIFF_API_KEY=pxd_your_key_here

Usage

Use the cy.pxdiff() command to take screenshots and diff them against baselines:

// Viewport screenshot
cy.visit("/");
cy.pxdiff("homepage");

// Element screenshot
cy.get(".dialog").pxdiff("dialog-open");

// With options
cy.pxdiff("checkout-page", {
  ignoreSelectors: [".dynamic-timestamp"],
  maxDiffPixelRatio: 0.01,
  path: ["pages", "Checkout"],
});

// Full-page screenshot
cy.pxdiff("landing-page", { fullPage: true });

---

pxdiffPlugin(on, config, options?)

Registers pxdiff tasks and event handlers in Cypress’s Node.js process. Call this in setupNodeEvents.

Option	Type	Default	Description
suite	string	"cypress"	Suite name for grouping snapshots
blocking	boolean	true	Whether changed snapshots fail the test
apiUrl	string	PXDIFF_API_URL or "https://pxdiff.com"	API URL
git.branch	string	(auto-detected)	Git branch override
git.commit	string	(auto-detected)	Git commit override
local	boolean	(auto-detected)	Local mode (from PXDIFF_LOCAL or absence of CI)
autoApprove	boolean	(auto-detected)	From PXDIFF_AUTO_APPROVE

---

cy.pxdiff(name, options?)

Custom command that takes a screenshot, uploads it, and asserts on the diff result.

Can be called standalone or chained on an element:

cy.pxdiff("full-page");
cy.get(".component").pxdiff("component-name");

Option	Type	Default	Description
blocking	boolean	(from plugin)	Override blocking mode for this snapshot
ignoreSelectors	string[]		CSS selectors to hide via visibility: hidden
maxDiffPixelRatio	number		Max acceptable diff ratio (0–1). Pass if below this
path	string[]		Display hierarchy path for tree grouping in review UI
fullPage	boolean	false	Capture full scrollable page instead of viewport

Ignore Selectors

Elements matching ignoreSelectors are hidden with visibility: hidden before the screenshot is taken. The CSS is cleaned up immediately after.

In addition, elements with data-pxdiff="ignore" or data-chromatic="ignore" attributes are always hidden:

<span data-pxdiff="ignore">Dynamic content here</span>

Full-Page Screenshots

When fullPage: true, Cypress captures the full scrollable page by scrolling and stitching multiple viewports. Elements with position: fixed or position: sticky will repeat in every stitched segment. Prefer viewport screenshots for pages with sticky headers or navbars.

Pass/Fail Logic

The command determines pass/fail as follows:

• Pass: unchanged, new, auto-approved, within maxDiffPixelRatio, non-blocking mode, or CI mode (soft-fail)
• Fail: changed snapshots exceeding the threshold in blocking mode

In CI mode (when PXDIFF_SESSION_ID is set and not local), the command always passes. The pxdiff GitHub check run reports the overall result.

---

CI Integration

With pxdiff run

The recommended approach for CI is to wrap your Cypress tests with pxdiff run:

.github/workflows/visual.yml

- name: Visual Regression
  run: pxdiff run -- npx cypress run
  env:
    PXDIFF_API_KEY: ${{ secrets.PXDIFF_API_KEY }}

This creates a GitHub check run, groups all screenshots into one session, and reports results back to the PR.

Standalone

You can also run Cypress tests without pxdiff run. Screenshots are still uploaded and diffed individually:

- name: Visual Tests
  run: npx cypress run
  env:
    PXDIFF_API_KEY: ${{ secrets.PXDIFF_API_KEY }}

---

Environment Variables

Variable	Description
PXDIFF_API_KEY	(required) API authentication key
PXDIFF_API_URL	API base URL (default: https://pxdiff.com)
PXDIFF_SESSION_ID	Session ID for grouping (set by pxdiff run)
PXDIFF_LOCAL	Set to true for local development mode
PXDIFF_AUTO_APPROVE	Set to true to auto-approve all changes
PXDIFF_BRANCH	Override git branch detection
PXDIFF_COMMIT	Override git commit detection