Documentation
Playground GitHub

whitehall snap

Capture every screen and compare it to its golden PNG.

Usage

whitehall snap [target] [options]
whitehall snap                  # capture every route, compare to the goldens
whitehall snap --update         # accept the current output as the goldens
whitehall snap --filter feed    # one route
       ok  /                            unchanged
  changed  /settings                    1841 pixels differ (0.64%)
            snapshots/.diff/settings.png
       ok  /favorites                   unchanged

Goldens live in snapshots/, one PNG per route. A change writes a three-panel diff to snapshots/.diff/ — the golden, the current capture, and a mask of what moved — and exits 1. A first run with no goldens writes them and passes.

Options

FlagWhat it does
-u, --updateAccept the current output as the goldens
-f, --filter <text>Only routes whose path or name contains this
-d, --device <id>Which phone
--tolerance <pct>Percentage of pixels that may differ before a screen fails. Default 0.1
--threshold <n>Per-channel color tolerance, for a compositor that is not bit-exact. Default 2
--settle <ms>Milliseconds to wait after navigating. Default 600
-r, --releaseCapture a release build instead of debug

Every screen, no configuration

A debug build reads a wh_route extra off its launch intent, so every route is reachable without a deep-link scheme and nothing has to be configured. This is debug builds only: in a release build the extra would let any installed app steer navigation.

Determinism

A screenshot suite that is not deterministic fails for reasons nobody caused, and then gets switched off. Each run forces animation, transition and animator scales to zero and puts the system UI in demo mode: a fixed clock, a full battery, full signal, no notification icons. All of it is restored afterwards, on the failure path too.

Routes with parameters

A route such as /photo/:id needs a value, and what a good value is depends on your app. It is configuration, in snapshots/routes.toml, keyed by the route path with :id rather than the [id] the folder is named:

# snapshots/routes.toml
["/photo/:id"]
id = "1"

A parameterized route with no entry is skipped and said out loud, naming the file that would fix it, rather than captured with an invented id.

whitehall test runs snap as a suite (--kind snap), and whitehall test --update passes through to it.

See Also