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 1920x1080 page A device preset (mobile, tablet, iPhone 15, ... from list_devices) or a size name (desktop-md, desktop-xl, ...). See Devices below
waitFor number or string No — Wait after page load: number = ms delay, string = CSS selector. For i18n or deferred rendering.

Devices

device resolves in this order:

  1. A device preset (any case): full emulation, with the device's user agent, touch, pixel ratio and size. Since 20.0, mobile, tablet and desktop mean the device presets here too (393x852, 834x1194 and 1920x1080), not just a page size.
  2. A size name such as desktop-md (1440x900) or desktop-xl (2560x1440): the page size only. desktop-lg is 1920x1080; it was 2560x1440 before 20.0, so use desktop-xl for that size.
  3. Anything else is an error that names the closest presets and lists the size names. Before 20.0 an unknown name fell through to a desktop render.

Without device, the baseline renders at 1920x1080. The baseline records its device and the size it rendered, and visual_regression renders the page the same way when it compares. Baselines saved before 20.0 keep comparing at 1920x1080.

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

Smart baselines have no CLI command; they are this MCP tool. The CLI has two other kinds of baseline: visual save keeps one plain screenshot, and ai-visual capture keeps an AI-analyzed one.

cbrowser visual save homepage \
  --url "https://example.com"
cbrowser ai-visual capture \
  https://example.com --name homepage

From the Blog