To debug a failed Cypress test in CI, record the run to Cypress Cloud, open the failing test, and inspect its Test Replay around the failure. The replay lets you step through the recorded commands and compare captured DOM, network, console, and JavaScript error evidence; it is not a fresh reproduction on your local machine. Start by confirming the run was recorded with Cypress 13 or later, used a supported Chromium-based test browser, and successfully uploaded its artifacts.
What Cypress Test Replay shows
Test Replay is an inspection view for eligible runs captured and uploaded to Cypress Cloud. It can show the command sequence, DOM and element rendering, network requests, console logs, JavaScript errors, styles, SVG, iframes, shadow DOM, and canvas. Step through the command log to align the point of failure with the state Cypress captured at that moment. See Cypress Test Replay documentation.
As an Amazon Associate I earn from qualifying purchases.
It does not capture every browser or application state. Cypress lists cookies, local and session storage, WebSockets, server-sent events, and traffic from cy.request() among exclusions, as well as certain video/audio and shadow DOM cases. If an event is in an unsupported category, its absence from the replay does not prove it never happened.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Prerequisites for a replay
- Cypress version: Cypress documents Test Replay for tests recorded with v13 or later. The migration guide says the feature is enabled by default in v13; verify the project setting rather than assuming it remains enabled. Cypress migration guide.
- Recorded CI run: Connect the project to Cypress Cloud and record the CI run. Cloud can inspect only data captured and uploaded from the run; Test Replay does not require edits to test code. See Cypress’s CI debugging guide.
- Test browser: Use a Chromium-based test browser. Cypress names Chrome and Edge, and its troubleshooting guidance also mentions deprecated Electron. Firefox and WebKit test replays are not supported in the feature documentation.
- Cloud setting and upload: Test Replay must be enabled in project settings and its artifact upload must complete. A run that timed out or encountered network, firewall, proxy, or upload problems may have no usable replay.
Do not confuse the browser used to run the test with the browser used to view Cloud: Cypress says Safari 16.4 and later can render Test Replay, while Safari/WebKit test runs are not supported for replay. Current availability is subject to Cypress Cloud usage limits and plan terms.
Debug a failed CI test step by step
- Open the recorded run. In Cypress Cloud, locate the CI run and select the failing test. If the run is not present, first verify the project is connected to Cloud and that CI invokes a recorded run as described in the CI debugging guide.
- Read the test history before replaying. Review the error, retries, artifacts, and earlier runs. Establish whether this is a new failure or a recurring one. To use Branch Review to assess a change, recorded runs must exist for both the current and base branches.
- Open Test Replay. Use the replay from the run overview or test detail. Step through the command log, focusing on the commands immediately before and at the failing assertion. Check the DOM and element rendering, network timeline, console messages, and JavaScript errors together rather than treating one signal as the whole explanation.
- Compare attempts when available. If the test retried, compare the failed attempt with a passing one on the same code. A retry passing is evidence of inconsistent behavior, not proof the initial failure was harmless.
- Test a specific explanation. For a missing or late element, inspect DOM state and command order for timing or race conditions. For unexpected application state after a request, inspect the request, response, console, and subsequent commands; remember that
cy.request()traffic is not listed as replayable. For a likely regression, compare commit and branch history and use Branch Review where both branch runs are recorded.
How to distinguish common CI failure causes
| Evidence in the run | Likely avenue to investigate | Next check |
|---|---|---|
| Element is absent or appears after the assertion | Render timing, a race, or an assertion that does not wait for the required state | Align the DOM and command sequence; confirm the test waits for the application condition it needs. |
| State diverges after a visible request | Unexpected response, network timing, or application handling | Inspect request/response and console evidence around the divergence. |
| Failure occurs on one attempt but a retry passes | Flakiness, ordering/shared state, timing, network, or environment difference | Compare attempts and prior run history; identify what changed instead of dismissing the first failure. |
| Replay appears to omit a storage or network event | The event may be outside Test Replay’s supported capture | Check the documented exclusions before concluding it did not occur. |
| Failure begins after a code change | Possible application regression | Compare the failing commit and branch history; use Branch Review only when both branches have recorded runs. |
Use the Cloud CLI for terminal triage
The Cypress Cloud CLI can return replay metadata and a structured timeline when replay data was captured and remains within its retention window. Install and authenticate the CLI according to the Cloud CLI reference, then run:
cy-cloud replay info --testId <testId>
cy-cloud replay timeline --testId <testId> --commands --aroundFailure 5 --network --logsReplace <testId> with the test identifier from Cloud. The timeline supports selecting attempts, command events, network types, logs, failed commands, and a window around the failure. If data is still processing, was never captured, or has passed its retention window, the commands cannot provide a replay.
Why Test Replay may be missing or disabled
- Unsupported version: Check that the recorded test used Cypress v13 or later; update Cypress before deeper investigation, since Cypress recommends using the latest version as replay issues are fixed over time.
- Unsupported test browser: Confirm the run used a supported Chromium-based browser, such as Chrome or Edge.
- Project setting is off: Verify Test Replay is enabled in the Cypress Cloud project settings.
- Artifact upload failed: Read the CI standard output for upload errors. Check connectivity and whether firewall or proxy rules block access to Cypress endpoints.
- Run or spec timed out: Cypress troubleshooting identifies invalid or missing upload URL errors that can occur when a spec exceeds the run timeout. Reduce spec runtime or increase the configured timeout, then record another run.
- Replay is still processing or expired: The CLI cannot inspect data that is not ready or has passed the retention window.
For feature-specific failure messages and current troubleshooting details, consult Cypress’s Test Replay page and its Cloud FAQ.
Performance, runner behavior, and data handling
Cypress warns that capture can use additional resources and recommends disabling video recording when Test Replay is enabled. Capturing many or large canvas elements can also affect performance; the canvas capture toggle is in project settings. Cypress does not establish a universal performance overhead or typical upload size, so treat these as workload-dependent considerations rather than fixed costs.
With Test Replay enabled, the Runner UI does not render during cypress run by default. Cypress documents --runner-ui as the option to enable it, with a possible runtime cost.
Cypress documents default redaction of sensitive values in captured network requests and responses before upload, and masking of password and payment field values before artifact creation. Replays and test data are visible to people with access to the Cloud project. Review Cypress Cloud’s security documentation, terms, and project access controls against your team’s data requirements; do not assume replay artifacts contain no sensitive information.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
For a screenshot of a page while investigating a visual issue, ScreenshotNeo is a separate website screenshot API and MCP server; it does not replace Cypress Test Replay or expose a recorded test’s command and network timeline. One GET request returns an image or PDF. Example using cURL:
Free tools Windows power users keep installed
One-click scans. No signup required.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for parameters. Cookie banners, newsletter popups, and chat widgets are removed before the shot; bot checks, blank pages, failed loads, timeouts, and cache hits are not billed. Its MCP server lets AI agents use screenshot tools. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up for 1,000 free screenshots a month, with no card required.
Frequently Asked Questions
Can I replay a Cypress failure locally after the CI run?
Test Replay is an inspection of captured and uploaded Cloud run data, not a new local reproduction. Use the replay for the recorded state, then reproduce locally if you need to experiment with a fix.
Does the absence of a request in Test Replay prove it was never sent?
No. Cypress lists some traffic, including `cy.request()` and WebSockets, as unsupported replay data, so absence may reflect a capture limitation.
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.
