What you'll learn
- What Test Replay is and why you should use it
- How to get started with Test Replay in Cypress Cloud
- How to debug failed and flaky CI test runs more accurately and efficiently
Test Replay is available when recording tests to Cypress Cloud using Cypress
v13 and up. See the Cypress v13 changelog.
Test Replay currently supports Chromium-based browsers (Chrome, Edge, Electron) only.
What Is Test Replay?
Test Replay vs Screenshots and Videos
v13, test failures in CI have historically been captured through screenshots, videos, and stack trace outputs, but these artifacts provide limited information. Developers often need more context to understand the root cause of failures, requiring them to reproduce the issue locally, which may not always be possible due to environmental or network conditions. This knowledge gap between test failures and debugging capabilities leads to increased debugging time and potentially deploying unresolved bugs to production.
How Does Test Replay Advance Your Workflow?
Test Replay complements the existing visual artifacts provided by Cypress Cloud. It eliminates the need for local test replication by enabling developers to time-travel to the exact moment of test failure. Developers gain access to previously inaccessible details and feedback loops, enabling faster and more accurate debugging, and instilling confidence in handling test failures in CI. Replacing video recordings with Test Replay provides a superior debugging experience that is sharable and supports team collaboration with efficient workflows.
Test Replay is available to all Cypress Cloud plans at no additional cost, subject to usage limits.
To get started with Cypress Cloud, sign up for our free plan.
Free plans allow 3 users and 500 monthly test results, while exceeding this limit requires upgrading the plan. Please see our pricing page for more details.
Test Replay is automatically enabled when updating to
v13 of Cypress. If desired, an opt-out is provided through project-level settings. Learn about what this means for capturing video of test failure in Cypress Cloud under "See also" below.
All you need to do after recording test runs is log in to your Cypress Cloud account and leverage these new debugging capabilities. No additional software, configuration or changes to the existing test recording process is required. For example, you do not need to edit your Cypress configuration file or pass any flags or new commands when recording via the command line in order to enable or use Test Replay.
Accessing Test Replay
Accessing the replay of your test is as simple as reviewing any other test artifact in Cypress Cloud.
Hover on a test for review under the Latest Runs Overview.
Or navigate to the test detail sidebar header or above each attempt in the errors panel. The header option will replay the first failing test while the option above each attempt will replay the affiliated test.
Debugging With Test Replay
Both options above display the Test Replay interface, which we'll unpack from top to bottom in more detail below.
The left side of the header displays the Cypress Cloud test run ID number (#), with the Git branch name along with the spec, platform and browser information. Hovering on this exposes additional test meta data.
Dive into network-level traffic, console events and inspect the application under test just as you can in the browser.
Toggle each test attempt, play back errors at a variety of speeds or scrub through the captured error by dragging the playhead along the timeline.
Opt-out of Test Replay
If you do not want to capture test data for replay and debugging purposes, simply "shut off" Test Replay in project settings.
If Test Replay is not present or disabled in Cypress Cloud:
- Confirm runs have been recorded to Cypress Cloud using Cypress
- Ensure tests were recorded using a Chromium-based browser (Chrome, Edge, Electron).
- Check that Test Replay is enabled in Cypress Cloud project settings.
- Review the standard output of the test run to ensure there was not an error capturing Test Replay. If you encounter an error capturing Test Replay, please open an issue so that we can investigate.
CentOS users may experience errors when using Test Replay
CentOS Linux 7 has an end of life in 2024. We have had these users report issues when accessing Test Replay in Cypress Cloud. This could be due to GCC version compatibility with better-sqlite3. We recommend using CentOS 8 rather than 7, or try following the steps noted in this installing better-sqlite3 on Centos 7 Github Issue.
Safari 16.3 and under users may experience errors when viewing Test Replay
Cypress Cloud relies on certain web APIs implemented by specific browsers. Safari versions older than 16.4 may be missing certain APIs required for rendering Test Replay. To view Test Replay in Safari, version 16.4 and above may be used. This does not affect running tests or recording to Cypress Cloud.
Runner UI Notes
The Cypress Test Runner "Runner UI" is made up of the powerful command log which displays every command executed in your spec. The UI also includes the URL bar, browser selector, and the viewport size control above the application under test.
The Runner UI is visible during
cypress open mode, but is also rendered (headless-ly) during
cypress run so that it displays within captured screenshots or videos, to assist in debugging CI failures.
Rendering the Runner UI while running tests via
cypress run often has performance implications, resulting in a slower test runtime, especially on lower resourced machines.
With Test Replay, Cypress Cloud regenerates the entire UI for viewing the run and debugging CI failures. Additionally, displaying the Cypress command log in videos and screenshots is less valuable for users using Test Replay.
Therefore, as of Cypress
v13, the Runner UI is no longer rendered during
cypress run for users using Test Replay, with an option to opt-out of this behavior.
If you'd like to render the Runner UI, you can turn on this behavior by passing
--runner-ui as a CLI flag. You may encounter a slower performance when turning this on, especially in lower resourced machines. Learn more about the
--runner-ui command line option.