Enables viewing/debugging Cypress runs from remote environments (ex. CI) with debug information you're used to having locally.
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._
Install the Cypress plugin into your Cypress project.
``sh`
npm install -D @deploysentinel/cypress-debugger
In your Cypress project's support file (ex. cypress/support/index.js) add:
`js
// ❗ Must be declared at the top of the file ❗
import "@deploysentinel/cypress-debugger/support";
...
import "./commands";
`
In your Cypress project's plugin file (ex. cypress/plugins/index.js) add:
`js
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._
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:
`json`
{
...
"env": {
...
"deploysentinel_key": "YOUR_API_KEY"
}
}
#### Option 2. OS Environment Variable
In your environment export an OS environment variable
`sh`
CYPRESS_DEPLOYSENTINEL_KEY=YOUR_API_KEY
#### Option 3. Cypress CLI Flag
`sh`
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:
`js
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;
};
`
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.
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:
`sh`
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).
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._
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.
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.
By default, the debugger captures all network requests. You can specify a
beforeNetworkSend in the plugin file to filter out sensitive network requestsnull
by returning or undefined.
`js`
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:
`js`
{
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 beevent.headers["x-my-header"]
accessible via .
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:
`sh`
CYPRESS_DEPLOYSENTINEL_SPEC="cypress/tests/ui/, cypress/integration/"
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:
`sh`
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
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.
`js`
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:
`json`
{
"compilerOptions": {
"types": ["cypress", "@deploysentinel/cypress-debugger"]
}
}
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.
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
`sh`
CYPRESS_DEPLOYSENTINEL_NETWORK_MOCK_MODE=record
(Optional) You can specify networkMock in the plugin file to filter out unused
network artifacts
`js`
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 []
},
});
When intercept mode is enabled, the debugger will read fixtures previously
generated from record mode (in /cypress/fixtures) and intercept network on thecy.intercept
fly using
To enable intercept mode, set CYPRESS_DEPLOYSENTINEL_NETWORK_MOCK_MODE
environment variable to
`sh`
CYPRESS_DEPLOYSENTINEL_NETWORK_MOCK_MODE=intercept
_Note: Intercept mode will create a fixtures/.ds-network-cache folder whichfixtures/ds-network-mock-*`_
temporarily stores network mocks. This folder should be gitignored as the source
of truth is derived from
View our
changelog directly on our website.