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. The player is available at: https://cypress-debugger.dev

Video Demo | Player | Sorry Cypress | Currents

Requirements

Cypress version 10+
NodeJS ^14.17.0
Chromium family browsers only
Requires alternative cypress binaries due to Cypress.io blocking

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, config, {
        meta: {
          key: 'value',
        },
        // path: absolute 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 --browser 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
Example of integrating with Currents: https://github.com/currents-dev/gh-actions-example/tree/debugger-example

API

Plugin: `debuggerPlugin`

Installs cypress-debugger.

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

on - Cypress.PluginEvents setupNodeEvents method first argument
config - Cypress.PluginConfig setupNodeEvents method second 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
- targetDirectory: string: the path to the reports directory. Default is dump
- failedTestsOnly: boolean: whether to generate debug traces for failed tests only, default is false

Example:

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

In order to generate traces for failing tests only, set the failedTestsOnly configuration to true

Example:

module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      return debuggerPlugin(on, config, {
        failedTestsOnly: true,
      });
    },
  },
});

Support File: `debuggerSupport`

Attaches required handlers to Cypress events

debuggerSupport(): void

Troubleshooting

Our example setup is working with Chromim-based (Electron and Chrome / Chromium) browsers. We have also created an example CI integration with GitHub. Most chances, your existing configuration is more complex and there are additional plugins that interfere with how this plugins works.

Try to simplify your configuration until you get a working example as appears in the example apps/web
Slowly enable the rest of the plugins, one-by-one until you face the issue
Use the debug mode to identify possible root cause: NODE_DEBUG=cypress-har-generator* DEBUG=cypress:*,cypress-debugger* ELECTRON_EXTRA_LAUNCH_ARGS=--remote-debugging-port=9226 npx cypress run --browser electron
If you found a workaround, submit a contribution with code or documentation improvement
If you found a bug, submit a new issue with all the details and suggestion

Disclaimer

All third party trademarks and references (including logos and icons) referenced herein are the property of their respective owners. Unless specifically designated as Made by Currents, integrations are not supported or maintained by Currents. The third party products or services that this software connects to are subject to their respective owners intellectual property and terms of service agreements.

currents-dev/cypress-debugger