Repository files navigation

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

• Cypress version 10+
• NodeJS^14.17.0
• Chromium family browsers only
• Requiresalternative cypress binaries due toCypress.io blocking

Install the package:

npm install cypress-debugger

Addcypress-debugger tocypress.config.{js|ts|mjs}

// cypress.config.jsconst{ 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 datacallback:(path,data)=>{console.log({            path,            data,});},});returnconfig;},},});

Addcypress-debugger tocypress/support/e2e.{js|ts}

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

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

Analyze the information using the debugger web app.

npx cypress run --browser chrome

Set theremote-debugging-port viaELECTRON_EXTRA_LAUNCH_ARGS environment variable:

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

• See an example inapps/web directory
• Example of integrating with Currents:https://github.com/currents-dev/gh-actions-example/tree/debugger-example

Installs cypress-debugger.

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

• on -Cypress.PluginEventssetupNodeEvents method first argument
• config -Cypress.PluginConfigsetupNodeEvents method second argument
• options -PluginOptions:
  • meta: Record<string, unknown>: an optional field that is added to theTestExecutionResult aspluginMeta
  • callback: (path: string, data: TestExecutionResult: a callback function that will be called after each test
  • targetDirectory: string: the path to the reports directory. Default isdump
  • failedTestsOnly: boolean: whether to generate debug traces for failed tests only, default isfalse

Example:

// cypress.config.jsconst{ defineConfig}=require('cypress');const{ debuggerPlugin}=require('cypress-debugger');module.exports=defineConfig({e2e:{setupNodeEvents(on,config){returndebuggerPlugin(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 thefailedTestsOnly configuration totrue

Example:

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

Attaches required handlers toCypress events

debuggerSupport():void

Our example setup is working with Chromim-based (Electron and Chrome / Chromium) browsers. We have also created anexample 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 exampleapps/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 anew issue with all the details and suggestion

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.