Baselines

A baseline is the reference screenshot Vizzly compares your new builds against. It’s the “before” image in a before-and-after comparison.

How Baseline Matching Works

Vizzly matches screenshots between builds using a signature that includes:

• Screenshot name
• Viewport width
• Browser (if provided)

For example: homepage|1920|chromium

If any part changes, Vizzly treats it as a different screenshot. You’ll see it marked as “new” or “missing” instead of “changed”.

Baseline Signature Properties

You can extend the signature to include custom properties. This creates separate baselines for variants of the same screenshot.

When you need this:

• Themes: dashboard with theme: dark and theme: light
• Devices: checkout on device: mobile vs device: desktop
• Locales: homepage in locale: en-US vs locale: fr-FR

Setup:

1. Go to Project Settings
2. Find Baseline Signature Properties
3. Add the property names (e.g., theme, device)
4. Save

How it works:

Without theme configured, the signature only uses name, viewport, and browser:

dashboard|1920|chromium  (theme metadata: dark)
dashboard|1920|chromium  (theme metadata: light) ← Same signature, overwrites

With theme added to baseline signature properties, it becomes part of the identity:

dashboard|1920|chromium|dark   → separate baseline
dashboard|1920|chromium|light  → separate baseline

Properties vs Baseline Signature Properties:

Baseline Selection Modes

Vizzly has three modes for selecting baselines. Each fits different workflows.

Git Mode (Recommended)

Git mode uses your Git history to find the right baseline automatically.

How it works:

When processing a build, Vizzly:

1. Checks if the SDK/CLI provided a common_ancestor_sha (merge base)
2. If not, tries to find it via GitHub API (if GitHub integration is active)
3. Falls back to local git to calculate the merge base
4. Looks for a completed build at that SHA on your baseline branch with allowed approval status
5. If no build exists at the merge base, uses the latest completed build with allowed approval status on the baseline branch
6. If the baseline branch has no such builds, falls back to the latest completed build with allowed approval status on the current branch

Branch behavior:

• Feature branches: Compare against eligible builds on your baseline branch (usually main)
• Baseline branch builds: Compare against the previous eligible build on the same branch

“Eligible” means a completed build that meets your baseline approval requirements (approved by default).

When to use:

• Pull request workflows
• Teams that want baselines to automatically advance as changes get approved
• CI environments with GitHub integration

Setup:

1. Go to Project Settings → Baseline
2. Select Git mode
3. Set your baseline branch (e.g., main, develop)
4. Save

Manual Branch Mode

Manual Branch mode lets you set a different baseline for each branch.

How it works:

• You manually mark one build per branch as the baseline
• Builds on each branch compare only against that branch’s marked baseline
• If a branch has no marked baseline, all screenshots appear as “new”

When to use:

• Long-lived feature branches
• Parallel release trains (e.g., v1.x and v2.x branches)
• Cases where each branch needs its own independent reference point

Setup:

1. Navigate to a completed, approved build on the branch
2. Click Set Baseline in the build header
3. Repeat for other branches as needed

Manual Mode

Manual mode uses one fixed baseline across all branches.

How it works:

• You manually mark one build as the baseline
• All builds on all branches compare against this single baseline
• The baseline stays fixed until you change it

When to use:

• Design-locked periods where you want a frozen reference point
• Marketing campaigns requiring strict visual consistency
• Any time you need predictable comparisons regardless of Git activity

Setup:

1. Navigate to the completed, approved build you want as your baseline
2. Click Set Baseline in the build header
3. All future builds will compare against it

Changing the baseline:

To change it, click Unmark Baseline on the current baseline, then Set Baseline on a different build.

Baseline Approval Requirements

By default, only approved builds can be selected as baselines. You can configure which approval statuses are eligible:

• Approved: Only approved builds (default, recommended)
• Approved + Pending: Include builds that haven’t been reviewed yet
• Approved + Pending + Rejected: Include all builds regardless of status

This setting applies across all baseline modes. When Git mode searches for a baseline at a specific commit, it only considers builds with allowed approval statuses.

Configure in: Project Settings → Baseline Allowed Approval Statuses

See Build Settings for auto-approval options.

Common Issues

Can’t Mark a Build as Baseline

Requirements to mark a build as baseline:

• Build status is completed (processing must be finished)
• Build meets your baseline approval requirements
• You’re signed in as a user (API tokens cannot mark baselines)
• You have project admin access

Common reasons this fails:

• Build is still processing or failed
• Your baseline approval settings require the build to be approved first
• You’re using an API token instead of being signed in
• You don’t have admin access to the project

No Baseline Found in Git Mode

Git mode needs at least one build with an allowed approval status as a reference.

Check:

• Your baseline branch has at least one build that meets your approval requirements
• Your baseline branch setting matches your actual Git branch name (case-sensitive)
• Your baseline approval requirements aren’t too restrictive (default is approved-only)
• If you just created the project, you need to approve at least one build on your baseline branch first

Unexpected Baseline Selection

Check:

• Your baseline approval requirements in project settings
• For Git mode: verify your baseline branch setting
• For Manual/Manual Branch modes: which builds are currently marked as baseline

Next Steps

• Build Settings - Configure auto-approval and baseline approval requirements
• GitHub Integration - Improve Git mode accuracy with GitHub
• Team Management - Set up review processes for baselines