How to Manage Visual Testing Baselines and Branches

A visual testing baseline is an approved screenshot used as the reference for later comparisons. To manage baselines across branches, first identify how your tool chooses that reference, then review visual changes before accepting them, regularly sync feature branches with the integration branch, and keep screenshot rendering consistent.

Branch behavior differs by tool. Playwright stores reference images in your repository. Chromatic UI Tests maintain accepted baselines per branch, while Chromatic UI Review compares branch snapshots from a Git merge base. Percy Git selects a base-branch build from Git history and approves or rejects a whole build; Percy Visual Git stores approved snapshots on branchlines. These are different workflows, so choose one that fits your repository, CI, and review process.

1. Decide what a baseline means for your team

A baseline is not simply the last screenshot generated. It is the reference state your team has approved. Updating it changes what future runs consider correct, so baseline updates should be reviewed as code changes are.

Repository snapshots: Reference images live beside tests and are committed and reviewed with the code. Playwright supports this approach.
Build-level approval: A hosted service compares a build with a base build, and reviewers accept or reject the build as a whole. Percy Git uses this model.
Snapshot-level approval: Reviewers accept individual snapshots stored in branchlines. Percy Visual Git uses this model.
Branch baselines: Accepted snapshots are associated with branches, with tool-specific inheritance and synchronization rules. Chromatic UI Tests use branch baselines.

Before adopting a workflow, write down who can approve a change, whether approval applies to an entire build or individual images, where references are stored, and how a feature branch gets updates from the base branch.

2. Create a known-good first baseline

Choose a stable application revision and verify its UI manually or with your existing functional checks.
Run visual tests in a documented environment. Record the browser and version, operating system or container, viewport, fonts, locale, timezone, test data, and relevant rendering settings.
Generate reference images once, inspect them, and commit or accept only the intended state.
Run the same visual tests again without changing the application. Resolve unexplained differences before relying on the baseline.

Playwright notes that rendering can vary with operating system, browser version and settings, hardware, power source, and headless mode. Its guidance is to use the same environment that generated the reference screenshots and to commit and review snapshot files. In practice, also control inputs that affect your application, such as data, fonts, viewport, animations, and network-dependent content.

3. Understand branch selection before updating snapshots

Playwright: reference files in version control

Playwright screenshot references are stored in a snapshot directory next to the tests. The repository history determines which reference a branch checks out. After intentionally changing the UI, update the snapshots in that branch, inspect the image changes, and commit them with the code change. Do not regenerate references just to make a failing comparison pass: first determine whether the difference is expected.

# Run visual tests
npx playwright test

# After reviewing an intentional visual change, update snapshots
npx playwright test --update-snapshots

Commit the resulting snapshot files and review them in the pull request. Run tests in the same browser and host environment used to create the references so environment changes do not look like application changes. See the Playwright visual comparisons documentation.

Chromatic: branch baselines and UI Review

Chromatic UI Tests use accepted baselines associated with a branch. A new branch inherits from its branch point, then maintains its own baseline. An accepted update on one branch does not automatically update every other feature branch. A long-lived branch can therefore report a difference for a change already accepted on the integration branch.

Chromatic UI Review is a separate comparison flow: it compares snapshots from two branches using their Git merge base rather than using the same baseline method as UI Tests. Its review flow needs builds on both the head and base branches to produce a changeset. Be clear about which Chromatic workflow your project uses before interpreting a diff.

When branch merges produce multiple candidate snapshots, Chromatic generally selects the most recently approved change. Its preferMergedBaselines option can make accepted baselines from an incoming integration branch take precedence in certain sync situations; it uses the baseline from the last sync point. A branch that is far behind should be synced first. After rebases, squash merges, or history rewrites, run Chromatic again and verify that it selected the intended baseline. Chromatic documents recovery and selection options for cases where Git history and stored baseline history diverge. See Chromatic’s branches, baselines, and Git history guide and its documentation.

Percy: choose Git or Visual Git

Mode	How the reference is selected	Approval unit	Branch workflow
Percy Git	Finds a base-branch build from Git commit history.	Complete build	Useful when CI builds and pull request approval follow Git ancestry.
Percy Visual Git	Uses approved snapshots stored on branchlines.	Individual snapshots	Teams can sync snapshots from a central baseline or merge branchline snapshots into it.

Decide whether reviewers should approve a complete build together or resolve individual images. In Visual Git, understand the distinction between syncing snapshots from the baseline into a branchline and merging branchline snapshots into the baseline. See BrowserStack’s Percy baseline management guide and Visual Git documentation.

4. Keep feature branch baselines current

Run visual builds on the base or integration branch when your tool’s comparison or review flow needs them.
Periodically merge or rebase the latest base branch into a long-lived feature branch.
Run the visual suite in the stable environment and inspect every changed image.
Separate changes already accepted upstream from changes introduced by your feature.
Approve only intentional UI changes. Investigate unexpected differences before changing a reference.
After a merge, rebase, squash merge, or history rewrite, confirm which build or snapshot the tool selected as the reference.

For Chromatic, branch baselines do not automatically propagate across other branches when a change lands. Syncing regularly limits stale comparisons. For Percy, follow the selected Git or Visual Git model: their reference and approval behavior differ. For repository snapshots, merging the base branch brings its committed reference files into the feature branch, subject to ordinary Git conflict resolution.

5. Review a visual change safely

For each diff, ask:

Is the changed region part of the feature or design change being reviewed?
Does the actual screenshot show a real product change, or did rendering, data, fonts, or network state shift?
Are unchanged areas stable across a repeat run?
Does the proposed baseline update include only intended files or snapshots?
Has the relevant base branch build or snapshot been produced if the tool needs it?

Accept intentional changes and record the reason in the pull request or review. Reject or investigate unexpected changes. Make baseline refresh a deliberate review action rather than an automatic response to every diff.

6. Stabilize screenshot rendering

Rendering consistency makes diffs easier to interpret. Keep the following inputs stable where they affect your application:

Browser engine, version, and launch settings.
Operating system or container image, fonts, and rendering dependencies.
Viewport size, device scale factor, and color scheme.
Locale, timezone, and deterministic test data.
Animations, clocks, and asynchronous content.
Network responses and third-party content that appears in the captured page.

These are practical controls for reproducibility; their exact implementation depends on your app and test runner. Keep the environment configuration in code or CI configuration so local and CI runs can use the same setup. If a visual test is flaky, identify whether the app state or rendering environment is changing before updating its baseline.

7. Choose a workflow that matches your review process

Approach	Good fit when	Trade-off to plan for
Playwright snapshots	You want reference images in the repository and code review to cover baseline changes.	Keep the image-generation environment consistent with the environment used to create references.
Percy Git	Visual tests run in CI and approval should apply to a build associated with Git history.	The approval unit is the whole build.
Percy Visual Git	Tests run independently of commit-based CI, or reviewers need per-snapshot approval.	Team members must understand branchlines and sync or merge actions.
Chromatic UI Tests or UI Review	You use Chromatic’s branch-aware baselines or its separate branch comparison flow.	Know which flow is active and how branch syncs and rewritten history affect selection.

There is no universally best model in the documented workflows. Choose based on repository versus hosted reference storage, whole-build versus snapshot approval, reliance on Git ancestry, and whether reviewers need a baseline comparison or a merge-base changeset.

8. Troubleshooting common baseline problems

Symptom	Likely cause	What to do
Many unrelated pixels differ on CI	Browser, host OS, fonts, rendering settings, or headless mode differs from the reference environment.	Use the same environment used to generate the baseline and verify the browser version and settings.
A feature branch shows a change already accepted on the base branch	The branch has a stale independent baseline or snapshot set.	Merge or rebase the latest integration branch, rerun visual tests, and review the resulting diff.
Chromatic selected an unexpected reference after a merge	Multiple accepted snapshots, sync-point state, or rewritten Git history may affect selection.	Sync a substantially behind branch, inspect the selected baseline, and rerun Chromatic after a history rewrite. Check whether `preferMergedBaselines` fits the desired sync behavior.
Percy is asking for one decision on many screenshots	The project is using Percy Git, which approves or rejects a complete build.	If individual snapshot approvals are required, assess whether Percy Visual Git fits the workflow.
A Percy Visual Git branch does not include an accepted central change	The branchline has not been synced from the baseline.	Use the documented sync action, then review the updated snapshots.
Snapshot update causes a large unexplained diff	References were regenerated after an environment or test-data change, or an automatic refresh obscured the actual change.	Restore the prior references if needed, stabilize inputs, rerun, and accept only explained visual changes.
Chromatic UI Review has no changeset	A build may be missing on the head or base branch.	Produce builds on both relevant branches and check the UI Review workflow configuration.

9. Performance, reliability, and cost considerations

Baseline management adds work when branches live for a long time, visual suites cover many screens, or reviews produce noisy diffs. Frequent integration keeps branch comparisons closer to the current product state. Stable rendering environments reduce reruns caused by unrelated visual variation. Keep only useful, reviewable reference images and make update ownership explicit.

The dossier does not establish comparative runtime, pricing, uptime, or reliability measurements for Playwright, Chromatic, or Percy, so those should be evaluated against current vendor terms and your own suite. For self-managed snapshots, account for repository storage and CI execution. For hosted workflows, check current plan limits, retention, and billing directly with the provider before selecting a plan.

Or skip the browser setup

If a task is to capture a page as an artifact for review, documentation, or an AI workflow, ScreenshotNeo can return a screenshot from one GET request. The baseline approval process still belongs in your visual testing tool; ScreenshotNeo handles page capture.

ScreenshotNeo is a website screenshot API and MCP server. Its capture flow accepts cookie and consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before the shot; each step can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and the response identifies the page verdict and billing status in headers. Its MCP tools let AI agents take screenshots, get page information, and capture PDFs. The API supports PNG, JPEG, WebP, and PDF, with options for full-page or selector capture, viewport and device settings, custom CSS or JavaScript, wait conditions, request blocking, and more.

Example using cURL:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python:

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

Node.js:

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', res);

See the ScreenshotNeo API documentation for request options and response headers. Cookie banners, popups, and chat widgets are removed before the shot; bot checks, blank pages, and failed loads are never billed; an MCP server lets AI agents take screenshots; and 1,000 screenshots a month are free with no card, with paid plans starting at $5 for 3,000.

FAQ

Should a pull request automatically update its visual baselines?

Usually, baseline acceptance should follow review. Automatic updates can hide whether a difference was intentional. Use the approval process of your tool and inspect the images before accepting them.

Does merging a change update every feature branch’s baseline?

No. Chromatic’s accepted branch baselines do not automatically propagate to every other branch. Repository snapshots and Percy modes also follow their own reference workflows. Sync branches and verify the selected reference.

Can I compare branches without maintaining a baseline?

Chromatic UI Review compares branch snapshots from a Git merge base and does not use the same baseline method as Chromatic UI Tests. Check your selected tool’s current workflow documentation for equivalent options.

What should I do when a baseline changes after a rebase?

Run the visual tool again and confirm the chosen reference matches the intended history. This is especially important when the tool stores accepted history separately from Git commits.