---
id: cloud/guides/debug-failing-tests
title: Debug Failing Tests in CI with Cypress Cloud | Cypress Documentation
description: >-
  Debug failing and flaky Cypress tests in CI with Cypress Cloud. Use Test
  Replay, AI error summaries, Branch Review, and Cloud MCP to find the root
  cause of a CI failure without reproducing it locally.
section: cloud
source_path: docs/cloud/guides/debug-failing-tests.mdx
version: b49619f519e862f29cdf8fb5a6c57d24c60b00f6
updated_at: '2026-06-19T04:14:16.080Z'
---
# Debug Failing Tests in CI with Cypress Cloud

When a Cypress test fails in continuous integration (CI), the hard part is rarely the fix. It's the investigation: the failure happened on a machine you can't see, in a browser session that no longer exists, on a commit you may have already moved past. The traditional answer (a screenshot, a video, and a stack trace) tells you _that_ a test failed, but rarely _why_.

**Cypress Cloud closes that gap.** When you [record your runs](/llm/markdown/cloud/get-started/setup.md), Cypress Cloud captures the complete state of every test as it ran in CI, so you can debug the actual failure with the same tools you use locally, get an AI explanation of what went wrong, and confirm whether your change introduced the failure or simply surfaced existing instability. This guide walks through that workflow end to end.

##### What you'll learn

*   Why a test that passes locally still fails in CI, and why that is so hard to debug
*   A step-by-step workflow to find the root cause of a failing CI test in Cypress Cloud
*   How to debug the exact CI run with [Test Replay](/llm/markdown/cloud/features/test-replay.md) instead of reproducing it locally
*   How AI [Error Summaries](/llm/markdown/cloud/features/cypress-ai-features.md#Error-Summaries) and [Cloud MCP](/llm/markdown/cloud/integrations/cloud-mcp.md) speed up triage and root-cause analysis
*   How to tell a real regression apart from pre-existing [flake](/llm/markdown/cloud/features/flaky-test-management.md) before you merge
*   Which Cypress Cloud tool to reach for, based on the symptom you are seeing

## Why tests fail in CI but pass locally

Most "works on my machine" failures come down to a difference between your laptop and the CI environment that is invisible after the run ends:

*   **Timing and race conditions.** CI machines are often slower or more heavily loaded, so an element that was always ready locally now renders a beat late.
*   **Network conditions.** A slow, rate-limited, or intermittently failing API response changes behavior that was instant on your machine.
*   **Test order and shared state.** In CI, specs may run in [parallel](/llm/markdown/cloud/features/smart-orchestration/parallelization.md) or a different order, exposing state leaking between tests.
*   **Environment differences.** Different browser versions, viewport sizes, operating systems, time zones, seed data, or feature flags.
*   **True regressions.** Sometimes the test is right and the code is wrong, the failure is a real bug your change introduced.

The common thread is that the evidence you need (the DOM, network traffic, console errors, and the order things happened in) lived in a browser session that is gone by the time you read the failure. Reproducing it locally is guesswork, and often impossible.

## The debugging workflow at a glance

When a recorded run fails, the fastest path from red build to root cause is:

1.  **[Find the failing test](#Step-1-Go-straight-to-the-failing-test)** in Cypress Cloud, without scrolling through CI logs.
2.  **[Read the AI Error Summary](#Step-2-Read-the-AI-Error-Summary)** to understand what went wrong in plain language.
3.  **[Replay the exact CI run](#Step-3-Replay-the-exact-failure-with-Test-Replay)** with Test Replay to inspect the DOM, network, and console at the moment of failure.
4.  **[Check whether it's a regression or flake](#Step-4-Is-it-a-regression-or-flake)** with Branch Review and Flaky Test Management.
5.  **[Fix and verify](#Step-5-Fix-and-verify)**, optionally without leaving your editor using Cloud MCP.

The rest of this guide covers each step in detail.

## Step 1: Go straight to the failing test

Instead of reading raw CI output, open the run in Cypress Cloud. The [**Tests for Review**](/llm/markdown/cloud/features/recorded-runs.md#Tests-for-Review) panel on a run's [Overview](/llm/markdown/cloud/features/recorded-runs.md#Overview-tab) tab consolidates the results that actually need a human, ordered by **Failed**, then **Flaky**, then **Modified**. Rather than scanning an entire suite, you go straight to the handful of tests that matter.

Clicking a test opens the [test detail sidebar](/llm/markdown/cloud/features/recorded-runs.md#Test-detail-sidebar), your home base for debugging a single failure. It surfaces the error, every retry attempt, artifacts, the test's recent pass/fail history, and the [git commits that changed the test](/llm/markdown/cloud/features/recorded-runs.md#Test-Code-History), all in one place.

The [**Previous runs**](/llm/markdown/cloud/features/recorded-runs.md#Previous-runs) timeline in the sidebar instantly tells you whether you're looking at a brand-new regression or a long-standing flaky test, and exactly when its behavior changed. Check it first; it often reframes the whole investigation.

## Step 2: Read the AI Error Summary

At the top of the failure, Cypress Cloud's AI [**Error Summaries**](/llm/markdown/cloud/features/cypress-ai-features.md#Error-Summaries) give a plain-language explanation of what went wrong and what led to the failure, so you don't have to parse a raw stack trace to get oriented. Paired with the [**Test Intent Summary**](/llm/markdown/cloud/features/recorded-runs.md#test-intent-summary) (an AI description of what the test is _supposed_ to verify) you can understand both the goal of the test and the reason it failed in seconds, before opening a single artifact.

The full stack trace, error message, and point-of-failure code frame for each attempt sit directly below the summary in the [Attempts and errors](/llm/markdown/cloud/features/recorded-runs.md#attempts-and-errors) section.

## Step 3: Replay the exact failure with Test Replay

This is the core of debugging in Cypress Cloud. [**Test Replay**](/llm/markdown/cloud/features/test-replay.md) lets you replay the test _exactly_ as it ran in CI, with full debugging capability. You are not looking at a video recording, you are stepping through the real run.

With Test Replay you can:

*   **Time travel** to the exact moment of failure and step through the [command log](/llm/markdown/app/core-concepts/open-mode.md#Command-Log), just like in the Cypress app.
*   **Open developer tools** to inspect the DOM exactly as it rendered in CI, including styles, attributes, shadow DOM, and iframes.
*   **Inspect network requests, responses, and console logs** and line them up with the exact moment they returned or printed during the run.
*   **See canvas elements as they rendered**, giving you the visual context you need when debugging deeply interactive UIs like maps, charts, and games.
*   **Scrub the timeline** and play back the failure at different speeds.
*   **Switch instantly between test attempts** to compare a passing run against a failing one on the same code and narrow down the cause of flake.

Because Test Replay reproduces the run itself, **you no longer need to reproduce CI failures on your own machine.** That single capability removes the most expensive and frustrating part of debugging CI: the guesswork of trying to recreate an environment you can't see. A timing issue, a missing network response, or an unexpected DOM state that would be invisible in a screenshot is right there to inspect.

Test Replay is also **shareable**. The link preserves the exact timestamp, so you can drop a teammate at the precise moment the test reached an important state and they land on exactly what you see, turning "I can't reproduce it" into a collaborative debugging session instead of a back-and-forth.

## Step 4: Is it a regression or flake?

Before you spend time on a fix, answer the question that determines what you're actually dealing with: **did my change cause this, or was it already broken or unstable?**

### Use Branch Review to isolate what your change broke

[**Branch Review**](/llm/markdown/cloud/features/branch-review.md) compares the run on your branch against its base branch in a single view, so you can instantly see the failures your Pull Request _introduced_ versus problems that already existed on `main`. Open a new failure to see the base branch (passing) and your branch (failing) side by side, then use Test Replay and the code diff on each to pinpoint exactly what your change broke, without re-running anything locally.

This is also the fastest way to **stop chasing pre-existing flake**: if a test was already failing intermittently on the base branch, Branch Review makes that obvious so you don't waste time on noise you didn't create.

### Use Flaky Test Management when a test passes on retry

If a test fails and then passes on a [retry](/llm/markdown/app/guides/test-retries.md) with no code change, it's **flaky**, and flake needs a different approach than a hard failure. [**Flaky Test Management**](/llm/markdown/cloud/features/flaky-test-management.md) automatically detects, scores, and tracks flaky tests from your recorded runs. From a flaky test's detail panel you can open any flaky run in Test Replay and **compare a passing attempt against a failing one on the same code**, which is often the fastest way to spot the race condition, timing issue, or environmental dependency behind the flake.

A test can pass after retries and still be flaky. The build goes green, but the underlying instability (and its cost) is still there. This is exactly why flake is so easy to miss without dedicated tracking. See [failure rate vs. flake rate](/llm/markdown/cloud/features/flaky-test-management.md#Failure-rate-vs-flake-rate).

## Step 5: Fix and verify

Once you understand the root cause:

*   **Fix the issue**, whether it's a true bug in your application, a timing assumption in the test, or a missing wait on a network request you spotted in Test Replay.
*   **Re-record the run** and use [Branch Review](/llm/markdown/cloud/features/branch-review.md) to confirm the failure is now _resolved_ and that you didn't introduce new failures or flake elsewhere.
*   **Keep failing code out of `main`.** With the [GitHub](/llm/markdown/cloud/integrations/github.md), [GitLab](/llm/markdown/cloud/integrations/gitlab.md), and [Bitbucket](/llm/markdown/cloud/integrations/bitbucket.md) integrations, status checks can block a merge until your tests are green, and PR comments surface failure and [flake](/llm/markdown/cloud/features/flaky-test-management.md#Flake-Alerting) details with deep links back into Cypress Cloud.

### Debug from your editor with Cloud MCP

You can run much of this workflow without leaving your AI coding assistant. [**Cloud MCP**](/llm/markdown/cloud/integrations/cloud-mcp.md) connects assistants like Claude, Cursor, and GitHub Copilot directly to your Cypress Cloud results, closing the context gap between CI and your editor. Instead of manually triaging which failures are real, you can ask your agent to pull the failing tests for a run, read the error details and stack traces, and follow the Test Replay link straight to the root cause.

> "Get the failed tests from the latest Cypress Cloud run on this branch, summarize the errors, and tell me which are likely regressions versus known flake."

Cloud MCP is generally available on **every Cypress Cloud plan at no additional cost**.

## Which tool should I use?

Different symptoms call for different Cypress Cloud tools. Use this as a quick reference:

| Symptom | Start here |
| --- | --- |
| A test fails in CI and I can't reproduce it | [Test Replay](/llm/markdown/cloud/features/test-replay.md) |
| I don't understand the stack trace | [AI Error Summaries](/llm/markdown/cloud/features/cypress-ai-features.md#Error-Summaries) |
| A test passes on retry without code changes | [Flaky Test Management](/llm/markdown/cloud/features/flaky-test-management.md) |
| Did my PR cause this, or was it already broken? | [Branch Review](/llm/markdown/cloud/features/branch-review.md) |
| When did this test start failing? | [Previous runs](/llm/markdown/cloud/features/recorded-runs.md#Previous-runs) & [Test Code History](/llm/markdown/cloud/features/recorded-runs.md#Test-Code-History) |
| I want to debug without leaving my editor | [Cloud MCP](/llm/markdown/cloud/integrations/cloud-mcp.md) |
| Keep failing or flaky code from merging | [GitHub](/llm/markdown/cloud/integrations/github.md) / [GitLab](/llm/markdown/cloud/integrations/gitlab.md) / [Bitbucket](/llm/markdown/cloud/integrations/bitbucket.md) status checks |

## Get started

Every capability in this guide works on runs [recorded to Cypress Cloud](/llm/markdown/cloud/get-started/setup.md) from your CI/CD pipeline. You keep writing and running tests exactly as you do today, recording is the only setup required.

To get started with Cypress Cloud, [sign up](https://cloud.cypress.io/signup) to start your **30 day free trial** - including all premium Cypress Cloud features and plenty of test results to let you experience the power of Cypress Cloud!

[Record your first run ➜](/llm/markdown/cloud/get-started/setup.md)

## See also

*   [Test Replay](/llm/markdown/cloud/features/test-replay.md) — replay the exact CI run with full debug capability
*   [Recorded Runs](/llm/markdown/cloud/features/recorded-runs.md) — view, filter, and analyze every recorded run
*   [Branch Review](/llm/markdown/cloud/features/branch-review.md) — compare branches to catch regressions before merge
*   [Flaky Test Management](/llm/markdown/cloud/features/flaky-test-management.md) — detect, score, and fix flaky tests
*   [Cypress AI](/llm/markdown/cloud/features/cypress-ai-features.md) — AI error summaries, test intent, and more
*   [Cloud MCP](/llm/markdown/cloud/integrations/cloud-mcp.md) — debug from your AI coding assistant
*   [Test retries](/llm/markdown/app/guides/test-retries.md) — the mechanism behind flake detection
*   [Set up Cypress Cloud](/llm/markdown/cloud/get-started/setup.md) — record your runs in CI
*   [Cypress Cloud FAQ](/llm/markdown/cloud/faq.md#Debugging) — common debugging questions answered