How to Use Test Replay to Debug Failed Tests

Use a test replay to inspect the recorded execution around a failure: find the failed command, examine the page state and events at that moment, and compare the failing attempt with a passing one if available. In Cypress, Test Replay in Cypress Cloud can expose the recorded DOM, network requests, console logs, JavaScript errors, and element rendering from a CI run. It gives you evidence to investigate; it does not guarantee that the replay will identify the root cause.

This guide focuses on Cypress Cloud Test Replay. “Test replay” is not one universal interface: Cypress Cloud replay is distinct from tools such as pytest’s pytest-replay plugin and from a video or screenshot of a test.

1. Confirm that the failed run has a replay

Before diagnosing a missing replay, check the capture prerequisites and the CI run:

The run was recorded to Cypress Cloud.
The project has Test Replay enabled in its settings.
The run uses Cypress v13 or later and a Chromium-based browser.
The replay data uploaded successfully. Check the Cypress output for upload errors.

Cypress documents these requirements in its Test Replay setup and troubleshooting guidance. It notes that Safari versions below 16.4 may lack APIs needed to view a replay. Requirements can change, so check the current documentation when configuring a project.

If the run is on a pull request, make sure the default or base branch also has recorded runs when you want to compare a passing baseline with a failing change. Cypress’s CI guide says both sides need recorded runs for attempt comparison.

2. Start with the failure report, then inspect the replay

Read the error and code frame. Note the failed assertion or command, the expected and actual values, and the point in the test where the failure occurred.
Open the replay near the failure. Use its timeline to find the last expected action and the first unexpected state. A replay is a time-ordered inspection of a recorded run, not just a video to watch from beginning to end.
Inspect the page at that time. Look at the DOM and element rendering. Check whether the target exists, is visible, has the expected text, or is covered or otherwise different from what the assertion assumed.
Correlate network and console evidence. Inspect requests and responses around the same point, then check console output and JavaScript errors. For example, a missing element could be related to a failed request or a page error; the replay evidence helps you investigate that possibility, but does not establish the cause on its own.
Form one testable explanation. Decide whether the evidence points toward a changed product behavior, an unexpected response, timing or race behavior, a JavaScript error, or an environment difference. These are useful diagnostic hypotheses, not an exhaustive list.
Make one targeted change and rerun. Confirm that the failure signature changes or disappears, while keeping assertions meaningful. Avoid weakening an assertion or adding a long wait just to make the build green.

Cypress’s CI debugging guide recommends beginning with the error, stack trace, and code frame, then using replay and attempt comparison to investigate what happened.

3. Compare a failing attempt with a passing one

When a test has both a failed and a passed attempt, compare them at the same logical step. Look for differences in page state, command ordering, network responses, console output, and rendered elements. A difference can narrow the investigation, but correlation alone does not prove which difference caused the failure.

For a pull request comparison, record runs on both the default branch and the change branch. If only the failing run is recorded, replay can still show its context, but there is no recorded passing baseline to compare against.

A failure followed by a pass on retry, with no code change, is a flakiness signal. It is not proof that the failure is harmless: the retry may simply have encountered different timing, data, or environment conditions. Investigate the failed attempt before treating a green retry as resolution.

4. Replay, retry, rerun, and local debugging are different

Approach	What it does	Best use
Replay	Inspects evidence from an already recorded attempt.	Understand the state and events around a CI failure.
Retry	Runs a failed test again during the same test run.	Reveal whether an outcome is intermittent; it does not explain the original failure.
Rerun optimization	After a CI build, selects previously failed tests or specs to execute again.	Re-execute failures without necessarily rerunning the whole suite.
Local debug session	Runs and inspects a test in the local environment.	Test a hypothesis interactively or investigate a failure that depends on local control.

Cypress distinguishes retries during a run from rerun optimization after a recorded build in its Cloud FAQ. Replay is diagnostic evidence; retries and reruns are execution choices. In another framework, use its own debugging workflow: for example, Playwright documents --debug and an HTML report with filters for browser, result status, and flaky tests in its running and debugging tests guide.

5. Reproduce CI-only and flaky failures

A replay can tell you what the recorded CI attempt did, while a local reproduction lets you vary inputs and inspect behavior interactively. If the failure is intermittent, preserve the failing attempt’s evidence before changing timing or retry settings.

Compare the failing and passing attempt first, if both exist.
Check whether the response, test data, or browser environment differed.
Use a local run to test a specific explanation rather than making several unrelated changes at once.
Rerun after a change and confirm the original assertion still catches the behavior it was meant to catch.

For pytest users, the official pytest flaky-test guide explains that rerunning can mitigate the effects of flaky tests and identifies pytest-replay as a plugin for reproducing CI crashes or flaky tests locally. That plugin is not Cypress Cloud Test Replay.

6. Common replay problems and fixes

Symptom	Likely cause	What to check
No replay is available	The run was not recorded, replay is disabled, or the run does not meet the documented version or browser requirements.	Confirm the run is recorded, enable Test Replay in project settings, and verify Cypress v13+ and a Chromium-based browser.
Replay upload fails	Network access, a firewall or proxy, or a run-time limit prevents upload.	Inspect Cypress’s upload output; check CI network and proxy rules and whether the run reaches its time limit.
A replay cannot be viewed in Safari	Safari below 16.4 may lack APIs required to view a replay.	Use a supported viewing environment and consult the current Cypress compatibility notes.
There is no passing attempt to compare	The baseline or default branch has no recorded run available.	Set up recording on both the base branch and the change branch, then compare recorded attempts.
Capture slows a test with a large canvas	Canvas capture can be resource-intensive, especially for large canvas elements.	Monitor test performance and disable canvas capture if it is not needed for diagnosis.
The Cypress Runner UI is not rendered during `cypress run`	Enabling replay suppresses Runner UI rendering during that command.	Use replay for the recorded run. Cypress notes that forcing the UI with `--runner-ui` can slow tests, especially on lower-resourced machines.
The replay does not make the cause obvious	A replay shows recorded evidence, not an automatic root-cause verdict.	Align DOM, requests, responses, console events, and the failed command in time; then test one explanation with a targeted change.

7. Performance, reliability, and data access

Replay capture can add resource use. Cypress calls out canvas capture as potentially resource-intensive and says forcing Runner UI rendering during cypress run may slow tests, particularly on lower-resourced machines. Monitor your own CI duration and resource use; do not assume a fixed performance impact.

Replay is only as useful as the run data that was captured and uploaded. Keep recording configured on branches you need to compare, and investigate upload errors when an expected replay is missing. A retry can provide another observation, but it does not repair missing evidence from the original attempt.

Cypress says replay access follows project access: people who can access the project can access test replays, including test data. Review the project’s access settings and Cypress’s Terms of Use and Security & Compliance guidance before uploading sensitive test data. Cypress documentation also describes usage limits and says Test Replay is available across Cloud plans at no additional cost; check current plan terms and limits before relying on those details.

Or skip the browser setup

If your debugging step needs a current screenshot of the page rather than an interactive replay of a recorded CI test, ScreenshotNeo can return an image or PDF with one API request. This is useful for collecting a visual artifact; it does not replace Cypress replay’s recorded DOM, network, and console evidence. See the 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.webp

import requests

r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Cookie and consent 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 gives AI agents tools to take screenshots, inspect page information, and capture PDFs.
The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Every feature is on every plan.

Create a free ScreenshotNeo account to get 1,000 screenshots a month with no card.

FAQ

Does a passing retry mean the bug is fixed?

No. A pass after a failure without a code change is evidence of an intermittent outcome. Investigate the failed attempt and confirm the underlying condition is understood.

Can I compare a pull request failure with the base branch?

Yes, when both the base branch and the change branch have recorded runs available for comparison.

Is Cypress Test Replay the same as a test video?

No. Cypress describes replay as providing inspectable DOM, network, console, error, and rendering evidence, while a video or screenshot is a visual artifact.

Does ScreenshotNeo replay a Cypress test?

No. ScreenshotNeo captures a webpage image or PDF from a URL; use Cypress Cloud Test Replay to inspect a recorded Cypress test execution.