Fallback baselines
Compare a new screenshot against an existing one so variants and A/B tests show real changes instead of appearing as brand new screenshots.
Argos compares a screenshot with the screenshot of the same name in the baseline build. When a name has no match, the screenshot is reported as added — there is nothing to compare it with.
That's the right default, but it gets in the way when a screenshot is really a variant of an existing one. The baseName option lets you list the names to compare against instead, in priority order.
The problem
Say you run an A/B test on your home page and capture each variant under its own name:
home.png # variant A, the page you already ship
home-variant-b.png # variant B, the one being testedThe first time variant B runs, home-variant-b.png doesn't exist in the baseline, so Argos reports it as added and you see no diff — even though what you actually want to review is how variant B differs from the page you ship.
Set fallback baselines
Pass an array to baseName. Argos tries each name in order and compares against the first one that exists in the baseline build:
await argosScreenshot(page, "home-variant-b", {
baseName: ["home-variant-b", "home"],
});cy.argosScreenshot("home-variant-b", {
baseName: ["home-variant-b", "home"],
});await argosScreenshot(page, "home-variant-b", {
baseName: ["home-variant-b", "home"],
});await argosScreenshot("home-variant-b", {
baseName: ["home-variant-b", "home"],
});With that in place:
Once variant B has a baseline of its own,
home-variant-b.pngis used — you review it against its own history.Until then, Argos falls back to
home.png, so the first build shows variant B as a change from variant A.
Other uses
Fallback baselines fit any case where a screenshot is a derivative of another one:
Feature flags — compare a flagged variant against the unflagged page.
Localizations — bootstrap a new locale from the default one.
Renames — keep history across a rename by falling back to the old name.
How the comparison is reported
A screenshot compared against a fallback shows the mapping in the snapshot metadata on the build page, for example home-variant-b.png → home.png, so it's clear which baseline was used.
A baseline reached through a fallback is not reported as removed, even when no screenshot in the build carries its name.
Single-name override
baseName also accepts a single string, which always compares against that name:
Without an SDK
If you generate screenshot metadata yourself, set transient.baseName:
Names include the file extension here, and the project prefix if you use Playwright projects (e.g. chromium/home.png).
Last updated
Was this helpful?