cypress-flowdiff

Cypress plugin for FlowDiff — adds the cy.flowSnap() command to capture named keyframe screenshots during Cypress journeys.

Install

npm install --save-dev cypress-flowdiff
# or
pnpm add -D cypress-flowdiff

Setup

1. Register the plugin (Node side)

In cypress.config.ts:

import { defineConfig } from 'cypress';
import { installFlowDiffPlugin } from 'cypress-flowdiff';

export default defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      installFlowDiffPlugin(on, config);
      return config;
    },
  },
});

2. Register the command (browser side)

In cypress/support/e2e.ts:

import { addFlowSnapCommand } from 'cypress-flowdiff';

addFlowSnapCommand();

3. Capture keyframes in your tests

describe('Login journey', () => {
  it('logs in and reaches dashboard', () => {
    cy.visit('/login');
    cy.flowSnap('login page');

    cy.get('#username').type('admin');
    cy.get('#password').type('password');
    cy.flowSnap('credentials filled');

    cy.get('[data-cy=submit]').click();
    cy.url().should('include', '/dashboard');
    cy.flowSnap('dashboard loaded');
  });
});

How it works

• cy.flowSnap('step name') takes a full-page screenshot and saves it to cypress/screenshots/flowsnap/{journeyName}/{NNN}-{sanitized-step}.png
• The journey name is derived from the spec filename (e.g. login.journey.cy.ts → login)
• Screenshot indices are tracked server-side (Node task) so they stay consistent across runs
• Screenshots are collected by the flowdiff collect CLI command and compared by flowdiff compare

Peer dependency

Requires cypress >= 12.0.0.

License

MIT