Introduction to TurboSnap

1. Check your preview.js file: you may have a global decorator configured that’s imported from an index or barrel file, which itself imports a bunch of other files. This can lead to all stories depending on a large swath of seemingly unrelated files.
   
   Whenever a global Storybook file changes, we run a complete build because global Storybook files can change how any story renders. If any of those files or their imports change, we will trace them as dependent changes. If the file changes are frequent, you can utilize --untraced on these files to help ensure you’re not triggering a complete rebuild each time the file changes.

2. Make sure you have a valid lockfile(s) available and that it’s in sync with your package.json. If a lockfile is missing or out ouf sync with package.json, we’ll have to re-test all stories when there are any changes to either file.

When there is more than one ancestor, TurboSnap needs to consider the possible changes triggered by either ancestor. This can lead to situations where we need to retest everything or more stories than you were expecting, even if your branch itself is simple.

Let’s take a look at an example to understand how a merge impacts the changes TurboSnap considers.

Suppose an update was made to preview.js on the feature-2 branch, causing TurboSnap to trigger a full rebuild on build F2.1. This is expected, since changes to preview.js require us to retest everything.

The changes from feature-2 are then merged into the main branch in build M.2, which now has ancestors from both sides of the merge - M.1 from main and F2.1 from feature-2. The diff between both these ancestors and M.2 contains the changes to preview.js, triggering a full rebuild.

Let’s say we want to update feature-1 to merge in the changes that were made on feature-2. When we merge the changes from main into feature-1 on build F1.2, we trigger another full rebuild. Similarly to the previous build, the diff between F1.2 and the ancestor builds (F1.1 and M.2) includes the change to preview.js that was introduced on feature-2 and merged in build M.2.

Since we don’t know if the baseline that gets calculated will be taken from F1.1 or M.2, we take from both sides which can lead to merges involving more updates than expected. For example, if it’s taken from F1.1, the baseline won’t have the changes from preview.js, and so could be affected. For this reason, we retest all stories in the union of git changes from both sides of a merge, and will do a full rebuild if the change triggers one.

This same logic applies even if the change doesn’t trigger a rebuild. If we were to imagine the change in F2.1 was a change to MyComponent.jsx, we can assume that MyComponent.stories.jsx would be tested in builds F2.1, M.2, and F1.2. While this is less impactful, it’s worth noting since this can make a noticeable difference if a lot of files were changed.

We treat rebases like merges in this regard, since we want to bring baselines across from both sides of the “merge”. This way, we don’t lose baselines that you’ve accepted.

Let’s take a look at an example to illustrate the logic behind why Chromatic takes an ancestor from each side of your rebase.

Suppose you were to make and accept some changes on Build F.1.

After you’re done making changes to your feature branch, you rebase the changes onto your main branch - essentially, rebasing Build F.2’s commit onto Build M.2’s commit. When you do this, those changes from Build F.1 are going to come over, so you likely want to bring the new baselines over, too. Otherwise, you’ll need to re-accept the changes every time you rebase a branch.

Since we take baselines from ancestor builds, this means that we need to use Build F.2 as an ancestor for Build M.2 in order to track the baseline correctly.

Since most folks want to preserve their branch’s baseline history, we do this as the default and have a flag available for anyone who wants to ignore the baselines for the last build on a branch (ignoreLastBuildOnBranch). Usually, you would only use this option in rare cases where you were doing the rebase in order to delete the baseline changes for the branch.

We use information about the branch from git, along with the last Chromatic build on the rebased/squashed branch, to determine the ancestor build for the missing commit.

• When you are rebasing a branch off your main branch, we can find the last build that ran on the branch before the rebase and use that as an ancestor build.
• When you’re squash/rebase merging, we can query GitHub, GitLab, or Bitbucket to find out the branch that was just merged, and again use the last build on the branch as an ancestor build.

TurboSnap traverses your git history in order to identify what files have been changed between commits. When you squash/rebase, TurboSnap is prevented from accurately computing the difference between the current commit and its ancestor builds.

This is because the last Chromatic build on your rebased/squashed branch will not have a matching commit in your git history. The previous commit is removed from your git history, leading TurboSnap to being unable to find the commit.

TurboSnap will search for a “replacement build” on the branch with a valid commit in the repo, and use the replacement to approximate the difference between the two commits alongside any visual changes.

Let’s take a look at an example to understand the ancestor selection logic TurboSnap uses when the commit tied to the previous build on the branch is no longer in your git history.

In this example, let’s say you’re working on feature-1. There are changes from feature-2 that were merged into main, so you rebase those changes onto your feature-1 branch on Build F1.3.

TurboSnap is attempting to find an ancestor build for each side of your rebase on Build F1.3. For the main branch, TurboSnap is able to find the commit belonging to Build M.2 since it is the commit rebased onto Build F1.3.

Things get a little more complicated when TurboSnap tries to locate the commit for the last build on feature branch (Build F1.2) - the commit no longer exists in your git history. TurboSnap then traverses your git history until a replacement build is found with a valid commit, which is Build M.1 in our example.