Start with the earliest failed Cypress command, not the last error in the report. Read its message and code frame, inspect the application state at that exact point, then reproduce the smallest failing case and compare one execution condition at a time. This sequence helps distinguish a real application or test defect from timing, browser, and CI differences.
1. Find the first meaningful failure
Open the failed test and locate the earliest command that failed. Later errors may be consequences of that first failure: for example, a missing element can make a later assertion fail too.
- Read the error type and message, highlighted source location, and stack trace. Cypress errors may include a Learn more link with additional context.
- Check whether the failure is a failed assertion, a command timeout, an application exception, or a browser or runner error. Those categories point to different causes.
- In the Cypress Command Log, click the relevant command while browser DevTools is open. Cypress can print the command’s subject and yielded result, which helps establish what the test actually received.
See Cypress’s Debugging in Cypress guide for the documented inspection tools.
2. Inspect the app and test state at the right moment
Cypress commands are queued while the test callback runs and execute afterward. A debugger statement placed after a chain in the test body may pause after queued commands have completed, rather than at the state you intended to inspect.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutePause after a query
Put the breakpoint inside a .then() callback when you need to inspect the result of a preceding query:
cy.get('[data-testid="save-button"]').then(($button) => {
debugger
// Inspect $button and the current page in DevTools.
})Inspect the current subject
Append .debug() to a chain to expose its current subject as subject in DevTools:
cy.get('[data-testid="save-button"]').debug().click()Use cy.pause() when you want to step through subsequent Cypress commands. While paused, inspect the DOM, network activity, and browser storage in DevTools. These tools are most useful when placed immediately before or after the first failing transition, rather than at an arbitrary point in a long test.
3. Use the Command Log to travel back
In Cypress open mode, the Command Log includes commands and hooks, and its snapshots let you inspect earlier application states. Travel back to the command before the failure and check whether the selector matched, a response arrived, or the interface changed as expected. A snapshot can reveal where the observed state first diverged from what the test assumes. Cypress documents this workflow in Open mode in the Cypress app.
4. Decide whether the test needs to wait or is genuinely failing
Cypress retry-ability and test retries address different problems. Queries and assertions retry while the application changes; configured test retries rerun a whole failed test. Do not use whole-test retries as a substitute for understanding a command that is asserting too early or waiting for the wrong condition.
When a query or assertion is racing the UI
Use a query and assertion that describe the state the test needs, so Cypress can retry them while the interface updates. Avoid treating a fixed delay as proof that the application is ready: a delay can make a test slower without addressing a condition that varies.
See Retry-ability for how Cypress retries queries and assertions.
When a configured test retry passes
A retry reruns the failed test, including its beforeEach and afterEach hooks. Failures in before and after hooks do not trigger a retry. A test that passes on a later attempt is still a flake signal: compare the attempts and identify what changed instead of treating the later pass as a durable fix. Cypress explains the behavior in Test retries in Cypress.
Free tools Windows power users keep installed
One-click scans. No signup required.
5. Reduce the failure to a small reproduction
Run the narrowest test that still fails. If the problem appears only in a long test or spec, split the work or remove unrelated steps until the failure remains in a minimal case. This makes it easier to see whether the cause is test setup, application timing, browser behavior, or the environment.
When comparing a failing run with a passing one, change one axis at a time and keep the application build, test data, and relevant configuration fixed where possible:
- local execution versus CI;
- headed versus headless mode;
- browser family or version;
- isolated test versus full spec;
- first attempt versus retry.
Review available screenshots, video, or replay alongside the reduced test. Cypress’s Troubleshooting: Cypress App guide recommends narrowing the reproduction and comparing browsers and environments.
6. Investigate a headless-only or CI-only failure
First try to reproduce a headless-only failure locally with a visible browser. For example:
npx cypress run --headed --no-exit --browser chrome--headed displays the browser, and --no-exit keeps Cypress open after the run so you can inspect the Command Log and final application state. This can expose a different browser-visible state, but it does not by itself prove that the underlying issue is fixed. Cypress documents the options in Launching browsers in Cypress.
For CI, compare the failing run with a local run using the same browser family and version, application build, test data, and relevant configuration where possible. If the original browser session is gone or the conditions are hard to reproduce locally, Cypress Cloud’s documentation describes reviewing the error, retry attempts, artifacts, test history, and Test Replay for a recorded run: Debug failing tests in CI with Cypress Cloud.
7. Collect only the logs and artifacts you need
Turn on Cypress DEBUG output selectively
Set DEBUG=cypress:* before cypress run or cypress open for broad Cypress logs. For a narrower view, use a namespace such as cypress:server:project or cypress:server:browsers*. Broad debug output can be large and may affect performance, so enable it when needed and narrow the namespace if possible.
In browser open mode, Cypress documents another option: set localStorage.debug = 'cypress*' in DevTools, then reload to see browser logs. The options and their trade-offs are covered in Cypress troubleshooting.
Know which screenshots and videos exist
cypress runautomatically captures a screenshot when a test fails.cypress opendoes not automatically capture failure screenshots.- Video is off by default. Set
video: trueto enable it; Cypress records spec videos incypress run, notcypress open. - The default folders are
cypress/screenshotsandcypress/videos. A run clears these folders before execution unless configured otherwise.
Check the artifact from the failing run rather than assuming an old file belongs to it. Configuration and capture behavior are documented in Capture screenshots and videos in Cypress.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.8. Common debugging dead ends
| Symptom | Likely explanation | Next step |
|---|---|---|
| A later command fails after an earlier one timed out | The later error may be a consequence of the earliest failure. | Inspect the earliest failed command and its yielded subject. |
| A debugger pauses after the useful state is gone | The breakpoint may be outside the queued command’s execution point. | Move it into a .then() callback or use .debug() on the chain. |
| A test passes on retry but fails intermittently | Whole-test retries can mask a flaky condition without removing it. | Compare attempts, then investigate the failing query, state transition, or setup. |
| A headless failure does not appear in a normal local run | The execution mode, browser, or environment may differ. | Try the headed command above, then compare one execution axis at a time. |
| No screenshot appears after using open mode | Failure screenshots are automatic in cypress run, not cypress open. |
Use the Command Log and snapshots in open mode, or capture the failure in a run. |
| Debug logs obscure the useful output | The cypress:* namespace is broad and can produce substantial output. |
Choose a narrower namespace and disable debugging after collecting the needed evidence. |
Or skip the browser setup
If you need a screenshot of a page while investigating a visual state, you can capture it with one GET request instead of setting up a separate browser script. ScreenshotNeo is a website screenshot API and MCP server for developers; it is a supporting page-capture option, not a replacement for Cypress’s test runner or its browser debugging tools. See the ScreenshotNeo website and API documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp- Cookie banners, newsletter popups, and chat widgets are removed before the shot; each cleanup step can be turned off.
- Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed; response headers identify the page verdict and billing status.
- An MCP server provides
take_screenshot,get_page_info, andcapture_pdftools for AI agents. - The Free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000.
Sign up for ScreenshotNeo’s free plan to try it without a card.
Frequently Asked Questions
Where does Cypress put screenshots and videos by default?
The default output folders are cypress/screenshots and cypress/videos.
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 →Can I use Cypress’s automatic failure screenshot behavior in open mode?
No. Cypress automatically captures failure screenshots during cypress run; it does not do so automatically in cypress open.
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.
