Cypress

Add visual regression screenshots to your Cypress E2E tests.

Prerequisites

npm install --save-dev @pxdiff/cypress

Setup

Add the pxdiff plugin to your Cypress config and support file:

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",
      });
    },
  },
});

cypress/support/e2e.ts

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

Write Tests

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

cy.get(".dialog").pxdiff("dialog-open");

Local Development

One-time setup — authenticate and link your project:

pxdiff login
pxdiff project set myorg/myproject

Run your tests with pxdiff:

pxdiff local -- npx cypress run

CI

Create an API key for your project and set it as a repository secret.

.github/workflows/visual.yml

name: Visual Regression
on: pull_request

jobs:
  visual:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 24
          cache: npm

      - run: npm ci

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

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

See the Cypress plugin reference for all command options.