Cypress 13 Test Replay: How to Debug Failed Tests
Use Cypress Cloud Test Replay to inspect a failed CI run, compare retries, find missing evidence, and choose the next debugging step.
To debug a failed Cypress test with Test Replay, record the CI run to Cypress Cloud, open the failing test, and inspect its captured command history and browser state around the failure. Compare retries and review the DOM, network requests, console events, and JavaScript errors for evidence of an application regression, a timing or network issue, or an environment difference.
Test Replay is an inspection view of an eligible recorded run; it does not rerun the test later on your computer. You need Cypress 13 or later, a recorded run, Test Replay enabled for the project, a supported Chromium-based test browser, and a successfully uploaded replay artifact. Cypress Test Replay documentation
What Test Replay captures—and what it cannot show
Replay lets you move through the recorded test and inspect captured state at commands and around the failure. Depending on the event, the view can include the command log, DOM and element rendering, network requests, console logs, JavaScript errors, styles, SVG, iframes, shadow DOM, and canvas.
There are capture exclusions. Cypress lists cookies, local and session storage, WebSockets, server-sent events, and traffic from cy.request() among data that replay does not show. Some media, shadow DOM cases, and Cypress command console properties are also excluded. An event missing from replay is therefore not proof it never occurred if it falls into an unsupported category. Check the current feature documentation for the complete and current list.
Prerequisites and browser support
- Cypress version: Use Cypress 13 or later for recorded tests. The Cypress 13 migration guide says Test Replay is enabled by default in v13, but verify the project setting if the replay is missing. Cypress migration guide
- Recorded CI run: The run must be recorded to Cypress Cloud, and its replay data must upload successfully. A local run that was never recorded cannot be inspected later in Cloud.
- Test browser: Use a supported Chromium-based browser, such as Chrome or Edge. Replay is not supported for Firefox or WebKit test runs in the feature documentation. Troubleshooting also mentions deprecated Electron.
- Viewing browser: This is separate from the browser used to run the test. Cypress says Safari 16.4 and later can display Test Replay; older Safari versions may lack required web APIs.
- Project setting: Test Replay must be enabled in Cypress Cloud project settings.
Debug a failed CI run step by step
- Confirm the run was recorded. Connect the project to Cypress Cloud and record the CI run using your existing
cypress runworkflow. Test Replay does not require changes to test code. See the Cypress CI debugging guide. - Open the failing test in the recorded run. Note the error, commit, branch, retries, artifacts, and previous-run history. Check whether this is a new failure or a recurring one.
- Open Test Replay. From the run overview or test detail view, step through the command log and align the failed command with the captured DOM, network, console, and error evidence.
- Compare attempts. If Cypress retried the test, compare the failed attempt with a passing attempt on the same code. Identify the earliest point where their commands or visible state diverge.
- Form a cause from evidence. For a missing element, inspect when it appeared in the DOM and whether the command ran before rendering completed. For state that diverged after a request, inspect the request, response, and console timeline, bearing in mind the
cy.request()exclusion. - Check history and code changes. Compare the failure with prior runs and the relevant commit. Cypress Branch Review can help assess a change when recorded runs exist on both the current and base branches.
- Make the smallest useful follow-up. Reproduce with the same browser and relevant CI conditions, improve the assertion or wait on the specific application condition, or investigate the implicated request or code change. Do not treat a retry pass alone as proof that the failure is harmless.
How to interpret common failure patterns
| Replay evidence | Possible explanation | Next check |
|---|---|---|
| Expected element is absent, then appears later | Render timing, an incomplete readiness condition, or a race | Inspect command ordering and wait for the application condition the test actually needs. Prefer condition-based assertions over an arbitrary delay. |
| Element is present but not interactable or has different styling | Overlay, animation, layout, or responsive/environment difference | Inspect the rendered element, surrounding DOM, styles, viewport, and any popup or overlay. |
| State changes after a request or an error appears in the console | Unexpected response, request failure, client-side error, or backend/environment difference | Correlate network and console events with the command timeline. Remember replay does not show cy.request() traffic. |
| One retry fails and another passes | Flakiness, timing, network variation, ordering, or shared state | Compare the first divergence across attempts and inspect test isolation and external dependencies. |
| Failure starts after a commit or appears only on one branch | Application or test change, or branch-specific configuration | Compare commits and branch runs; ensure both branches have recorded runs before using Branch Review. |
| No relevant event appears in the replay | Capture exclusion, upload issue, or event outside retained replay data | Check the exclusions and upload output before concluding the event did not occur. |
Use the replay as evidence about the captured run, then validate the likely explanation under the relevant conditions. Cypress’s general debugging guide also covers inspecting commands and test behavior in the app. Cypress app debugging guide
Use the Cloud CLI for terminal triage
Cypress Cloud CLI can return replay metadata and a structured timeline. First obtain the test ID from the Cloud run, then run:
cy-cloud replay info --testId <testId>
cy-cloud replay timeline --testId <testId> --commands --aroundFailure 5 --network --logsThe timeline supports selecting attempts and filtering command events, network types, logs, failed commands, and events around the failure. Consult the Cloud CLI reference for the current flags and setup details. The replay must have been captured and remain within its retention window.
Why Test Replay may be missing or unavailable
| Symptom | Likely cause | What to do |
|---|---|---|
| Replay control is disabled or absent | Unsupported Cypress version or test browser, Replay disabled in project settings, or run not recorded | Check version, browser, setting, and that the test belongs to a recorded Cloud run. |
| Replay remains unavailable after a run | Artifact upload failed or is still processing | Inspect the CI standard output for upload errors and allow processing to finish. |
| Upload fails with network or HTTP errors | Connectivity, firewall, proxy, or restricted access to Cypress endpoints | Check the runner’s network path and proxy/firewall rules, then retry a recorded run. |
| Invalid or missing upload URL | The spec may have exceeded the configured run timeout | Reduce spec runtime or increase the configured timeout, as appropriate for the project. |
| CLI reports no replay data | Replay was not captured, is processing, or is outside the retention window | Verify the run and upload first; use a currently retained replay. |
| Replay opens but evidence is incomplete | The event type is excluded or capture was constrained | Review documented exclusions and inspect other evidence sources, such as application logs. |
Cypress recommends updating Cypress before deeper troubleshooting because fixes to Test Replay are included in later releases.
Flakiness, performance, and reliability
Use retries as diagnostic evidence
Retries can reveal that a failure is intermittent, but a passing retry does not identify the cause. Compare the failing and passing attempt, then investigate timing, network variability, test ordering, shared state, and differences between local and CI environments. Review whether assertions cover the required action and resulting response rather than merely a transient visual state. Cypress’s guide to debugging failing tests recommends reviewing retries and run history.
Account for capture overhead
Cypress says replay capture can use additional resources and recommends disabling video recording when Test Replay is enabled. Capturing many or large canvas elements can affect performance; a canvas capture toggle is available in project settings. The documentation gives an illustrative upload-size example, not a universal or typical size, so estimate from your own project rather than extrapolating that example.
When Test Replay is enabled, the Runner UI does not render during cypress run by default. Cypress documents --runner-ui to turn it on, with a possible runtime cost. Leave it off in CI unless you need it for a specific debugging workflow.
Protect test data
Cypress documents default redaction of sensitive values in captured network requests and responses before upload, plus masking of password and payment field values before artifact creation. Replay and test data remain visible to project members who have access. Review your team’s Cloud access settings and Cypress security terms for your data requirements; do not put secrets into test page content on the assumption that every value is masked.
Or skip the browser setup
If the failure investigation needs a clean screenshot of the page at a particular URL, ScreenshotNeo can capture it with one GET request. Cypress Test Replay investigates a recorded test run; a screenshot API is useful for capturing a page state you can inspect or share.
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 request options. 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 of those steps can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers identify the page verdict and billing status. Its MCP server lets AI agents using Claude, Cursor, or another MCP client take screenshots. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots.
Sign up for ScreenshotNeo’s free plan and get 1,000 screenshots a month with no card.
FAQ
Does Test Replay rerun my test?
No. It lets you inspect captured state from an eligible recorded run; it does not recreate the run on your local machine.
Can I replay a test that passed?
Replay is attached to captured recorded test data, so inspect the test’s run and attempt history in Cloud. Availability depends on capture, upload, and retention.
Does enabling Test Replay require test code changes?
The Cypress CI guide says it does not require changes to test code. You do need an eligible recorded run and the project configuration and browser prerequisites.
Can replay prove a backend event did not happen?
No. Replay omits some event types, including WebSockets, server-sent events, and cy.request() traffic. Missing replay evidence cannot establish that an excluded event did not occur.
Why did a test pass locally but fail in CI?
Use the recorded CI attempt to identify the first divergence, then compare browser, timing, network, configuration, and shared-state conditions with the local run. The replay shows captured evidence, not every environmental fact.
