Hide data that changes

A screenshot containing a clock, a live total or a random avatar reports a difference every time you run --check. This guide gives you three ways to stop that.

They are not a sequence to work through. Choose by one question — does the region belong in the published screenshot?

• No, it should not be seen — a customer's name, a face, a real balance. Paint over it with mask.
• Yes, a reader needs it — a chart, a result, a total the documentation is about. Keep it and excuse it with check.ignore.
• Nothing in the image holds still — turn the comparison off with check: false, knowing what that gives up.

One more thing decides whether you need any of them: size. A region that differs on every capture only fails the check if it exceeds check.threshold. A ticking clock in a large screenshot often sits under it and never reports anything.

Option 1: paint over the region

Use mask when the changing value does not need to be in the picture. Each entry is a query, and the region is painted over before the callouts are drawn:

name: dashboard
install: guide

clip: { css: '.panel' }

mask:
  - { within: clip, css: '.updated-at' }
  - { css: '.avatar' }

A mask covers every element its query matches, not the first — a page has three avatars far more often than it has one. Add pick or nth when you mean a single element.

Key the mask on something stable

Match a class, a test id or a position, never the value you are hiding. { text: $42.00 } matches the figure today and nothing at all tomorrow, when it reads $51.00. The failure is loud — a mask matching nothing stops the run — but it is still a broken recipe.

mask:
  - { within: clip, css: span, nth: 2 }
  - { within: clip, child: 2 }
  - { rect: [172, 84, 52, 20] }

Option 2: keep the region visible, but out of the comparison

Use check.ignore when the changing value is the point of the screenshot — a result, a total, a generated identifier. The region is captured as it is, and only its contents are excused from the comparison:

name: roll-form
install: guide

clip: { css: '.card' }

check:
  ignore:
    - { css: 'output#result' }

Only the contents are excused, not the geometry. shotlist still reports a difference when:

• the region moves or changes size, because what it used to cover is compared again
• the query matches nothing at all, which fails the recipe outright

A result that skipped something says so — same roll-form (1 region not compared) — so a pass is never read as covering the whole image.

Option 3: turn the check off for that screenshot

Use check: false only when nothing in the image holds still:

name: activity-feed
install: guide

clip: { css: '.feed' }
check: false

This gives up more than it looks. The recipe is still taken, so it still fails if the page changes enough to break a query, but nothing about the image itself is checked.

Adjust the tolerances instead

If the noise is small and spread across the whole image rather than confined to a region, raise the limits in your configuration rather than excluding anything:

check:
  threshold: 0.002
  tolerance: 8

• threshold is the fraction of pixels that may differ before a screenshot counts as changed.
• tolerance is how far one color channel may move, out of 255, before a pixel counts as different.

A recipe can set both under its own check key.

Related

• Callouts and masks reference
• Recipe reference: check
• Why screenshots drift