Branch Review
What you'll learn​
- How Branch Review helps you catch regressions before a Pull Request merges
- How to compare test results between branches in Cypress Cloud
- How Branch Review surfaces the impact of Pull Requests on your test suite
- How to compare any two runs, if not using a Pull Request workflow
- Best practices for grouping test runs
Why Branch Review​
Every Pull Request changes your application, and your test suite along with it. The critical question before merging is: did this change make things better or worse? Answering it manually means hunting through two separate sets of runs, eyeballing pass/fail counts, and guessing whether a failure is new or pre-existing. It's slow, error-prone, and easy to skip under deadline pressure.
Branch Review answers what changed and why in a single view, so you can:
- Catch regressions before they merge. Instantly see new failures introduced by a branch instead of discovering them after they reach
main. - Stop chasing pre-existing flake. Distinguish problems your PR introduced from noise that was already there, so reviewers spend time on what actually changed.
- Confirm coverage moved in the right direction. See tests that were added or modified, and (if enabled) how UI Coverage and Cypress Accessibility shifted between the two branches.
- Review with confidence. Give reviewers and authors a shared, objective picture of a PR's impact, turning "looks fine to me" into a verifiable comparison.
Branch Review is valuable even if you don't have a Pull Request workflow, because it allows you to compare any two runs of your choice. These might represent different builds of the application, changes in test code, or results from nightly runs.
Example: reviewing a Pull Request​
A typical review of an incoming Pull Request looks like this:
- Open Branch Review for the PR. This path requires VCS integration with pull request comments enabled. From the Cypress comment on the Pull Request, click "View all changes introduced in this branch" to land in Branch Review with the PR's latest run pre-selected as the Changed run.
- Scan the status tabs. Check the Failures and Flaky tabs for anything marked new. These are the tests your branch impacted, as opposed to problems that already existed on the base branch.
- Drill into a new failure. Open the test to see the base branch (passing) and feature branch (failing) results side by side, then use Test Replay and the code diff to understand exactly what your change broke.
- Confirm coverage moved the right way. Review the Added and Modified tabs, plus any UI Coverage or Cypress Accessibility changes, to verify the PR improved, rather than regressed, quality.
- Merge with confidence, or push a fix and re-review once the new run records.
Get started​
The key to the Branch Review area is a comparison between a base run and a changed run. The changed run is the main subject of the comparison, often associated with an incoming Pull Request. The base run is the starting point for comparison.
There are a number of ways to get to Branch Review depending on where you are looking at your Cypress results. In all cases, once you've picked a Changed run, you can adjust the automatically-selected base run to any branch or run in the project to dial in the comparison you are most interested in.
From the project list​
The project card shows three active branches for the project. You can click on any of these to enter Branch Review focused on that branch.
From the main navigation​
When a project is open, select "Branches" in the main navigation to see a full, filterable list of available branches and choose one to set as the source of the Changed run.
From the run overview page​
Click the branch name associated with the run. This will take you to Branch Review with that run pre-selected as the Changed run. This is a great way to investigate a specific run with an unexpected outcome in the tests.
From a Pull Request​
Click the "View all changes introduced in this branch" link at the bottom of the Test Results table. You will enter branch review with the current PR's branch and latest run pre-selected as the Changed run.
Integrating with Pull Requests​
Pull Requests in Branch Review work by leveraging the Cypress Cloud GitHub integration to query the GitHub API for branches with Pull Requests. Your project will first need to be connected to a GitHub repository. If you haven't already, follow the steps in Install the Cypress GitHub app to connect your project to GitHub.
When Pull Requests are connected, you'll be able to select runs by the associated PR:
Note: If you do not see PR # tags associated with a branch, you may need to pass PR numbers to runs as environment variables. This helps ensure Cypress Cloud can map PR data correctly.
Latest Runs​
If the selected branch has a PR associated and a PR # passed via CI, there is an additional callout on the top of the overview tab of the Latest runs page which directs to the Branch Review.
Branch Details​
The selected run includes the Git commit message, PR selector, PR status, and base and feature branch labels with the Cypress Cloud test run number.
If there are multiple Pull Requests open for the same branch, you can select the Pull Request you want to review from the dropdown to the right of the commit message.
Clicking the branch label will link you directly to the appropriate run overview and hovering on these elements exposes additional run meta data.
Review Test Status​
Note: Recording exactly one run for every commit is the best way to ensure complete and accurate comparisons. See our best practices on grouping multiple cypress run calls under one run.
When on the review screen, you will see the Failures, Flaky, Pending, Added, and Modified tabs. Each tab will show you the specs that fall into that category. You can click on a test to view the test details.
The numbered callouts above correspond to:
| # | Description |
|---|---|
| 1 | Details of which branches and runs are compared. If a Pull Request is detected, Pull Request details will be here. |
| 2 | Links to key differences in test information like new failures and flaky tests. Note that all numbers and scores refer to the Changed run. |
| 3 | UI Coverage changes. |
| 4 | Cypress Accessibility changes. |
| 5 | What has changed in the status you have opened, shown with the count indicators below. |
| 6 | The test state (failed, flaky, pending) at the spec level, described below. |
Count indicators show how a status shifted in your branch:
| Indicator | Meaning |
|---|---|
 | Total number introduced in your branch |
 | Total number decreased or resolved in your branch |
 | Total count, for example, 3 new and 1 existing |
Test states indicate how a spec's result compares to the base run:
| State | Meaning |
|---|---|
| new | The state was not previously captured, but now is (newly pending tests can imply an it.skip() was not removed). |
| existing | The state was previously captured and now is still captured. |
| resolved | The state was previously captured but now is no longer captured. |
Review Test Comparison​
Navigating into the test detail view reveals a side-by-side comparison of the test results on both branches, along with artifacts so you can compare before vs. after your PR. Pairing the failure on your branch with the passing result on the base branch, along with Test Replay, screenshots, and videos for each attempt, lets you pinpoint exactly what your change broke without re-running anything locally. This narrows the focus to changes introduced or resolved on either branch and helps surface the source of flake across different attempts. Review the test definition panel for diff snapshots to quickly determine changes in test code.
The numbered callouts above correspond to:
| # | Description |
|---|---|
| 1 | Base branch results |
| 2 | Feature branch results |
| 3 | Test Replay and artifacts |
| 4 | Test attempts (descending order) |
| 5 | Code change diffs |
Troubleshooting​
Note on Available Data for Pull Requests​
Branch Review is a powerful tool to compare two branches with recorded runs to Cypress Cloud. There are factors that can impact what is available to review between a feature and base branch. For example, whether or not a branch at a particular commit has a run recorded to Cypress Cloud will affect what is displayed.
The following captures this scenario across both branches:
| Base Branch | Feature Branch | What Branch Review Displays |
|---|---|---|
| has run | has run | Comparison data using both found runs |
| has run | no run | Comparison data using last run on feature branch |
| no run | has run | Non-comparison data with found feature run |
| no run | no run | Non-comparison data using last run on feature branch |
If the required runs for comparison are not available, you can use the manual selection dropdowns to compare two suitable runs, if they exist in Cypress Cloud.
Best Practices​
Grouping Test Runs​
Cypress Cloud allows for grouping recorded tests together under a single run. This means multiple cypress run calls can be labeled and associated to a single run in Cypress Cloud.
Recording multiple test runs per commit without grouping will cause issues, as Branch Review relies on the latest run. Therefore, recording one run per commit and utilizing grouping is essential to improving effectiveness and ensure an accurate comparison between branches.
Missing Runs in Pull Request Comparisons​
If a run is missing on either the merge base or feature commit of the PR, a banner is displayed specifying which commit is missing the run with a link to it on GitHub.
See Also​
- Read about multi-repo implementation best practices in Cypress Cloud. Even if your test code and application code are not colocated, you may be able to connect your test runs to specific commits and pull requests in your application.