Use test replay to inspect what happened during a failed CI run, not just the final error: start with the failure and code frame, then examine the replay’s timeline, DOM, network activity, and console output around the first unexpected state. For Cypress, this means Cypress Cloud Test Replay, a feature for recorded runs—not a generic replay interface shared by every test framework.
What test replay shows—and what it does not
Cypress Cloud Test Replay lets you inspect details of a recorded Cypress test run, including DOM state, network requests, console logs, JavaScript errors, and element rendering. That context can explain a failure that a final stack trace or screenshot alone leaves ambiguous. Replay is an investigative view of an execution that already happened; it does not guarantee that it will identify the root cause or reproduce the problem locally. Cypress Test Replay documentation
These steps are specific to Cypress Cloud. Other frameworks have their own debugging workflows, and similarly named tools are not necessarily equivalent. For example, pytest’s pytest-replay plugin is for reproducing CI-observed crashes or flaky tests in the pytest ecosystem; it is not Cypress Cloud Test Replay. pytest’s flaky-test guide
Debug a failed Cypress CI attempt in replay
-
Read the failure report first
Start with the failed attempt’s error message, stack trace, and code frame. Note the command or assertion that failed, the expected and actual state if shown, and whether other attempts in the same run behaved differently. This gives you a specific point to inspect rather than treating the entire replay as equally relevant. Cypress’s CI debugging guide
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy. -
Open the replay at the failure point
Use the replay timeline to locate the failure and move backward to the last successful actions. Look for the first point where the application state diverges from what the test expects. Replay is time-oriented inspection of a captured run, not simply a video to watch from beginning to end. Cypress Test Replay documentation
-
Correlate the DOM with network and console evidence
At the relevant moment, inspect the DOM and element rendering alongside requests, responses, console messages, and JavaScript errors. A missing element is the observed symptom; a request that failed, a response with unexpected content, or a preceding script error may help explain it. Treat those as hypotheses to check against the replay, not as predetermined causes.
-
Compare a passing attempt when available
If the same test has both a passing and failing attempt, compare their state and events at the same logical point. A comparison is most useful when it isolates the first meaningful difference, such as a different response or a delayed state change. Cypress notes that comparisons require recorded runs on both sides; record the default or base branch as well as the change branch if you want to compare them. Cypress’s CI debugging guide
-
Make one evidence-led change and rerun
Classify the likely cause from what the replay shows: for example, an assertion that no longer matches the product, timing or race behavior, an unexpected response, a JavaScript error, or an environment difference. These are diagnostic possibilities, not an exhaustive vendor taxonomy. Make a targeted change, rerun the test, and check whether the same failure signature is gone. Avoid weakening an assertion or adding an arbitrary wait just to make the run green.
Recommended Free Tools
Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Use retries and reruns without confusing them with replay
Replay, retry, and rerun are different actions. Replay helps explain an existing recorded attempt. A retry creates another attempt during the same test run. Cypress Cloud’s rerun optimization, by contrast, can select previously failed tests or specs after a CI build. Cypress Cloud FAQ
A test that fails and then passes on retry without a code change is a signal of possible flakiness, not proof that the failure is harmless. The second outcome can help reveal intermittency, but a passing retry can also let a build pass while the underlying test or application condition remains. Inspect the failed and passing attempts and use their differences to guide investigation.
Retries are execution policy, not a substitute for diagnosis. pytest’s documentation says rerunning failed tests can mitigate the negative effects of flaky tests and identifies pytest-replay as one option for reproducing CI crashes or flaky tests locally; that is a separate workflow from Cypress Cloud replay. pytest’s flaky-test guide
When replay is unavailable or fails to upload
Cypress’s documented requirements and troubleshooting notes are product-specific and can change, so check the current Test Replay documentation if your setup differs. The documentation says replay requires recorded runs using Cypress v13 or later, a Chromium-based browser, and Test Replay enabled in project settings. It also notes Safari versions below 16.4 may lack APIs needed to view a replay.
- No replay appears: Check that the run was recorded, Cypress is v13 or later, the browser is Chromium-based, and the feature is enabled in project settings.
- Replay upload fails: Check network connectivity and firewall or proxy configuration, and review whether the run hit a time limit. These are among the upload checks called out by Cypress.
- Viewing fails in Safari: Cypress notes that Safari below 16.4 may lack required viewing APIs; try a supported Chromium-based browser for the replay workflow.
Performance, access, and sensitive test data
Replay capture has trade-offs. Cypress says canvas capture can be resource-intensive, especially for large canvas elements, and recommends monitoring test performance and disabling canvas capture if needed. Enabling replay suppresses Cypress Runner UI rendering during cypress run; forcing the UI with --runner-ui may slow tests, particularly on lower-resourced machines. Do not assume capture has no effect on runtime. Cypress Test Replay documentation
Rank #4
Cypress says replay access follows project access: everyone with access to the project can see test replays, including test data. Review the Cypress Cloud Terms of Use and Security & Compliance guidance before uploading sensitive test data. The documentation describes availability on all Cypress Cloud plans subject to usage limits; check current plan and limit details rather than assuming they remain unchanged.
Replay compared with other debugging evidence
| Approach | What it helps you inspect | Best use |
|---|---|---|
| Cypress Cloud Test Replay | Recorded DOM, network, console, JavaScript errors, and rendering state. | Investigating the sequence and state around a recorded CI failure. |
| Screenshot or video | Visual output, with less interactive forensic context than replay according to Cypress. | Seeing what the page looked like or communicating a visual symptom. |
| Retry | A new attempt during the same test run. | Detecting whether an outcome changes across attempts; it does not explain the prior attempt by itself. |
| Rerun optimization | Selected failed tests or specs executed again after a completed build. | Re-running failures selectively after the build, rather than inspecting the old execution. |
| Playwright debugging | Playwright documents a --debug command and an HTML report with filters for browser, status, and flaky tests. |
Debugging and reviewing results in a Playwright workflow, not as a direct Cypress Cloud equivalent. Playwright running tests |
Or skip the browser setup
For a separate task—capturing a page as an image or PDF—ScreenshotNeo provides a screenshot API and MCP server. It does not replay a test run or replace Cypress Test Replay. A single GET request can capture a URL:
ScreenshotNeo API documentation
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo accepts cookie or consent banners and removes 60+ known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and responses indicate the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf for AI agents and other MCP clients. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. Sign up for ScreenshotNeo’s free plan.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsFrequently Asked Questions
Does a passing retry mean the test is fixed?
No. A fail-then-pass outcome without a code change is a flakiness signal; inspect the attempts to find what differed.
Best Value
Is Cypress Test Replay the same as pytest-replay?
No. Cypress Test Replay is a Cypress Cloud feature for recorded Cypress runs; pytest-replay is a separate pytest plugin.
Can replay guarantee the root cause of a CI failure?
No. It provides execution evidence that can guide investigation, but the evidence still needs interpretation and may not establish a single cause.
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.
