Verify the toolchain: which tools work, which are impaired, what to install.

Run this first when anything behaves unexpectedly. It distinguishes "the Maestro CLI is missing" from "the CLI is fine but the emulator is unauthorized", which are two very different afternoons.

List every connected Android device and emulator with its health and lease state.

Call this before planning any parallel work: it is the only way to learn how many devices are actually usable right now, and which of them are already held by runs in flight. A device is usable when adb reports state device; unauthorized and offline devices appear in the list but cannot run flows.

Run several Maestro flows in parallel across leased devices.

Flows are distributed round-robin over the leased devices, so N flows on M devices take roughly N/M rounds. Every device is leased for the duration and released on exit, including on failure, so a crashed run cannot strand a device.

Returns per-flow results plus wall-clock time, the sequential estimate, and the resulting speedup. A failure on one device never masks a pass on another: each result is reported separately.

Run a Maestro flow, then check assertions against the screen it left behind.

The flow's own result is always reported, even when assertions cannot run. Assertions are skipped entirely when the flow failed, because checking expectations after a known-broken run produces a second, noisier failure that buries the first one.

Compare the current screen, or a region of it, against a baseline image.

Region comparison is the reason this is usable. A whole-screen baseline on a device with a clock in the status bar differs on every single run, which is how visual testing earns its reputation for flakiness. Cropping to the part that matters is what makes the result mean something.

update_baseline exists so refreshing a baseline is an explicit, visible act rather than an edit someone makes by hand and forgets to review.

Run a flow and, when it fails, gather the evidence needed to attribute the fault.

Collects the screen before the run, Maestro's own capture at the moment of failure, the screen after, the focused window, the relevant slice of logcat, and the elements present at failure — then applies an attribution heuristic and writes a JSON plus HTML bundle.

Returns diagnosed: false when the flow passes, because there is nothing to diagnose and inventing an analysis would be noise.

Generate a replayable Maestro flow from a described exploration, then verify it runs.

With both capture_assertions and validate enabled the steps run twice: once to observe the resulting screen and derive assertions, once to prove the finished file replays. That is deliberate — a flow that has never been executed is a hypothesis, not a test.