Cypress Debugger

Capture and replay Cypress Tests. Debug your failed and flaky CI cypress tests by replaying execution traces.

• Cypress test execution steps
• DOM snapshots
• network requests (HAR)
• browser console logs

The plugin captures and replays everything that's happening in Cypress tests, think of it as Playwright traces for Cypress.

Video Demo | Sorry Cypress | Currents

Requirements

• Cypress version 10+
• NodeJS ^14.17.0
• Chromium family browsers only

Setup

Install the package:

npm install cypress-debugger

Add cypress-debugger to cypress.config.{js|ts|mjs}

// cypress.config.js
const { defineConfig } = require('cypress');
const { debuggerPlugin } = require('cypress-debugger');
module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      debuggerPlugin(on, {
        meta: {
          key: 'value',
        },
        // path: abosulte path to the dump file
        // data: captured data
        callback: (path, data) => {
          console.log({
            path,
            data,
          });
        },
      });
      return config;
    },
  },
});

Add cypress-debugger to cypress/support/e2e.{js|ts}

// cypress/support/e2e.js
const { debuggerSupport } = require('cypress-debugger');
debuggerSupport();

Usage

Configure the plugin as documented above. Use the callback function to fetch the location of the replay file you can open in the player. Get the test execution information from the dump directory, relative to the cypress configuration file.

Analyze the information using the debugger web app.

Chrome / Chromium

npx cypress run --chrome

Electron

Set the remote-debugging-port via ELECTRON_EXTRA_LAUNCH_ARGS environment variable:

ELECTRON_EXTRA_LAUNCH_ARGS=--remote-debugging-port=9222 npx cypress run --browser electron

Example

See an example in apps/web directory.

Plugin: debuggerPlugin

Installs cypress-debugger.

debuggerPlugin(on: Cypress.PluginEvents, options?: PluginOptions): void

• on - Cypress.PluginEvents setupNodeEvents method first argument
• options - PluginOptions:
  • meta: Record<string, unknown>: an optional field that is added to the TestExecutionResult as pluginMeta
  • callback: (path: string, data: TestExecutionResult: a callback function that will be called after each test

Example:

// cypress.config.js
const { defineConfig } = require('cypress');
const { debuggerPlugin } = require('cypress-debugger');
module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      debuggerPlugin(on, {
        meta: {
          key: 'value',
        },
        callback: (path, data) => {
          console.log({ path, data });
        },
      });
      return config;
    },
  },
});

Support File: debuggerSupport

Attaches required handlers to Cypress events

debuggerSupport(): void