maestro-runner

Release 1.1.28

This release is about running a Maestro suite and getting Maestro's answer. Most of it came from running real Maestro suites (DuckDuckGo Android and iOS, React Native's RNTester, React Navigation) side by side with Maestro and fixing each place the two disagreed. The largest of those is selector matching: text and id selectors now match the whole value, as Maestro does, which is a behaviour change — see below. DeviceLab becomes the default driver on both platforms: on iOS it runs a new agent, on simulators and on real iPhones. Every flow gets DEVICE_UDID, -e stops splitting values at commas, and the Appium driver closes a long list of gaps with the native drivers.

⚠️ Behaviour changes

DeviceLab is the default driver on Android and on iOS. Running without --driver now uses the on-device DeviceLab agent on both platforms: on Android instead of UIAutomator2, on iOS instead of WebDriverAgent, on simulators and real iPhones (a real iPhone still needs --team-id, as WDA did). Nothing changes for a run that names its driver. To keep the previous defaults, pass --driver uiautomator2 on Android or --driver wda on iOS; both drivers are unchanged. See Changed below for the numbers behind the switch.

Text and id selectors match the whole value, ignoring case, as in Maestro. A plain text selector used to match any element whose text, content description or hint contained it, so tapOn: Open could land on a "Talk · Open" row and assertVisible: English passed on "Language: English". Ids matched as substrings too: id: login found com.app:id/login_button. Maestro compiles every text and id selector as a case-insensitive regex that must match the whole value (an id may match the whole resource-id or the part after the package prefix), falls back to the literal text when the pattern does not compile, and also accepts a value equal to the pattern. That rule now applies on DeviceLab, UIAutomator2 and Appium on Android, on --driver devicelab and --driver devicelab-legacy on iOS, and on Appium for iOS — both in the queries sent to the device and in the page-source matchers. A flow that relied on substring matching must say so with a regex. The WDA driver keeps its existing predicate matching: it prefers an element whose whole text matches and falls back to a substring match when there is none (#188, #161).

- tapOn: "Open"               # only an element whose whole text is "Open" (any case)
- tapOn: ".*Open.*"           # any element whose text contains "Open"
- tapOn: { id: "login" }      # "login" or "com.app:id/login", not "login_button"
- tapOn: { id: ".*login.*" }  # the old substring behaviour, spelled out

Regex selectors ignore case again. 1.1.26 made regex text selectors case-sensitive on the premise that Maestro does; it does not — every text and id selector is compiled with IGNORE_CASE, and suites depend on it ((let's get started!|Let's do it!) against "Let's get started!"). Regexes now ignore case. The problem 1.1.26 fixed is kept solved as a preference: when several elements match, those matching in the pattern's own case come first, so ^SIGN OUT$ still taps the "SIGN OUT" button ahead of a "Sign out" row (#151).

An index: past the number of matches finds no element. It used to fall back to the first match, so assertNotVisible: {id: row, index: 1} ("there is no second row") failed with one row on screen, and a tap with an out-of-range index hit the first row. Now it names no element, on every mobile driver (#188).

-e keeps commas in values. -e REPLY="Thanks, going with Vue" reached the flow as REPLY=Thanks. Each -e is now one variable, as in Maestro, so -e A=1,B=2 sets A to 1,B=2;

Mostly about flows that already work on Maestro working the same way here.

1.1.26 made selectors stricter, and one of those fixes woke up a parsing bug that had been dormant for months: any inputText that named an id: stopped finding its field, and because that step usually lives in a shared login sub-flow, whole suites went red on their first command. That is fixed. So are three places where a Maestro flow was read differently here without a word — speed: on scrolls, the value: spelling of airplane and dark mode, and an element-relative point: on swipes.

Two things are new: addMedia takes documents, so a flow can seed a PDF and pick it in the system file picker; and a password passed through a variable no longer ends up in the report.

No behaviour changes this release — nothing that passes on 1.1.26 should start failing.

Added

• addMedia accepts documents — PDF, Word, Excel, PowerPoint, txt, csv, rtf, json and zip. Android places them in Download/, where the system file picker lists them immediately; the iOS simulator places them in "On My iPhone", which every app's document picker browses. A physical iPhone refuses with an explanation — Apple exposes no path into Files storage (#167, thanks @georgetarazi-swipejobs).

  - addMedia:
      - assets/contract.pdf
  - tapOn: "Attach a file"
  - tapOn: "contract.pdf"
  

• Text selectors match a field's validation error on Android — a Compose field whose only visible content is its error message can be found by that text, as in Maestro 2.9 (UIAutomator2 and Appium drivers).

Fixed

• inputText with a selector failed on every native driver since 1.1.26 — the value to type was silently reused as a text predicate on the target field (#166, diagnosed to the line by @laiskajoonas).
• A password passed through a variable was written into the report — steps inside a runFlow were described after expansion, so ${PASSWORD} appeared in report.html, the flow JSON and the console as the password itself. The per-request client.log carried it too; text-entry request bodies are now redacted on every driver.
• speed: on scroll and scrollUntilVisible was ignored by every driver — now honoured with Maestro's own formula. An absent speed: keeps the existing default so no current flow scrolls a different distance, and very high speeds are floored at a 50ms swipe, because Android reads a 1ms swipe as a tap (#165, thanks @ismailhaiberhub).
• Tapping a file in the system file picker did nothing on the DeviceLab driver — the picker ignores injected taps; those now go through input tap (#87, thanks @LandonPatmore).
• Maestro's value: spelling of setAirplaneMode and setDarkMode was read as disabled.
• scrollUntilVisible on Appium accepted a container-clipped sliver as fully visible — the 1.1.26 fix now covers the third Android driver (#164).
• setOrientation returned before the display had turned, so the next step could read a half-rotated screen.
• An element-relative point: on swipe.from was ignored by the Appium and WDA drivers.
• stopRecording could return an unplayable file — it now waits for screenrecord to finish writing.
• WDA on a physical iPhone pins the destination architecture, avoiding the arm64/arm64e ambiguity that can stall startup; MAESTRO_WDA_DEST_ARCH overrides it.

Changed

• Formatting is gated in CI.
• The Go toolchain is pinned and the standard-library CVEs are cleared.

Validation

Android on a Pixel 4a, against the released binary: auth 4/4 on each of uiautomator2, devicelab and appium, plus the release's own checks on both native drivers — inputText with an id:, speed: 1 and 100, orientation, a PDF seeded with addMedia and picked in the system file picker, and a login run whose output directory was searched for the password (not found). Browser 50/64, unchanged from baseline on all five suites. iOS simulator (iPhone 16 Pro, iOS 18.6): auth 9/9

Mostly about taps and selectors landing where the flow says they should.

A tap used to be injected first and validated afterwards, so a "rejected" tap had already hit whatever sat under the fold — usually a bottom tab, which navigated away and left every later step running on the wrong screen. scrollUntilVisible would stop on a 9-pixel sliver of a button because the hierarchy handed us a rect it had already clipped. Two selector semantics move closer to Maestro's, and both change what an existing flow matches.

Reaching the runner got easier too: it is on npm, it compiles on Windows, and it reads flow files with Windows line endings.

⚠️ Two behaviour changes

Both make selectors stricter. A flow that relied on the looser behaviour will start failing — and that is the point, because the looser behaviour was matching things the flow never asked for.

Regex selectors are case-sensitive. Every regex was previously compiled with (?i), so an anchored pattern could not distinguish what it was written to distinguish: ^SIGN OUT$ matched a "Sign out" row as readily as the "SIGN OUT" button, and page-source order decided which one was tapped. Plain text is not a regex and stays case-insensitive (#151).

- tapOn: "^SIGN OUT$"          # now matches only the uppercase button
- tapOn: "(?i)^sign out$"      # opt back in to insensitivity
- tapOn: "sign out"            # plain text — unchanged

A selector naming both id: and text: must match one element carrying both. The two were emitted as separate queries, so the finder returned on whichever hit first — an AND written by the author behaving as an OR (#157, #158).

Added

• npm — npx maestro-runner test flows/, or pin it beside a React Native or Expo project. No postinstall and nothing downloaded at install time, so it works offline, behind a proxy, and in CI that blocks postinstall network access.
• --window-size <WxH> — set the browser viewport, so one suite covers phone, tablet and desktop breakpoints.
• --new-command-timeout <seconds> — sets appium:newCommandTimeout; matters on cloud --parallel runs where early sessions are reaped while waiting (#124, thanks @JSap0914 and @devrchoi).
• Windows builds — the runner compiles for Windows (#159).

Fixed

• A tap was injected before it was validated — the off-screen guard ran on a tap that had already landed. It now runs on the device, on the bounds about to be clicked, and declines to click. Five more coordinate paths that never reached that guard validate too, as does the lazy-retry path, which had no check at all (#162).
• A tap is refused when a window above the target covers the point — a keyboard, a system or permission dialog — and the error names it.
• Chained UiSelector predicates were first-match-wins, so .resourceId(…).textContains(…) matched on text alone (#160).
• scrollUntilVisible accepted a container-clipped sliver as fully visible (#164).
• "Driver not installed" was reported for any adb failure, sending people to reinstall something already there (#163).
• A CSS selector tapped the first DOM match even when hidden, then timed out with context deadline exceeded.
• setPermissions was missing on most drivers; iOS now honours location's own vocabulary, and an unusable value is reported instead of silently resetting the permission (#147).
• A nil-pointer panic in the WebView manager killed the whole run (#149).
• A step's label: is used in the HTML report instead of being overridden by its selector (#150).
• Flow files with Windows line endings failed to parse (#159).
• checked: reads the checked state on the native Android drivers too (#153, #154).
• Directional relative selectors pick the nearest element, not the deepest (#16).
• ${VAR} is expanded in every step's env: block.

Changed

• Flutter widget trees are no longer re-serialised on every poll (#152).
• Binaries are built with

Release 1.1.25

This release is about the first five minutes and the oldest complaints: a doctor that says exactly what your machine is missing, a devices listing, a screenshot command, runShell for the one adb call every suite eventually needs, and an inputText that checks what actually landed in the field. It is also about gestures that behave like a user's finger: a real dragAndDrop on every driver — press, hold until the item lifts, move slowly, settle, release — and a scrollUntilVisible that stops when the element is actually visible instead of one pixel in. Flutter apps go from barely drivable to ahead of WDA on the DeviceLab iOS driver, --step-delay slows any flow down for demos and animation-heavy apps, and JUnit reports carry test-tracking properties and failure artifacts into CI.

Added

• doctor — checks the toolchain and says what to do about each gap, with --json for CI. A missing platform is a warning rather than an error, so it gates a Linux runner without failing it for having no Xcode; only a broken install or a team ID Xcode does not have exits non-zero. Three checks earn their place: Command-Line-Tools-instead-of-full-Xcode, which otherwise surfaces far from its cause; an AVD naming a system image that is not installed, which nothing reports at run time and which shows up only as a driver polling for a device that will never boot; and --team-id checked against the signing certificates in the login keychain, which is the entire content of error: No Account for Team "..." at WDA build time.

  ✗ Signing identity for team abcd123456 — no certificate belongs to team abcd123456;
    this Mac has: A3RCAA2YAX
      Pass one of the team IDs listed above as --team-id, or add that team's account in Xcode.
  

• devices — Android devices and emulators, iOS simulators and connected phones in one listing, with --json and --all for the shut-down simulators. A phone that answers usbmux but refuses the lockdown handshake is listed as not-ready with the reason, instead of looking identical to a working one.
• screenshot — capture the current screen with the same device and driver flags a run takes. Writes a file, or - for stdout.
• runShell — run a host command from a flow, for the adb, simctl or xcrun call every suite eventually needs.

  - runShell:
      command: adb -s $MAESTRO_DEVICE_ID shell getprop ro.build.version.sdk
      output: SDK
  

  output: binds the command's trimmed output to a flow variable for later steps. The environment carries the flow's variables, the step's own env:, and MAESTRO_DEVICE_ID / MAESTRO_PLATFORM / MAESTRO_APP_ID — the device id being the one that matters, since a bare adb shell fails outright when --parallel has two devices attached. Bounded at 30s by default (timeout: to change it), output capped at 64KB keeping the tail, and a non-zero exit fails the step unless it is optional: true.
• scrollUntilVisible can scroll inside a container — from: names the scrollable element, for a screen whose scrolling part is an inner list or a horizontal carousel rather than the screen itself. The gesture is centred in the container and inset at each end, so a swipe starting on its edge is not claimed by the parent list instead. UIAutomator2 for now; the other drivers refuse from: by name rather than silently scrolling the screen.

  - scrollUntilVisible:
      element:
        id: "product-item-Playwright"
      from:
        id: "products-list"
  

• --video never|always|on-failure — keep screen recordings only for the runs worth watching. --record still means always. A recording cannot be started retroactively, so on-failure records every flow and discards the passing ones at the end. The vocabulary matches --artifacts rather than inventing a second spelling for the same idea.
• lint --json — {checked, failed, results[]} on stdout, for editors, CI and anything