DeploySentinel Cypress Debugger

Enables viewing/debugging Cypress runs from remote environments (ex. CI) with debug information you're used to having locally.

Browser Compatibility Note: Console log and network capturing are not yet compatible with Microsoft Edge or Firefox.

Installation

Install the Cypress plugin into your Cypress project.

npm install -D @deploysentinel/cypress-debugger

Usage

Add Support File

In your Cypress project's support file (ex. cypress/support/index.js) add:

// ❗ Must be declared at the top of the file ❗
import "@deploysentinel/cypress-debugger/support";

...
import "./commands";

Add Plugin

In your Cypress project's plugin file (ex. cypress/plugins/index.js) add:

module.exports = (on, config) => {
  // ❗ Must be declared at the top of the function ❗
  [on, config] = require('@deploysentinel/cypress-debugger/plugin')(on, config);

  // Use 'on' and 'config' returned from the plugin
  // ...
};

Note: The plugin returns patched versions of on and config to deconflict with other plugins and configuration.

Add API Key

Lastly, add your API key to a deploysentinel_key Cypress environment variable. You can grab your API key by logging into/signing up for DeploySentinel and visiting your profile page: https://deploysentinel.com/profile.

Afterwards you can specify the key in a few different ways:

Option 1. Cypress Config File

In your cypress.json file add:

{
  ...
  "env": {
    ...
    "deploysentinel_key": "YOUR_API_KEY"
  }
}

Option 2. OS Environment Variable

In your environment export an OS environment variable

CYPRESS_DEPLOYSENTINEL_KEY=YOUR_API_KEY

Option 3. Cypress CLI Flag

cypress run --env deploysentinel_key=YOUR_API_KEY

Option 4. Programmatically via Plugin File

Recommended only if you need to programmatically control or customize where the API key is pulled from.

In your Cypress project's plugin file (ex. cypress/plugins/index.js) add:

module.exports = (on, config) => {
  // Add this to specify the key programmatically, before calling the plugin
  config.env.DEPLOYSENTINEL_KEY =
    process.env.YOUR_CUSTOM_ENV_FOR_API_KEY || 'YOUR_API_KEY';

  // Import plugin as usual, after the key in the env is set above
  require('@deploysentinel/cypress-debugger/plugin')(on, config);

  // ❗ Important: The config needs to be returned in the end
  return config;
};

Electron Configuration

If your test suite is running in Electron, you'll need to pass an additional flag to Cypress to open a remote debugging port for the plugin to listen to network and console logs.

Specify the remote debugging port with the ELECTRON_EXTRA_LAUNCH_ARGS environment variable. The port number can be any valid port number available on the machine.

ELECTRON_EXTRA_LAUNCH_ARGS="--remote-debugging-port=40500" cypress run ...

If your test suite is only running in Chrome/Chromium ex. cypress run --browser chrome, then this step is not necessary. Networking and console log capturing for Microsoft Edge and Firefox is currently not supported.

Verifying Everything Works Locally

By default, the plugin is only enabled in non-interactive mode (ex. cypress run) and will only upload captures on failure. To verify if the plugin is working locally, you can force it to always be enabled and always upload captures by enabling the following environment variables:

CYPRESS_DEPLOYSENTINEL_UPLOAD_ON_PASSES=true cypress run # or open

If OS environment variables are not available to be set, they can also be set via CLI flag or config file similar to how the API key can be configured (see "Add API Key" section above).

Viewing Test Results

By default, failed tests will have the run URL available in the console log next to the run failure logs. This can be accessed in your CI logs.

Example Logs:

  Running:  pages.js                                            (3 of 3)


  Pages
    ✓ generates complex slug with md extension (647ms)
    1) generates a slug with an index file
	 DeploySentinel Debug URL: https://deploysentinel.com/ci/runs/712345677654321abcd00000
    ✓ generates a slug with a slash (672ms)

Otherwise, runs can be viewed from the DeploySentinel Dashboard at https://deploysentinel.com/ci/dashboard.

Note: By default, the plugin will not upload any data when tests are passing or if the test is run in interactive mode. See "Verifying Everything Works Locally" above for more information.

JUnit Report Integration

If Cypress is run with the JUnit reporter, the plugin will automatically append a DeploySentinel URL to the end of the error details for failed tests after the entire test suite has run, so you can easily access test captures from your JUnit report output.

Captured Data

DeploySentinel Cypress Debugger, when enabled, will automatically capture the actions Cypress took during the test, as well as DOM captures, console logs and network requests.

Advanced Configuration

Network Request Filtering

By default, the debugger captures all network requests. You can specify a beforeNetworkSend in the plugin file to filter out sensitive network requests by returning null or undefined.

require('@deploysentinel/cypress-debugger/plugin')(on, config, {
  beforeNetworkSend: event => {
    if (event.request.url.includes('wikipedia.org')) {
      return null;
    } else if ('ds-key' in event.request.headers) {
      return null;
    } else if (event.response?.statusCode === 400) {
      return null;
    }
    return event; // Don't filter out event
  },
});

Note: Updating/mutating the network event object within the function will not modify the actual recorded network event content, we may allow for mutations in the future via this API.

Event Object Type:

{
  request: {
    url: string;
    method: string;
    headers: { [key: string]: string };
  };
  // optional
  response?: {
    statusCode: number;
    statusMessage: string;
    headers: { [key: string]: string };
    bodySize: number;
    body: string;
  };
}

Headers will be lower-cased. Ex: A header such as X-My-Header will be accessible via event.headers["x-my-header"].

Enabling Captures For Specific Files

To capture only specific tests, you can specify a glob pattern in the CYPRESS_DEPLOYSENTINEL_SPEC environment variable, similar to the --spec Cypress CLI flag.

Example:

CYPRESS_DEPLOYSENTINEL_SPEC="cypress/tests/ui/**, cypress/integration/**"

Git Commit Metadata

By default, the debugger will collect commit metadata automatically to show within the dashboard UI. If we're unable to pull the information automatically, you can set the following environment variables to manually specify commit information:

branch: COMMIT_INFO_BRANCH
message: COMMIT_INFO_MESSAGE
email: COMMIT_INFO_EMAIL
author: COMMIT_INFO_AUTHOR
sha: COMMIT_INFO_SHA
timestamp: COMMIT_INFO_TIMESTAMP
remote: COMMIT_INFO_REMOTE

Send Custom Event to DeploySentinel [BETA]

Users can send custom events to DeploySentinel to attach additional debug information during a test run. (ex. debugging errors and flakes with DB or app state dumps) To use it, simply pass the custom data to command cy.dsAddEvent.

Cypress.on('fail', e => {
  // As an example, fetch data from Firebase
  cy.callFirestore('get', 'myData').then(r => {
    cy.dsAddEvent(r);
  });
  throw e;
});

Note: For each payload, it should be able to be stringified with JSON.stringify (no circular dependencies) and the size has to be smaller than 4 MB.

Typescript Configuration

If you're using Typescript with Cypress, you'll need to add @deploysentinel/cypress-debugger to the cypress/tsconfig.json file:

{
  "compilerOptions": {
    "types": ["cypress", "@deploysentinel/cypress-debugger"]
  }
}

Network Fixtures Generator / Interceptor [BETA]

DeploySentinel Cypress Fixtures Generator, when enabled, will automatically dump network requests data to local disk once tests are finished.

On the other hand, DeploySentinel Cypress Network Interceptor, when enabled, will automatically intercept network requests during test runs with fixtures generated by Fixtures Generator.

Record Mode

Once record mode is enabled, the debugger will dump network artifacts to /cypress/fixtures with filename prefix ds-network-mock in JSON format

To enable record mode, set CYPRESS_DEPLOYSENTINEL_NETWORK_MOCK_MODE environment variable to record

CYPRESS_DEPLOYSENTINEL_NETWORK_MOCK_MODE=record

(Optional) You can specify networkMock in the plugin file to filter out unused network artifacts

require('@deploysentinel/cypress-debugger/plugin')(on, config, {
  networkMock: {
    mode: 'record', // optional
    methods: ['GET', 'POST'], // default to ["GET", "PATCH", "POST", "PUT", "HEAD", "DELETE"]
    includeUrls: ['https://example.com/**', 'https://api.example.com/users/**'], // default to ['**']
    excludeUrls: ['https://example.com/**'], // inverse of 'includeUrls', default to []
  },
});

Intercept Mode

When intercept mode is enabled, the debugger will read fixtures previously generated from record mode (in /cypress/fixtures) and intercept network on the fly using cy.intercept

To enable intercept mode, set CYPRESS_DEPLOYSENTINEL_NETWORK_MOCK_MODE environment variable to intercept

CYPRESS_DEPLOYSENTINEL_NETWORK_MOCK_MODE=intercept

Note: Intercept mode will create a fixtures/.ds-network-cache folder which temporarily stores network mocks. This folder should be gitignored as the source of truth is derived from fixtures/ds-network-mock-*

Changelog

View our changelog directly on our website.