Back to docs

Tool Visual Baseline

Category: Visual Testing · Tier: All

Capture a visual baseline using the Wasserstein barycenter. Takes multiple screenshots, rejects outliers, and computes an optimal consensus reference. Sets an adaptive threshold. Robust to dynamic content, animations, and timing jitter.

Parameters

Parameter Type Required Default Description
url string Yes — URL to capture
name string Yes — Baseline name for future comparison
captures number No 3 Number of screenshots (more = more robust, slower)
delay number No 1500 Delay between captures in ms
selector string No — CSS selector to capture specific element
device string No — Device emulation (mobile, tablet, iphone-15, etc.)
waitFor number or string No — Wait after page load: number = ms delay, string = CSS selector. For i18n or deferred rendering.

Examples

Capture a baseline of our homepage

Capture a baseline with 5 screenshots for extra robustness

Capture a baseline of the hero section on mobile

How It Works

  1. Capture -- Takes N screenshots (default 3) with configurable delays
  2. Histogram -- Computes per-channel CIE-Lab color histograms for each capture
  3. Barycenter -- Computes the Wasserstein barycenter (optimal "average" distribution)
  4. Outlier Rejection -- Captures beyond 2 sigma are excluded (dynamic content, animations, timing noise)
  5. Reference Selection -- The capture closest to the barycenter becomes the reference
  6. Adaptive Threshold -- Threshold derives from observed variance. Stable pages get tight values (~0.98). Dynamic pages get looser ones (~0.80). No manual tuning needed.

Response

{
  "name": "homepage",
  "captures": 3,
  "outliers": 0,
  "meanDistance": 0.0023,
  "adaptiveThreshold": 0.94,
  "reference": "/path/to/median-reference.png",
  "computeTime": "420ms"
}

Why Wasserstein?

Traditional baselines use a single screenshot. This causes false positives from:

  • Dynamic content (timestamps, ads, user counts)
  • Animation state timing
  • Font rendering differences between runs
  • Browser anti-aliasing randomness

The Wasserstein barycenter solves all of these. It computes the optimal consensus distribution -- the "typical" rendering -- with outlier rejection.

Mathematical Foundation

The Wasserstein barycenter is the Frechet mean in Wasserstein space. It minimizes the sum of Wasserstein distances to all input measures. For 1D marginals (color channels), this equals averaging the quantile functions. This gives the exact Wasserstein-1 barycenter in closed form.

Based on Agueh & Carlier (SIAM 2011).

CLI

cbrowser visual save homepage --url "https://example.com"
cbrowser smart-baseline capture "https://example.com" --name homepage --captures 5

Related

From the Blog