Capturing & managing baselines – QA Proof Help Center Skip to main content

Capturing & managing baselines

4 min read Last updated: March 2026

A baseline is a saved screenshot of a page in its "approved" state. Every Visual Regression test compares the current live page against this baseline and reports any differences. Monitors run regression tests on a schedule, so the baseline is the foundation of all monitoring.

How baselines are captured

You don't capture baselines manually — the system does it for you in two situations:

  • When you create a new monitor. The first scheduled run (or your first manual Run click) calls POST /api/baselines, captures the page, and stores it. From then on, every subsequent run is a regression test against this stored baseline.
  • When you approve a regression result. If the system flags real changes that you accept (you actually redesigned the page on purpose), click Approve on the result. That re-captures a fresh baseline so future runs use the new state as the reference.

What gets stored alongside the screenshot

To make regression diffs reliable, each baseline saves more than just an image:

  • Screenshot (full-page JPEG) — the visual reference.
  • Page text — every visible string on the page. Used to detect text-only changes that don't affect rendering (a typo fix, a new sentence in a paragraph) — these are detected programmatically without involving AI.
  • CSS color tokens — extracted CSS custom properties (--primary, --accent) plus computed colors of buttons, links, headings. Used to catch palette-wide shifts that pixel diff alone might miss.
  • Session cookies from the capture — restored on every regression run so the page renders in the same A/B test variant / geo-personalisation bucket as when the baseline was taken.

Stability guardrails

The capture pipeline refuses to save a broken baseline. If 3 or more images on the page failed to load during capture, the API returns 503 CAPTURE_UNSTABLE and nothing is stored. This prevents the most common regression-monitor failure mode: a baseline with missing images that every future run flags as "color shifts" against the white rectangles where images should be.

If you see this error, wait 1–2 minutes (your site or CDN may be rate-limiting our scraper) and try again.

Updating a baseline

Two scenarios call for a fresh baseline:

You shipped intentional changes

The monitor's next run will report a regression because the page genuinely changed. Open the result, verify the changes are correct, and click Approve. The plugin captures a new baseline immediately and the regression count clears.

The original baseline was bad

If your first regression result looks suspicious — large unexplained "color shifts" you didn't make — the baseline itself may have been captured at a moment when something on your site was broken (slow images, mid-deploy, CDN purge). Open Monitors, find the affected monitor, click Recapture Baseline. The new baseline replaces the old one and future runs compare against the fresh state.

Where baselines live

Baselines are stored on QA Proof servers, keyed by a hash of the normalized URL. They're persisted across plugin updates and WP-Cron restarts. Deleting a monitor also deletes its baseline. There's no per-baseline storage limit on any plan — your monitor count is the cap.

Direct API

If you're managing baselines outside the WP plugin (e.g. from CI), the API endpoints are:

  • POST /api/baselines — capture and save a baseline. Body: { "pageUrl": "..." }.
  • GET /api/baselines — list every baseline in your account.
  • GET /api/baselines/:key — retrieve a specific baseline (returns the screenshot inline as a data URI).
  • DELETE /api/baselines/:key — remove a baseline.

See API docs for full details.