{
  "doc": {
    "id": "cloud/guides/debug-failing-tests",
    "title": "Debug failing tests in CI with Cypress Cloud",
    "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": "/llm/markdown/cloud/guides/debug-failing-tests.md",
    "version": "3b85801b725bd02bf0cb58cedaf42944712cdc72",
    "updated_at": "2026-07-12T03:11:07.806Z",
    "headings": [
      {
        "id": "cloud/guides/debug-failing-tests#debug-failing-tests-in-ci-with-cypress-cloud",
        "text": "Debug Failing Tests in CI with Cypress Cloud",
        "level": 1
      },
      {
        "id": "cloud/guides/debug-failing-tests#why-tests-fail-in-ci-but-pass-locally",
        "text": "Why tests fail in CI but pass locally",
        "level": 2
      },
      {
        "id": "cloud/guides/debug-failing-tests#the-debugging-workflow-at-a-glance",
        "text": "The debugging workflow at a glance",
        "level": 2
      },
      {
        "id": "cloud/guides/debug-failing-tests#step-1-go-straight-to-the-failing-test",
        "text": "Step 1: Go straight to the failing test",
        "level": 2
      },
      {
        "id": "cloud/guides/debug-failing-tests#step-2-read-the-ai-error-summary",
        "text": "Step 2: Read the AI Error Summary",
        "level": 2
      },
      {
        "id": "cloud/guides/debug-failing-tests#step-3-replay-the-exact-failure-with-test-replay",
        "text": "Step 3: Replay the exact failure with Test Replay",
        "level": 2
      },
      {
        "id": "cloud/guides/debug-failing-tests#step-4-is-it-a-regression-or-flake",
        "text": "Step 4: Is it a regression or flake?",
        "level": 2
      },
      {
        "id": "cloud/guides/debug-failing-tests#use-branch-review-to-isolate-what-your-change-broke",
        "text": "Use Branch Review to isolate what your change broke",
        "level": 3
      },
      {
        "id": "cloud/guides/debug-failing-tests#use-flaky-test-management-when-a-test-passes-on-retry",
        "text": "Use Flaky Test Management when a test passes on retry",
        "level": 3
      },
      {
        "id": "cloud/guides/debug-failing-tests#step-5-fix-and-verify",
        "text": "Step 5: Fix and verify",
        "level": 2
      },
      {
        "id": "cloud/guides/debug-failing-tests#debug-from-your-editor-with-cloud-mcp",
        "text": "Debug from your editor with Cloud MCP",
        "level": 3
      },
      {
        "id": "cloud/guides/debug-failing-tests#which-tool-should-i-use",
        "text": "Which tool should I use?",
        "level": 2
      },
      {
        "id": "cloud/guides/debug-failing-tests#get-started",
        "text": "Get started",
        "level": 2
      },
      {
        "id": "cloud/guides/debug-failing-tests#see-also",
        "text": "See also",
        "level": 2
      }
    ]
  },
  "chunks": [
    {
      "id": "cloud/guides/debug-failing-tests#why-tests-fail-in-ci-but-pass-locally",
      "doc_id": "cloud/guides/debug-failing-tests",
      "heading": "Why tests fail in CI but pass locally",
      "heading_level": 2,
      "content_markdown": "## Why tests fail in CI but pass locally\n\nMost \"works on my machine\" failures come down to a difference between your laptop and the CI environment that is invisible after the run ends:\n\n*   **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.\n*   **Network conditions.** A slow, rate-limited, or intermittently failing API response changes behavior that was instant on your machine.\n*   **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.\n*   **Environment differences.** Different browser versions, viewport sizes, operating systems, time zones, seed data, or feature flags.\n*   **True regressions.** Sometimes the test is right and the code is wrong, the failure is a real bug your change introduced.\n\nThe 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.\n",
      "section": "cloud",
      "anchors": [
        "why-tests-fail-in-ci-but-pass-locally"
      ],
      "path": "/llm/json/chunked/cloud/guides/debug-failing-tests.json",
      "token_estimate": 247
    },
    {
      "id": "cloud/guides/debug-failing-tests#the-debugging-workflow-at-a-glance",
      "doc_id": "cloud/guides/debug-failing-tests",
      "heading": "The debugging workflow at a glance",
      "heading_level": 2,
      "content_markdown": "## The debugging workflow at a glance\n\nWhen a recorded run fails, the fastest path from red build to root cause is:\n\n1.  **[Find the failing test](#Step-1-Go-straight-to-the-failing-test)** in Cypress Cloud, without scrolling through CI logs.\n2.  **[Read the AI Error Summary](#Step-2-Read-the-AI-Error-Summary)** to understand what went wrong in plain language.\n3.  **[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.\n4.  **[Check whether it's a regression or flake](#Step-4-Is-it-a-regression-or-flake)** with Branch Review and Flaky Test Management.\n5.  **[Fix and verify](#Step-5-Fix-and-verify)**, optionally without leaving your editor using Cloud MCP.\n\nThe rest of this guide covers each step in detail.\n",
      "section": "cloud",
      "anchors": [
        "the-debugging-workflow-at-a-glance"
      ],
      "path": "/llm/json/chunked/cloud/guides/debug-failing-tests.json",
      "token_estimate": 143
    },
    {
      "id": "cloud/guides/debug-failing-tests#step-1-go-straight-to-the-failing-test",
      "doc_id": "cloud/guides/debug-failing-tests",
      "heading": "Step 1: Go straight to the failing test",
      "heading_level": 2,
      "content_markdown": "## Step 1: Go straight to the failing test\n\nInstead 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.\n\nClicking 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.\n\nThe [**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.\n",
      "section": "cloud",
      "anchors": [
        "step-1-go-straight-to-the-failing-test"
      ],
      "path": "/llm/json/chunked/cloud/guides/debug-failing-tests.json",
      "token_estimate": 187
    },
    {
      "id": "cloud/guides/debug-failing-tests#step-2-read-the-ai-error-summary",
      "doc_id": "cloud/guides/debug-failing-tests",
      "heading": "Step 2: Read the AI Error Summary",
      "heading_level": 2,
      "content_markdown": "## Step 2: Read the AI Error Summary\n\nAt 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.\n\nThe 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.\n",
      "section": "cloud",
      "anchors": [
        "step-2-read-the-ai-error-summary"
      ],
      "path": "/llm/json/chunked/cloud/guides/debug-failing-tests.json",
      "token_estimate": 144
    },
    {
      "id": "cloud/guides/debug-failing-tests#step-3-replay-the-exact-failure-with-test-replay",
      "doc_id": "cloud/guides/debug-failing-tests",
      "heading": "Step 3: Replay the exact failure with Test Replay",
      "heading_level": 2,
      "content_markdown": "## Step 3: Replay the exact failure with Test Replay\n\nThis 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.\n\nWith Test Replay you can:\n\n*   **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.\n*   **Open developer tools** to inspect the DOM exactly as it rendered in CI, including styles, attributes, shadow DOM, and iframes.\n*   **Inspect network requests, responses, and console logs** and line them up with the exact moment they returned or printed during the run.\n*   **See canvas elements as they rendered**, giving you the visual context you need when debugging deeply interactive UIs like maps, charts, and games.\n*   **Scrub the timeline** and play back the failure at different speeds.\n*   **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.\n\nBecause 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.\n\nTest 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.\n",
      "section": "cloud",
      "anchors": [
        "step-3-replay-the-exact-failure-with-test-replay"
      ],
      "path": "/llm/json/chunked/cloud/guides/debug-failing-tests.json",
      "token_estimate": 399
    },
    {
      "id": "cloud/guides/debug-failing-tests#step-4-is-it-a-regression-or-flake",
      "doc_id": "cloud/guides/debug-failing-tests",
      "heading": "Step 4: Is it a regression or flake?",
      "heading_level": 2,
      "content_markdown": "## Step 4: Is it a regression or flake?\n\nBefore 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?**\n\n### Use Branch Review to isolate what your change broke\n\n[**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.\n\nThis 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.\n\n### Use Flaky Test Management when a test passes on retry\n\nIf 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.\n\nA 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).\n",
      "section": "cloud",
      "anchors": [
        "step-4-is-it-a-regression-or-flake"
      ],
      "path": "/llm/json/chunked/cloud/guides/debug-failing-tests.json",
      "token_estimate": 397
    },
    {
      "id": "cloud/guides/debug-failing-tests#use-branch-review-to-isolate-what-your-change-broke",
      "doc_id": "cloud/guides/debug-failing-tests",
      "heading": "Use Branch Review to isolate what your change broke",
      "heading_level": 3,
      "content_markdown": "### Use Branch Review to isolate what your change broke\n\n[**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.\n\nThis 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.\n",
      "section": "cloud",
      "anchors": [
        "use-branch-review-to-isolate-what-your-change-broke"
      ],
      "path": "/llm/json/chunked/cloud/guides/debug-failing-tests.json",
      "token_estimate": 159
    },
    {
      "id": "cloud/guides/debug-failing-tests#use-flaky-test-management-when-a-test-passes-on-retry",
      "doc_id": "cloud/guides/debug-failing-tests",
      "heading": "Use Flaky Test Management when a test passes on retry",
      "heading_level": 3,
      "content_markdown": "### Use Flaky Test Management when a test passes on retry\n\nIf 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.\n\nA 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).\n",
      "section": "cloud",
      "anchors": [
        "use-flaky-test-management-when-a-test-passes-on-retry"
      ],
      "path": "/llm/json/chunked/cloud/guides/debug-failing-tests.json",
      "token_estimate": 188
    },
    {
      "id": "cloud/guides/debug-failing-tests#step-5-fix-and-verify",
      "doc_id": "cloud/guides/debug-failing-tests",
      "heading": "Step 5: Fix and verify",
      "heading_level": 2,
      "content_markdown": "## Step 5: Fix and verify\n\nOnce you understand the root cause:\n\n*   **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.\n*   **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.\n*   **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.\n\n### Debug from your editor with Cloud MCP\n\nYou 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.\n\n> \"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.\"\n\nCloud MCP is generally available on **every Cypress Cloud plan at no additional cost**.\n",
      "section": "cloud",
      "anchors": [
        "step-5-fix-and-verify"
      ],
      "path": "/llm/json/chunked/cloud/guides/debug-failing-tests.json",
      "token_estimate": 312
    },
    {
      "id": "cloud/guides/debug-failing-tests#debug-from-your-editor-with-cloud-mcp",
      "doc_id": "cloud/guides/debug-failing-tests",
      "heading": "Debug from your editor with Cloud MCP",
      "heading_level": 3,
      "content_markdown": "### Debug from your editor with Cloud MCP\n\nYou 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.\n\n> \"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.\"\n\nCloud MCP is generally available on **every Cypress Cloud plan at no additional cost**.\n",
      "section": "cloud",
      "anchors": [
        "debug-from-your-editor-with-cloud-mcp"
      ],
      "path": "/llm/json/chunked/cloud/guides/debug-failing-tests.json",
      "token_estimate": 168
    },
    {
      "id": "cloud/guides/debug-failing-tests#which-tool-should-i-use",
      "doc_id": "cloud/guides/debug-failing-tests",
      "heading": "Which tool should I use?",
      "heading_level": 2,
      "content_markdown": "## Which tool should I use?\n\nDifferent symptoms call for different Cypress Cloud tools. Use this as a quick reference:\n\n| Symptom | Start here |\n| --- | --- |\n| A test fails in CI and I can't reproduce it | [Test Replay](/llm/markdown/cloud/features/test-replay.md) |\n| I don't understand the stack trace | [AI Error Summaries](/llm/markdown/cloud/features/cypress-ai-features.md#Error-Summaries) |\n| A test passes on retry without code changes | [Flaky Test Management](/llm/markdown/cloud/features/flaky-test-management.md) |\n| Did my PR cause this, or was it already broken? | [Branch Review](/llm/markdown/cloud/features/branch-review.md) |\n| 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) |\n| I want to debug without leaving my editor | [Cloud MCP](/llm/markdown/cloud/integrations/cloud-mcp.md) |\n| 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 |\n",
      "section": "cloud",
      "anchors": [
        "which-tool-should-i-use"
      ],
      "path": "/llm/json/chunked/cloud/guides/debug-failing-tests.json",
      "token_estimate": 176
    },
    {
      "id": "cloud/guides/debug-failing-tests#get-started",
      "doc_id": "cloud/guides/debug-failing-tests",
      "heading": "Get started",
      "heading_level": 2,
      "content_markdown": "## Get started\n\nEvery 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.\n\nTo 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!\n\n[Record your first run ➜](/llm/markdown/cloud/get-started/setup.md)\n",
      "section": "cloud",
      "anchors": [
        "get-started"
      ],
      "path": "/llm/json/chunked/cloud/guides/debug-failing-tests.json",
      "token_estimate": 103
    },
    {
      "id": "cloud/guides/debug-failing-tests#see-also",
      "doc_id": "cloud/guides/debug-failing-tests",
      "heading": "See also",
      "heading_level": 2,
      "content_markdown": "## See also\n\n*   [Test Replay](/llm/markdown/cloud/features/test-replay.md) — replay the exact CI run with full debug capability\n*   [Recorded Runs](/llm/markdown/cloud/features/recorded-runs.md) — view, filter, and analyze every recorded run\n*   [Branch Review](/llm/markdown/cloud/features/branch-review.md) — compare branches to catch regressions before merge\n*   [Flaky Test Management](/llm/markdown/cloud/features/flaky-test-management.md) — detect, score, and fix flaky tests\n*   [Cypress AI](/llm/markdown/cloud/features/cypress-ai-features.md) — AI error summaries, test intent, and more\n*   [Cloud MCP](/llm/markdown/cloud/integrations/cloud-mcp.md) — debug from your AI coding assistant\n*   [Test retries](/llm/markdown/app/guides/test-retries.md) — the mechanism behind flake detection\n*   [Set up Cypress Cloud](/llm/markdown/cloud/get-started/setup.md) — record your runs in CI\n*   [Cypress Cloud FAQ](/llm/markdown/cloud/faq.md#Debugging) — common debugging questions answered\n",
      "section": "cloud",
      "anchors": [
        "see-also"
      ],
      "path": "/llm/json/chunked/cloud/guides/debug-failing-tests.json",
      "token_estimate": 132
    }
  ]
}