skip_area masks what exists NOW — surface selectors that never match

[pftg]

Follow-up to #272, raised by the maintainer: removing the implicit wait fixed a measured 44% of a suite, but that wait was doing a second job by accident.

The risk the fix created

A skip_area mask is only correct if the element exists when the mask is computed. Capybara's minimum: 1 default meant a not-yet-present element got up to 5s to appear. With minimum: 0, a lazy-loaded image that has not arrived yields an empty mask — nothing is excluded, the unstable region is compared, and the test flakes.

At risk: lazy-loaded images below the fold (skip_area: ["article img"]), JS-injected widgets and embeds, anything behind an unresolved fetch. Not at risk: elements already in the DOM, which resolved in ~0.008s before and after.

The trade is still right — the cost was certain and large, the risk is narrow and addressable — but it is real, and right now it fails silently.

What a real consumer already does

def preload_all_images
  scroll_to :bottom
  assert_text "JetThoughts. All Rights Reserved", exact: false
  scroll_to :top
end

called on the line before the screenshot, plus document.fonts.ready in their wrapper. This works today and needs nothing from us.

Considered and rejected: a before_capture block

assert_matches_screenshot("x") { preload_all_images } is functionally identical to calling the method on the previous line — the work happens once before capture either way. It adds API surface and buys nothing.

Worth revisiting only if a case appears that must run inside the stability retry loop, which is the one thing a block could do that a preceding line cannot. No such case is known.

What to build instead

• Document that skip_area masks what exists at assertion time, with the working pattern for late-loading content (scroll-to-settle, assert_selector, document.fonts.ready). This alone covers the common case.
• Report selectors that matched nothing in EVERY screenshot of a run — once, on the summary line, never per-screenshot. fix: skip_area wait, an invisible summary line, and a phantom assertion (#272, #269, #270) #275 deliberately declined a per-screenshot warning because the gem cannot tell a typo from a legitimately image-less page, and the legitimate case would fire constantly. A run-level tally has no such problem: a selector that never matched anywhere is a typo or stale with high probability; one that matched somewhere is doing its job. This was fix: skip_area wait, an invisible summary line, and a phantom assertion (#272, #269, #270) #275's own stated upgrade path, and the readiness risk is what justifies building it now.
• CHANGELOG must say so. Anyone upgrading who was unknowingly relying on the implicit wait gets a newly flaky mask with no warning until the tally ships. That belongs in the 2.0.0 entry next to the skip_area selectors that match nothing block for 5s each — measured at 44% of a real suite #272 line, not discovered in production.

Decision recorded at .okf/decisions/skip-area-element-readiness.md with the options weighed.

[pftg]

Correction — the block is accepted, and my rejection was wrong

I dismissed assert_matches_screenshot("x") { preload_all_images } as "functionally identical to calling the method on the line above." The maintainer pointed out the case I missed:

def assert_matches_screenshot(name, ...)
  return false unless SnapDiff.config.active?   # dsl.rb:72 — before anything

With screenshots disabled, a preceding line still runs. A block does not.

preload_all_images is three browser round-trips — scroll_to :bottom, an assert_text with its own wait, scroll_to :top. Switch screenshots off to speed up the suite and you keep paying every one of them, because the readiness scaffolding sits outside the thing you disabled.

That is decisive, and it connects two threads that were being worked separately: this issue, and the DevX question of running visual tests rarely. "Turn visual tests off" is only actually free if the work done to prepare for them goes too. Right now it is free-except-for-the-scaffolding, and the scaffolding is browser round-trips — the expensive kind.

It also generalises beyond skip_area. document.fonts.ready (#273), stabilising CSS injection, waiting on a widget — every pre-capture concern belongs inside the same guard as the capture it serves.

Revised scope

• Optional block on assert_matches_screenshot and capture_screenshot, invoked after the active? guard and immediately before capture. One &block parameter and one yield.
• Guard it as the USER's code: with screenshots disabled, the block must not run — assert on a side effect, not on a stub's call count.
• Guard the enabled path too: block runs exactly once, before capture, and a raise inside it surfaces as the user's error rather than being swallowed.
• Decide and document the interaction with the stability retry loop: the block runs once before the loop, not per attempt. If a per-attempt need ever appears that is a separate decision, not a silent behaviour change.
• Not a general hook. No config-level before_capture, no after-hooks. One optional block, two DSL methods, scoped to one capture.
• Docs: present it as where readiness work belongs — skip_area targets, fonts, lazy images — and say plainly that work placed there is skipped when screenshots are off.

Items 2 and 3 from the original scope (document the mask semantic; run-level tally of never-matching selectors) are unchanged and still needed — the block makes readiness possible to express correctly, it does not make a silently empty mask visible.

.okf/decisions/skip-area-element-readiness.md updated: option C moved from rejected to accepted, with the reasoning and with the original rejection left in place rather than quietly deleted.

[pftg]

Shipped in #279. Readiness block: verified that with screenshot_enabled = false the block runs 0 times (side-effect assertion, not a stub call count), and that when enabled it runs exactly once BEFORE capture — not once per stability attempt. Never-matched-selector tally reports once on the summary line, survives the fork-parallel merge (hit and miss for one selector can arrive from different processes, so both sets ride the fragment), and stays silent when empty. Also removed the stale docs/configuration.md claim that an unmatched selector waits for the element — untrue since #272.