debug-logs.md

Debug Logs

Many Cypress packages use the debug module to log runtime info to the console.

Choosing a namespace

The naming scheme for debug namespaces should generally follow this pattern:

cypress:{packageName}:{relative path to file from src root, using : to separate directories, minus index if applicable}

# examples:
# packages/server/lib/util/file.js -> cypress:server:util:file
# packages/launcher/windows/index.ts -> cypress:launcher:windows

cypress-verbose can be used instead of cypress if the logs are overly verbose and would make the output of DEBUG=cypress:* unreadable.

Exceptions to these rules:

• The cli uses cypress:cli:*.
• NPM packages should use {moduleName} as a prefix instead of cypress, like cypress-webpack-preprocessor for npm/webpack-preprocessor.
• In some places, like per-request in the proxy package, it's more useful to attach debug messages to something besides the module (like individual HTTP requests). In that case, it's okay to create namespaces as you see fit. But at least begin with cypress:{packageName} or cypress-verbose:{packageName}

Using debug logs

Pass the DEBUG environment variable to select a set of logs to print to stderr. Example selectors:

# frequently useful to get a sense of what is happening in the app at a high level
DEBUG=cypress:*
# print all info and verbose logs, but don't print verbose logs from `some-noisy-package`
DEBUG=cypress:*,cypress-verbose:*,-cypress-verbose:some-noisy-package:*
# print out verbose per-request data for proxied HTTP requests
DEBUG=cypress-verbose:proxy:http

# in the browser, set `localStorage.DEBUG`:
localStorage.DEBUG = 'cypress:driver,cypress:driver:*'

For more info, see the public documentation for printing debug logs and the debug module docs