How do you customize Visual Diff Detection?

visual-diffvisualrecommended9 credits per run

Optional monitoring check for pages that should not change. Compares the current screenshot against the previous capture of the same URL and viewport; fails when a meaningful difference is detected so a human can confirm whether the change was intended. Requires a prior capture — the first run always passes. Best used on a recurring schedule.

When is a custom rule warranted?

Override `comparisonCriteria` when you know which parts of the page you actually care about, or which parts always move. Naming a region — "compare the pricing table and the header; ignore the testimonial carousel" — turns an unusable check into a usable one on pages that are partly dynamic. It is also the way to raise sensitivity where drift matters most, for example asking that any change to legal or price text be reported however small, while allowing photographic content to vary.

When should you stay on the Standard?

Stay on Standard for pages that are genuinely static, where the honest answer is "tell me about anything that moved". Keep the default when you are establishing a baseline across many pages at once and do not yet know which regions are volatile — run it broadly first, then write criteria only for the pages that prove noisy. If a page moves on every run no matter how you word the criteria, the right answer is usually to stop watching that page rather than to keep refining the sentence.

What are the trade-offs?

Every exclusion you write is a region that can now break silently, and exclusions tend to be written in a hurry after a noisy run — the carousel you ignored is also where the campaign's main call to action lives. Narrowing to named regions likewise means a change anywhere else goes unreported, which is the opposite of what a change detector is for. The more conditional your criteria, the more the verdict depends on interpretation, and the less two runs a month apart can be compared with confidence.

How is a custom rule governed?

The Standard criteria are written so the check means the same thing on any page without setup, which is what makes a series of results comparable over time. Custom criteria are a statement about one page's structure and belong with whoever owns that page, reviewed when the page is redesigned — criteria describing a layout that no longer exists will pass a broken page happily. Because this check's output is often used as evidence that a page did not change, record when the criteria were last edited: a comparison is only as trustworthy as the instruction behind it.

What does a configured rule look like?

A pricing page with a rotating customer-logo strip sets `comparisonCriteria` to compare the plan cards, prices and header while ignoring the logo strip, so the check stays quiet until a price moves. A regulated disclosure page raises sensitivity by asking that any difference in body or legal text be reported however minor, while allowing image re-compression to pass. A campaign landing page under active editing narrows the criteria to the hero headline, the form and the call to action, accepting that changes further down the page will not be reported until the campaign settles.

How does an agent call it with your config?

{
  "type": "url",
  "validations": [
    { "id": "visual-diff", "config": { /* your overrides */ } }
  ]
}

What can you configure?

comparisonCriteriarequirednon-blank-string

Standard default: Report any visually significant layout, branding, or content changes compared to the previous screenshot for this URL and viewport.

Author ArbiterQA · Reviewed by ArbiterQA · 2026-08-14

Appears in

Related

Run this check on your own assets

1,000 credits a month on the free plan. No card.