๐ŸŒณ Branches

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 / Bitbucket / GitLab account to Waldo with the latest set of permissions (see https://app.waldo.com/settings/integrations)
  • 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

Branch status

When you go to your builds page, you can see a label attached to each of your builds.
It is also everywhere else in the product where you are acting on a specific build. It gives you the status of the commit that was used to generate this build, and how it is now considered by Waldo.

no git metadata was sent from CI
not sufficient branch information
edits made on this build are going to be scoped to this branch
edits made on this build are going to be applied globally

Until at least one of your builds show as blue or purple, your application is not yet configured to use the branch feature.

Whatโ€™s Next