How Waldo syncs your branch information

The problem

When you are coding on a feature branch, your changes are not yet visible to the rest of your team. As such, you cannot safely update a test globally to accommodate the changes you are introducing. If you do, the updated test will very likely start breaking for any other developer on your team who depends on that particular test.

This is precisely why we have introduced branch support into Waldo: it is a way to scope the edits you make on tests to the branch they belong to.


To efficiently understand the structure of the branches in your repository, Waldo needs to have access to the git information relevant to your app. Specifically, Waldo must be able to:

  • associate each build you upload with a particular git branch and commit sha
  • read the git history for this specific commit sha
  • read the git merge history for your repository as a whole

Thus, in order to use branch support in Waldo, you must:

  • connect your GitHub account to Waldo with the latest set of permissions (see
  • grant access to the different git repositories you use to build your apps
  • use the latest available Waldo CLI, specifically v2.0.0 or higher

How it works

At its core, branch support relies heavily on how well Waldo understands your git workflow. It is conceptually fairly simple: when you upload a new build, Waldo needs to determine the set of prior builds that the new build supersedes, purely from the perspective of the git history. This enables Waldo to decide which baselines are compatible with the new build.

Since Waldo does not have access to your actual source code, it needs to make a few assumptions when inferring what other builds the new build supersedes:

  • Waldo assumes that the default branch for your git repository is protected against force push. In other words, Waldo assumes the following:
    • the git history of your default branch is immutable
    • you will only add commits to that branch
    • once a commit is added, it will never be removed
  • whenever you upload two builds to a particular branch, Waldo assumes that you upload them in order, meaning Waldo assumes that the changes from the second build will contain the changes from the first build

How to use it

Waldo branch support is still a beta feature and needs to be explicitly turned on for your account.

Once this feature is turned on, there is no specific action you need take from your side in order to use branch support: when you record or edit any given test from a run, Waldo will scope the changes to the given branch containing then, and will follow the history of the underlying commit until it gets merged to your repository’s default branch.