For a failing Cypress test, start with the error and the matching Command Log entry, then pause at the command that failed and inspect the page in browser Developer Tools. Use .debug() to inspect a chain’s current subject, cy.pause() to step through commands, or put debugger in a .then() callback to stop after queued commands run. For failures limited to CI or appearing intermittently, examine available screenshots, video, or Test Replay and reduce the problem to a small reproducible test. Retries may reveal flakiness, but they do not fix its cause.
Start with the failure message and Command Log
Before changing the test, note the error name and message, the first useful code-frame location, and the Cypress command that failed. Cypress errors can include a code frame and stack trace; source maps can help trace the stack toward the original source. If Cypress provides a “Learn more” link, follow it for context on that specific error. See the Cypress debugging guide.
Open browser Developer Tools, then click the relevant command in the Cypress Command Log. Cypress prints details about the command, its subject, and the value it yielded to the browser console. That evidence can help distinguish a selector or unexpected subject from a problem in the application’s behavior.
Pause where the state matters
Cypress commands are queued for later execution, so a debugger statement placed immediately after a command chain may run before those Cypress commands. Put the statement inside a .then() callback to pause after the preceding queued work, or attach .debug() to the chain whose yielded value you want to inspect. With Developer Tools open, .debug() pauses and exposes the current subject as subject in the console.
#1 Best Overall
Use cy.pause() when you want to step through the test commands one at a time and inspect the DOM, network activity, or storage as the test proceeds. Choose the pause point just before the command whose behavior is unclear.
For an “element is not actionable” error, inspect the rendered DOM immediately before the action. The element may be covered, hidden, moving, or in another state the test did not account for; these are possibilities to check, not universal explanations. A breakpoint or .debug() before the click lets you examine the relevant state.
Match the investigation to the failure type
Assertion or selector failure
Inspect the subject and yielded element in the Command Log and console, then compare them with the state the assertion is intended to verify. Check that the selector targets the intended element and that the assertion describes the state the test actually needs.
Actionability failure
Pause before the action and inspect the element in the DOM. Determine whether it is visible and available for interaction at that moment, or whether the page is still changing.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Request or data timing
If later commands depend on a request, wait for the relevant request or assert on the DOM state that depends on its response before continuing. Timing differences can make a test behave differently locally and in CI; Cypress’s debugging guidance recommends accounting for network-dependent state rather than assuming it is ready.
Intermittent failure
Investigate whether animations, API timing, test-server or database availability, resource dependencies, network issues, missing assertions, or environment variation could explain the inconsistent result. Cypress discusses these sources of unreliability in its flaky-test guidance. Use the failure artifacts and retries as clues, then identify the condition that changes between attempts.
Startup or infrastructure issue
If the browser or Cypress itself fails to start or connect, use the official Cypress troubleshooting guide. It covers debug logs, browser connection problems, cache and dependency issues, and performance effects associated with the Command Log.
Use screenshots, video, and logs selectively
In cypress run, Cypress automatically captures a screenshot on failure by default. In cypress open, it does not automatically take failure screenshots. Use cy.screenshot() when you need a manual capture. For a recorded Cypress Cloud run, Test Replay can show execution details and evidence from the run; availability depends on having a supported recorded run. See Cypress Test Replay.
When ordinary diagnostics are not enough, set DEBUG=cypress:* before running cypress run or opening cypress open. Narrow the namespace if possible: verbose output can be large and affect performance. For browser-console logging in the open app, Cypress documents using localStorage.debug in its troubleshooting guide.
If Command Log rendering itself appears to slow or crash the browser, the same guide documents CYPRESS_NO_COMMAND_LOG=1 and --no-runner-ui for cypress run. These are targeted isolation options, not default debugging settings: disabling the Command Log means screenshots and videos will not show it.
Find why a test passes locally but fails in CI
Compare the test environment and browser, and check whether the CI build process changes the application. Remove assumptions tied to elapsed time, and wait for network-dependent content before querying it. If the failure comes from a recorded Cypress Cloud run, use Test Replay to inspect the execution as it happened in CI.
Reduce the failure to the smallest spec and test that still reproduces it. Then change one comparison axis at a time:
Recommended Free Tools
- Local environment versus CI.
- One browser versus another.
- Headed/open mode versus run mode.
- First attempt versus a retry.
- The original test versus the reduced reproduction.
Changing one factor at a time makes it easier to tell whether the failure follows the test, browser, or environment.
Interpret retries as evidence, not a repair
Cypress test retries are disabled by default. Once configured, Cypress can make the configured number of additional attempts: for example, two retries allow up to three total attempts. You can inspect retry attempts in the Command Log, and screenshots are associated with attempts. See Cypress test retries.
If a test fails once and passes on a later attempt, treat that as evidence of instability to investigate. A retry can expose flakiness; it does not explain or resolve the underlying race, timing, or environment condition.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →
