How to View and Use Cypress Logs
Learn where Cypress logs appear, how to inspect commands in the Test Runner, enable targeted debug output, and save evidence from failing runs.
Cypress logs appear in several places, depending on what you need to diagnose. Use the Command Log in cypress open to inspect test commands, hooks, and snapshots; click a command with browser DevTools open to see structured details. Use targeted DEBUG namespaces for Cypress process and startup problems, browser-side driver logs for issues inside the runner, and screenshots, videos, or Cypress Cloud Test Replay for recorded-run evidence.
This guide covers Cypress’s own logs and test-run evidence. It does not treat application logs from your server as Cypress logs; inspect those in the server or CI environment where the application runs.
1. Inspect commands in the Cypress Test Runner
Start in open mode when you can reproduce the problem locally:
npx cypress openOpen the spec and run the test. The Command Log lists commands and hooks in order. Click a test to expand its entries, including setup and teardown hooks. Hover over a command to return the application preview to the state captured for that command. Cypress documents a default buffer of 50 tests’ worth of snapshots and command data.
Cypress also logs browser events such as XHR and fetch requests, page loads, URL hash changes, and form submissions. If request entries make the list hard to scan, use the Command Log’s Show HTTP Requests toggle to hide them from the display. This changes what you see in the log; the requests still execute and remain available to assertions and tools such as cy.intercept(). See the Cypress open mode documentation.
2. Read a command’s details in browser DevTools
Keep the browser’s Developer Tools open, then click an entry in the Command Log. Cypress writes structured information for that command to the browser console. Depending on the command, this can include the command issued, yielded value, elements found, and selector used. This is useful when a query matched an unexpected element or an action received an unexpected subject.
For your own custom commands, Cypress.log() controls the Command Log entry. Its consoleProps option supplies structured details shown in DevTools when the entry is clicked. For asynchronous commands, autoEnd: false lets you end the log entry when the work finishes.
Cypress.Commands.add('findByLabelAndLog', (label) => {
const entry = Cypress.log({
name: 'findByLabelAndLog',
message: label,
consoleProps: () => ({ label }),
})
return cy.contains('label', label)
.find('input')
.then(($input) => {
entry.set({ $el: $input })
return $input
})
})Use care with log properties. Do not include passwords, session tokens, personal data, or sensitive response bodies in command details. See the Cypress.log() API documentation.
3. Debug a failing command and its timing
Read the error message, code frame, and stack trace in the Runner first. Then inspect the failing command and the commands immediately before it. With DevTools open, clicking the command can reveal the subject and yielded result. Cypress source maps help connect stack traces to your project files. The Cypress debugging guide recommends using browser developer tools alongside the Cypress interface.
If the failure looks timing-related, check whether the test is waiting for the event that actually makes the page ready. For example, wait for a relevant network response before asserting on content populated by that response. Prefer a request alias and an assertion on the resulting state over a fixed delay that only happens to be long enough on one machine.
cy.intercept('GET', '/api/profile').as('profile')
cy.visit('/account')
cy.wait('@profile')
cy.get('[data-cy=profile-name]').should('be.visible')A command’s position in the log is evidence about order, but a passing command does not guarantee that an asynchronous application update has completed. Make the test wait for the application condition it needs.
4. Enable Cypress process debug output
For Cypress startup, project-opening, browser-detection, reporter, or video problems, set DEBUG before launching Cypress. On macOS, Linux, and Windows Git Bash, for example:
DEBUG=cypress:* npx cypress runUse npx cypress open instead of run to capture startup diagnostics while opening the Specs UI. The wildcard enables broad output; it can produce a lot of data and affect performance. Turn it on only while diagnosing, then narrow the namespace.
| Problem area | Example namespace |
|---|---|
| Project opening | cypress:server:project |
| Browser detection | cypress:server:browsers* |
| Reporter | cypress:server:reporter |
| Video recording | cypress:server:video |
You can combine namespaces with commas and exclude a noisy source with a leading hyphen. For example:
DEBUG=cypress:server:project,cypress:server:browsers*,-cypress:server:browsers:protocol npx cypress openShell syntax differs by platform. In Windows Command Prompt, set the variable in the same session before running Cypress:
set DEBUG=cypress:server:project
npx cypress openIn PowerShell:
$env:DEBUG='cypress:server:project'
npx cypress openFor Yarn, pnpm, or Bun, use the equivalent environment-variable syntax supported by your shell and package manager. If no logs appear, check that the variable was set in the shell that launched Cypress. Cypress’s Troubleshooting: Cypress App reference describes the available debugging approach and namespace examples.
5. Enable browser-side Cypress driver logs
Node-side DEBUG output and browser-side driver logs are separate. To diagnose Cypress driver behavior inside cypress open, open the runner’s browser DevTools console and set:
localStorage.debug = 'cypress*'Reload the page, then enable Verbose console messages in DevTools. The browser console will show driver debug messages such as cypress:driver. This setting applies in that browser’s local storage; remove it when you no longer need the extra output.
6. Save screenshots, videos, and recorded-run evidence
Call cy.screenshot() to capture a screenshot at a useful point in a test. Cypress also captures screenshots automatically when tests fail in cypress run by default. It does not automatically capture failure screenshots in cypress open. The default screenshot directory is cypress/screenshots; configuration can change the directory or disable failure screenshots.
it('shows the account page', () => {
cy.visit('/account')
cy.get('[data-cy=account-heading]').should('be.visible')
cy.screenshot('account-page')
})Cypress can record a video for each spec during cypress run when video recording is enabled. For recorded Cypress Cloud runs, Test Replay provides a way to replay execution with debugging capability. Replay depends on having a recorded run and applicable Cloud access. Treat screenshots and videos as supporting evidence; the command sequence, assertions, and relevant network state still matter. See Capture screenshots and videos and open mode.
7. Isolate slowdowns caused by logging
The Command Log is useful, but Cypress documents that it can contribute to slower tests or browser crashes in some cases. As a diagnostic experiment, disable it for a run:
CYPRESS_NO_COMMAND_LOG=1 npx cypress runThe CLI also supports --no-runner-ui to hide the full Runner UI during a run:
npx cypress run --no-runner-uiCompare the same workload with and without the logging surface to see whether it contributes to the issue. When the Command Log is disabled, screenshots and videos will not include it. Re-enable logging when you need the visual command history.
8. Choose the log surface that matches the failure
| What you need to understand | Where to look |
|---|---|
| Command order, hooks, snapshots, and DOM state | Command Log in cypress open |
| What a command received or yielded | Browser DevTools after clicking its Command Log entry |
| Cypress startup or Node-side process behavior | Terminal output with a targeted DEBUG namespace |
| Cypress driver behavior in the browser | DevTools console with localStorage.debug |
| Evidence from a CI or recorded execution | Failure screenshots, enabled video recording, or Cypress Cloud Test Replay |
9. Troubleshooting common logging problems
| Symptom | Likely cause | What to do |
|---|---|---|
| No failure screenshot appears | The test ran in cypress open, where failure screenshots are not automatic, or the run configuration disabled them. |
Use cy.screenshot() for a manual capture, or check screenshot settings for cypress run. |
DEBUG prints nothing |
The variable was not set in the launching shell, the syntax was wrong for that shell, or the selected namespace does not match the issue. | Set it in the same shell session, try a relevant namespace, and confirm the command is running there. |
| The terminal is overwhelmed with logs | DEBUG=cypress:* enables broad diagnostics. |
Replace the wildcard with a targeted namespace; disable debug output after the investigation. |
| Browser driver messages are missing | Node-side DEBUG was enabled, but browser-side driver logging was not; or the page was not reloaded after setting local storage. |
Set localStorage.debug = 'cypress*' in runner DevTools, reload, and show Verbose console messages. |
| Clicking a command shows no useful details | DevTools may be closed, or a custom command may not expose structured properties. | Keep DevTools open and add safe, relevant consoleProps through Cypress.log(). |
| The Command Log hides a request you need to inspect | The HTTP request display toggle is off. | Turn on Show HTTP Requests; hiding entries does not stop the requests. |
| Tests slow down or the browser crashes | The Command Log or broad debug output may contribute to resource use. | Try CYPRESS_NO_COMMAND_LOG=1 as an isolation step and narrow or remove debug output. Remember that captured media will omit the Command Log when it is disabled. |
| A test passes locally but fails intermittently in CI | The test may depend on variable timing or an unobserved request or UI state. | Inspect the recorded failure evidence, wait on the relevant request or DOM condition, and remove unnecessary fixed delays. |
10. Or skip the browser setup
If your debugging workflow needs a screenshot of the page under test, [ScreenshotNeo](https://screenshotneo.com) can capture it with one GET request. See the ScreenshotNeo API documentation for request options.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);ScreenshotNeo accepts cookie and consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks, blank pages, and failed loads are never billed, and response headers identify the page verdict and billing status. Its MCP server gives AI agents tools for screenshots, page information, and PDF capture. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 shots. For this Cypress guide, it is an optional way to capture a URL; it does not replace Cypress command logs or test-run evidence.
Create a free ScreenshotNeo account for 1,000 screenshots a month with no card.
Frequently asked questions
Where does Cypress save screenshots?
By default, screenshots are saved in cypress/screenshots. Project configuration can change that location.
Does Cypress automatically save a screenshot in open mode?
No. Failure screenshots are automatic by default in cypress run, not in cypress open. Use cy.screenshot() for a manual capture.
Can I use Cypress logs to inspect my application’s server output?
Cypress’s Command Log and debug namespaces describe test-runner activity. Check the application server’s own terminal or hosting logs for server-side output.
Where can I find the available Cypress CLI options?
See the official Cypress command-line reference.
