diff --git a/review/golden-review-v2.html b/review/golden-review-v2.html
index 45253d7..a6e6740 100644
--- a/review/golden-review-v2.html
+++ b/review/golden-review-v2.html
@@ -110,7 +110,7 @@ <h1>Golden Set v2 Review</h1>
 </div>
 
 <script>
-const DATA = {"pin": "f232d54", "questions": [{"id": "g001", "kind": "fact", "question": "There are no Mobium release binaries yet. What do I need on my Mac to install the mobium command, and what is the command?", "tags": ["how-to", "new-user"], "gold": [{"id": "docs/quickstart/README.md#1-install-mobium", "heading": "1. Install mobium", "path": "docs/quickstart/README.md", "excerpt": "Until the first release there are no prebuilt binaries: mobium installs with **Go 1.24 or later** ([go.dev/dl](https://go.dev/dl/)), and needs nothing else. ```sh go install github.com/mobiumdev/mobium/cmd/mobium@latest mobium --version ``` It lands in `$(go env GOPATH)/bin`; make sure that is on your `PATH`. Each client page says how to install that client. Python (with `git`) and Go install straight from GitHub tod…"}], "retrieved": [{"id": "docs/quickstart/README.md#1-install-mobium", "heading": "1. Install mobium", "path": "docs/quickstart/README.md", "excerpt": "Until the first release there are no prebuilt binaries: mobium installs with **Go 1.24 or later** ([go.dev/dl](https://go.dev/dl/)), and needs nothing else. ```sh go install github.com/mobiumdev/mobium/cmd/mobium@latest mobium --version ``` It lands in `$(go env GOPATH)/bin`; make sure that is on your `PATH`. Each client page says how to install that client. Python (with `git`) and Go install straight from GitHub tod…", "gold": true}, {"id": "docs/SETUP.md#installing-a-release", "heading": "Installing a release", "path": "docs/SETUP.md", "excerpt": "From the first tagged release on, each one carries mobium prebuilt for macOS, Linux and Windows, on amd64 and arm64, so installing it needs no Go: `mobium_<version>_<os>_<arch>.tar.gz` (`.zip` for Windows), each holding the binary, the license and its notices, and the README, and `SHA256SUMS` over all of them. The binary is static — nothing else to install with it. ```sh v=0.1.0; os=darwin; arch=arm64 # or linux / wi…", "gold": false}, {"id": "docs/quickstart/python.md#2-install-the-client", "heading": "2. Install the client", "path": "docs/quickstart/python.md", "excerpt": "Not on PyPI yet — pip installs it straight from GitHub, which needs `git` on your `PATH`. After the first release this becomes `pip install mobium`. ```sh mkdir quickstart && cd quickstart python3 -m venv .venv .venv/bin/pip install \"mobium @ git+https://github.com/mobiumdev/mobium.git#subdirectory=clients/python\" ```", "gold": false}, {"id": "README.md#quick-start", "heading": "Quick start", "path": "README.md", "excerpt": "Requirements: - **Go 1.24+**, to install it — prebuilt binaries arrive with the first release ([SETUP.md](docs/SETUP.md#installing-a-release)) - **Android:** platform-tools on `PATH` (or `ANDROID_HOME`, or `MOBIUM_ADB_PATH`), and an emulator or a phone with USB debugging on - **iOS:** full Xcode and a booted simulator — or an iPhone on a cable, with an Apple ID (a free one works) added to Xcode ```sh go install githu…", "gold": false}, {"id": "docs/quickstart/mcp.md#2-connect-an-agent", "heading": "2. Connect an agent", "path": "docs/quickstart/mcp.md", "excerpt": "`mobium mcp` is an MCP server on stdio, so there is nothing to install beyond `mobium` itself. Register it with your agent — in Claude Code: ```sh claude mcp add mobium -- mobium mcp ``` Other clients take the same command in their `mcpServers` configuration; [the MCP guide](../guides/mcp.md#1-connect-it) has the JSON. From then on, ask the agent for what you want done on the device, and it calls the tools below itse…", "gold": false}], "missed": false, "facts": ["Until the first release mobium installs with Go 1.24 or later and needs nothing else. ⟦Go 1.24⟧", "The install command is go install github.com/mobiumdev/mobium/cmd/mobium@latest. ⟦go install github.com/mobiumdev/mobium/cmd/mobium@latest⟧", "The binary lands in $(go env GOPATH)/bin, which must be on PATH. ⟦GOPATH⟧"], "concern": "", "check": "Claude's reading: go.mod declares go 1.24.0, matching the quick start's Go 1.24 or later; cmd/mobium is the main package. SETUP.md#installing-a-release covers the future prebuilt route and is a likely near miss, not gold. Verified in: go.mod:3, cmd/mobium/main.go."}, {"id": "g002", "kind": "fact", "question": "I made an Android virtual device in Android Studio. How do I get Mobium to start it and wait until it is ready, and how do I see its screen while it runs?", "tags": ["how-to", "new-user"], "gold": [{"id": "docs/quickstart/README.md#android-emulator-macos-linux", "heading": "Android emulator (macOS, Linux)", "path": "docs/quickstart/README.md", "excerpt": "Install [Android Studio](https://developer.android.com/studio) or the command-line tools, then create a virtual device (Device Manager in Android Studio, or `avdmanager`) and boot it by name: ```sh mobium boot <avd> ``` It finds the SDK's `emulator` itself, through `ANDROID_HOME` or the SDK's usual place, and answers once Android has finished booting — not merely once `adb` can see it. Add `--window` to watch it; it …"}], "retrieved": [{"id": "docs/quickstart/README.md#android-emulator-macos-linux", "heading": "Android emulator (macOS, Linux)", "path": "docs/quickstart/README.md", "excerpt": "Install [Android Studio](https://developer.android.com/studio) or the command-line tools, then create a virtual device (Device Manager in Android Studio, or `avdmanager`) and boot it by name: ```sh mobium boot <avd> ``` It finds the SDK's `emulator` itself, through `ANDROID_HOME` or the SDK's usual place, and answers once Android has finished booting — not merely once `adb` can see it. Add `--window` to watch it; it …", "gold": true}, {"id": "docs/quickstart/python.md#3-the-code", "heading": "3. The code", "path": "docs/quickstart/python.md", "excerpt": "Save this as `quickstart.py` in the project folder — it is [examples/python/quickstart.py](examples/python/quickstart.py). ```python \"\"\"Mobium quick start: start a session, drive Settings, quit. MOBIUM_PLATFORM=android python3 quickstart.py # or ios \"\"\" import os from mobium import start # Settings is on every emulator, simulator and phone, with nothing to install. PLATFORMS = { \"android\": {\"app\": \"com.android.settin…", "gold": false}, {"id": "docs/quickstart/cli.md#2-the-code", "heading": "2. The code", "path": "docs/quickstart/cli.md", "excerpt": "Save this as `quickstart.sh` — it is [examples/cli/quickstart.sh](examples/cli/quickstart.sh). ```sh #!/bin/sh # Mobium quick start from the command line: start a session, drive Settings, # quit. # # MOBIUM_PLATFORM=android sh quickstart.sh # or ios set -e PLATFORM=\"${MOBIUM_PLATFORM:-android}\" if [ \"$PLATFORM\" = ios ]; then APP=com.apple.Preferences ROW=General NEXT=\"label=About,role=button\" else APP=com.android.set…", "gold": false}, {"id": "docs/quickstart/cli.md#quick-start-command-line", "heading": "Quick start: Command line", "path": "docs/quickstart/cli.md", "excerpt": "<!-- Generated by docs/quickstart/build.py from examples/ and output/. Edit those, then run `make quickstart`. --> Start a session on a device, launch Settings, tap a row, take a screenshot, and quit — from the command line. Starts with `mobium session start --platform android --app com.android.settings`; ends with `mobium session end`. Before this page: [install mobium and prepare a device](README.md).", "gold": false}, {"id": "docs/quickstart/go.md#3-the-code", "heading": "3. The code", "path": "docs/quickstart/go.md", "excerpt": "Save this as `main.go` in the project folder — it is [examples/go/main.go](examples/go/main.go). ```go // Mobium quick start: start a session, drive Settings, quit. // // MOBIUM_PLATFORM=android go run . # or ios package main import ( \"context\" \"fmt\" \"log\" \"os\" \"strings\" \"time\" mobium \"github.com/mobiumdev/mobium/clients/go\" ) // Settings is on every emulator, simulator and phone, with nothing to install. var platfor…", "gold": false}], "missed": false, "facts": ["mobium boot <avd> starts the emulator by its AVD name and answers once Android has finished booting, not merely once adb sees it. ⟦mobium boot⟧", "It runs headless unless --window is added. ⟦--window⟧"], "concern": "", "check": "Claude's reading: BootEmulator passes -no-window -no-audio unless window is set (boot.go:139-141) and waits for sys.boot_completed=1 (boot.go:189). SETUP.md#android-emulator says the same in one sentence and may be returned instead; the quick-start section is the fuller answer. Verified in: internal/device/boot.go:115-141, internal/device/boot.go:189."}, {"id": "g003", "kind": "fact", "question": "My Android emulator won't start and says 'Cannot find valid sdk root path', yet adb works fine from my terminal. What is actually wrong?", "tags": ["troubleshooting", "new-user"], "gold": [{"id": "docs/SETUP.md#two-traps-neither-of-which-names-its-own-cause", "heading": "Two traps, neither of which names its own cause", "path": "docs/SETUP.md", "excerpt": "- **`platform-tools` must be installed *into the SDK root* by `sdkmanager`**, not only as the `android-platform-tools` Homebrew cask. The emulator validates the SDK root by looking for that directory and aborts with `Broken AVD system path` / `Cannot find valid sdk root path` — while `adb` sits on your `PATH` working perfectly, which sends you looking in entirely the wrong place. `mobium doctor` checks this specifica…"}], "retrieved": [{"id": "docs/SETUP.md#two-traps-neither-of-which-names-its-own-cause", "heading": "Two traps, neither of which names its own cause", "path": "docs/SETUP.md", "excerpt": "- **`platform-tools` must be installed *into the SDK root* by `sdkmanager`**, not only as the `android-platform-tools` Homebrew cask. The emulator validates the SDK root by looking for that directory and aborts with `Broken AVD system path` / `Cannot find valid sdk root path` — while `adb` sits on your `PATH` working perfectly, which sends you looking in entirely the wrong place. `mobium doctor` checks this specifica…", "gold": true}, {"id": "CHALLENGES#environment-traps", "heading": "Environment traps", "path": "docs/CHALLENGES.md", "excerpt": "None of these is a Mobium defect; each cost real time and no error named its cause. - **`platform-tools` must be installed into the SDK root** with `sdkmanager`, not only as the Homebrew cask. The emulator validates the SDK root by looking for that directory and dies with `Broken AVD system path` — while `adb` is on `PATH` and working perfectly, which sends you looking in entirely the wrong place. - **`avdmanager` pr…", "gold": false}, {"id": "docs/quickstart/README.md#android-emulator-macos-linux", "heading": "Android emulator (macOS, Linux)", "path": "docs/quickstart/README.md", "excerpt": "Install [Android Studio](https://developer.android.com/studio) or the command-line tools, then create a virtual device (Device Manager in Android Studio, or `avdmanager`) and boot it by name: ```sh mobium boot <avd> ``` It finds the SDK's `emulator` itself, through `ANDROID_HOME` or the SDK's usual place, and answers once Android has finished booting — not merely once `adb` can see it. Add `--window` to watch it; it …", "gold": false}, {"id": "docs/SETUP.md#setting-up-devices", "heading": "Setting up devices", "path": "docs/SETUP.md", "excerpt": "Everything Mobium needs on the machine and on the device, for all four kinds of target. Written from doing it: every trap below cost real time here, and most of them report something that names the wrong cause. **Run `mobium doctor` first.** It checks the whole list without needing a device, and exits non-zero if it found something: ``` ok adb Android Debug Bridge version 1.0.41 at /opt/homebrew/bin/adb note android …", "gold": false}, {"id": "docs/SETUP.md#on-linux", "heading": "On Linux", "path": "docs/SETUP.md", "excerpt": "Google ships the command-line tools as a zip, and the emulator and `platform-tools` for Linux **only for x86_64** — the SDK repository has no Linux arm64 build of either (checked 2026-09-28) — so an arm64 Linux machine cannot run the emulator. The emulator needs KVM: your user must be able to open `/dev/kvm` (usually by being in the `kvm` group). ```sh mkdir -p ~/android-sdk/cmdline-tools && cd ~/android-sdk/cmdline-…", "gold": false}], "missed": false, "facts": ["platform-tools must be installed into the SDK root by sdkmanager, not only as the Homebrew android-platform-tools cask; the emulator validates the SDK root by that directory. ⟦sdkmanager ; platform-tools⟧", "mobium doctor checks for this specifically. ⟦mobium doctor⟧"], "concern": "", "check": "Claude's reading: doctor's android sdk root check fails when the SDK root has no platform-tools directory and says to run sdkmanager platform-tools (doctor.go:115-118). The same trap is named in the doctor command's help text. Verified in: internal/agent/doctor.go:103-121, cmd/mobium/doctor.go:12-16."}, {"id": "g004", "kind": "fact", "question": "I restarted my Android emulator and my app came back as a build from days ago, missing screens I added since. Why, and how do I restart it without that happening?", "tags": ["troubleshooting", "test-author"], "gold": [{"id": "docs/SETUP.md#headed-and-headless-the-procedures-and-what-differs", "heading": "Headed and headless: the procedures, and what differs", "path": "docs/SETUP.md", "excerpt": "Measured 2026-09-26, when a headless emulator was restarted with a window mid-session and three things changed at once. The screen is the same; the **keyboard** and the **snapshot** are not. **Switching an emulator between the two.** It is decided at launch, so it is a restart, in the order `docs/SHUTDOWN.md` gives: ```sh mobium shutdown emulator-5554 && mobium boot mobium-test --window # headed mobium shutdown emula…"}], "retrieved": [{"id": "docs/SETUP.md#headed-and-headless-the-procedures-and-what-differs", "heading": "Headed and headless: the procedures, and what differs", "path": "docs/SETUP.md", "excerpt": "Measured 2026-09-26, when a headless emulator was restarted with a window mid-session and three things changed at once. The screen is the same; the **keyboard** and the **snapshot** are not. **Switching an emulator between the two.** It is decided at launch, so it is a restart, in the order `docs/SHUTDOWN.md` gives: ```sh mobium shutdown emulator-5554 && mobium boot mobium-test --window # headed mobium shutdown emula…", "gold": true}, {"id": "docs/SHUTDOWN.md#on-the-device", "heading": "On the device", "path": "docs/SHUTDOWN.md", "excerpt": "Stopping processes on your machine is not the whole job. **`clean-stop.sh --quit` now runs these**, so they are no longer a checklist nobody gets to. They were manual until a hierarchy dump turned up in `/data/local/tmp` six days after the session that wrote it, on an emulator stopped and rebooted twice in between — it was a hand-run `uiautomator dump` rather than mobium's own file, which is deleted after every read,…", "gold": false}, {"id": "docs/guides/graybox.md#when-the-app-is-not-waited-for", "heading": "When the app is not waited for", "path": "docs/guides/graybox.md", "excerpt": "Three things end a wait early, and the result says which, so a check that did not run never reads as one that passed: - **The app went to the background.** The library says `away` and `back`; while the app is away, an action elsewhere is not held up by it. - **The app stopped saying it is busy.** Busy is a lease: while work is in flight the library restates the count every half second, from a native timer that a busy…", "gold": false}, {"id": "docs/BACK.md#in-mobiumapp", "heading": "In MobiumApp", "path": "docs/BACK.md", "excerpt": "1. **Android back closed the app.** Fixed in mobium-app #12, measured above. Rebuild MobiumApp for any device that still has the old build, and keep `docs/checks/mobium-app.sh` passing. 2. **No swipe back on iOS.** Needs native-stack navigation; unmeasured. 3. **WebView screens.** Android back should go back in the page's history before leaving the screen, as a browser does. Unmeasured. 4. **Predictive back.** Measur…", "gold": false}, {"id": "CHALLENGES#186", "heading": "186. The emulator console answered nothing, and the error said nothing", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** `app_shake` on the Pixel 7 AVD, which had passed its check two days before, failing with \"the emulator did not say where its accelerometer rests:\" — and nothing after the colon. Every `adb emu` command printed nothing and exited 0, while the same commands typed into the console's own port answered at once. Another automation tool had rewritten `~/.emulator_console_auth_token` empty, a documented step of…", "gold": false}], "missed": false, "facts": ["-no-snapshot-save still loads the quick-boot snapshot on the next start, so everything installed since the snapshot is gone. ⟦-no-snapshot-save⟧", "Cold-boot with -no-snapshot-load, which mobium boot passes, or reinstall what you need and confirm its version. ⟦-no-snapshot-load⟧"], "concern": "", "check": "Claude's reading: BootEmulator always passes -no-snapshot-load and its comment cites the old-app snapshot problem (boot.go:116-118, 139). The fact is in part ~1 of the section. Verified in: internal/device/boot.go:115-139."}, {"id": "g005", "kind": "fact", "question": "What do I have to switch on, on the iPhone itself, before Mobium can drive it?", "tags": ["how-to", "test-author"], "gold": [{"id": "docs/SETUP.md#on-the-phone-once", "heading": "On the phone, once", "path": "docs/SETUP.md", "excerpt": "1. **Connect it with a cable, unlock it, tap Trust This Computer** and enter the passcode. 2. **Open Xcode → Window → Devices and Simulators** with the phone connected, and wait while Xcode prepares it. The next step's switch does not exist until this has happened. 3. **Settings → Privacy & Security → Developer Mode → on.** The phone restarts and asks you to confirm. 4. **Settings → Developer → Enable UI Automation →…"}], "retrieved": [{"id": "docs/RELEASE-CHECKLIST.md#ios-a-booted-iphone-simulator", "heading": "iOS — a booted iPhone simulator", "path": "docs/RELEASE-CHECKLIST.md", "excerpt": "- [ ] `mobium --driver wda map` on the home screen returns icons - [ ] Wait for something already on screen, and across a cold app launch - [ ] `mobium scroll-to` reaches a Settings row below the fold, and tapping it opens that screen - [ ] `mobium grant com.apple.Preferences photos` succeeds and says it could not be verified - [ ] `mobium grant <anything> camera` is refused, naming the missing service - [ ] Coordina…", "gold": false}, {"id": "CHALLENGES#153", "heading": "153. A real iPhone's WebDriverAgent answered anyone on its Wi-Fi", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** the threat model's open item, measured on the iPhone 15 Plus: the runner's `/status`, which reports the phone's Wi-Fi address, was asked again at that address from the Mac, over the network rather than the cable.", "gold": false}, {"id": "docs/SETUP.md#what-mobium-installs-and-removing-it", "heading": "What Mobium installs, and removing it", "path": "docs/SETUP.md", "excerpt": "On the machine, under `~/.mobium`: | | | | --- | --- | | `uiautomator2/`, `webdriveragent/` | pinned, checksummed device agents, ~40MB, downloaded on first use | | `webdriveragent-device/` | WebDriverAgent's pinned source and one signed build per team and phone, ~150MB — only once a real iPhone has been driven | | `daemon/` | socket and PID file, removed on shutdown | On an **Android** device, the default backend ins…", "gold": false}, {"id": "docs/THREAT-MODEL.md#the-mobile-side", "heading": "The mobile side", "path": "docs/THREAT-MODEL.md", "excerpt": "The OWASP Mobile Top 10 and MASVS are about the apps under test, not about Mobium, but two points apply to Mobium itself: - It installs a server APK on the device with its permissions granted, and builds and signs WebDriverAgent for a person's iPhone. Both are removable, and [SETUP](SETUP.md#what-mobium-installs-and-removing-it) says how. - It must leave nothing on the device: a hierarchy dump in `/data/local/tmp` is…", "gold": false}], "missed": true, "facts": ["Trust the computer over a cable and let Xcode's Devices and Simulators window prepare the phone, then turn on Developer Mode. ⟦Developer Mode⟧", "Turn on Settings > Developer > Enable UI Automation; without it WebDriverAgent fails with \"Timed out while enabling automation mode\". ⟦Enable UI Automation⟧", "Set Auto-Lock to Never (or long enough) so the phone does not lock mid-run. ⟦Auto-Lock⟧"], "concern": "", "check": "Claude's reading: wdaphone.go recognizes WebDriverAgent's \"Timed out while enabling automation mode\" log and names the switch (lines 653-660). README.md#platforms~1 lists Developer Mode and Enable UI Automation too and is a plausible near miss, but lacks the trust/Xcode/Auto-Lock steps. Verified in: internal/device/wdaphone.go:653-660."}, {"id": "g006", "kind": "fact", "question": "Which simulator features does Mobium refuse on a real iPhone, and how do I reset an app's data on a phone instead?", "tags": ["support", "test-author"], "gold": [{"id": "docs/SETUP.md#what-a-phone-cannot-do", "heading": "What a phone cannot do", "path": "docs/SETUP.md", "excerpt": "These are done by `simctl` on a simulator and `devicectl` has no equivalent, so on a phone they are refused, each with the reason, rather than approximated: **permissions, appearance, the clipboard, simulated location and routes, and notifications** — reading or posting them. **Clearing an app's data takes its bundle on a phone.** Nothing can delete from an app's container there, so `mobium clear-data <app> --bundle …"}], "retrieved": [{"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": false}, {"id": "docs/SETUP.md#what-a-phone-cannot-do", "heading": "What a phone cannot do", "path": "docs/SETUP.md", "excerpt": "These are done by `simctl` on a simulator and `devicectl` has no equivalent, so on a phone they are refused, each with the reason, rather than approximated: **permissions, appearance, the clipboard, simulated location and routes, and notifications** — reading or posting them. **Clearing an app's data takes its bundle on a phone.** Nothing can delete from an app's container there, so `mobium clear-data <app> --bundle …", "gold": true}, {"id": "docs/checks/README.md#results", "heading": "Results", "path": "docs/checks/README.md", "excerpt": "Run 2026-09-13. Both emulators are the same Pixel 7 profile — 1080x2400 at 420dpi — so the only difference between them is the OS. | Device | OS | calculator.sh | clock-timer.sh | external-driver.sh | third-party-app.sh | device-state.sh | | --- | --- | --- | --- | --- | --- | --- | | Pixel 7 AVD | Android 15 (API 35) | PASS 6.4s | PASS 5.5s | PASS | PASS | PASS | | Pixel 7 AVD | Android 17 (API 37) | PASS 6.9s | PAS…", "gold": false}], "missed": false, "facts": ["On a phone Mobium refuses permissions, appearance, the clipboard, simulated location and routes, and notifications, each with the reason, because simctl does them and devicectl has no equivalent. ⟦devicectl⟧", "Clearing an app's data on a phone takes its bundle: mobium clear-data <app> --bundle uninstalls and reinstalls the app. ⟦--bundle⟧"], "concern": "", "check": "Claude's reading: simulatorOnly in wdaphone.go lists exactly permissions, appearance, clipboard read/write, geolocation, routes, clear-data and notifications, and phoneRemedies gives the --bundle reinstall route for clear-data. The code also lists clipboard read separately; the doc says 'the clipboard'. Verified in: internal/mobiumdriver/wdaphone.go:196-230, internal/mobiumdriver/wdaphone.go:263-265."}, {"id": "g007", "kind": "multi", "question": "Can I use Mobium on a Windows PC for my Android and iOS app testing today, and how far does that go?", "tags": ["support", "new-user", "new since 7b590a4"], "gold": [{"id": "docs/WINDOWS.md#windows-support", "heading": "Windows support", "path": "docs/WINDOWS.md", "excerpt": "**Status: devices driven from Windows since 2026-10-22; not yet declared supported.** On a Windows 11 laptop (24H2, i7-8565U, 8 GB), an Android 15 emulator and a Pixel 8 Pro over USB were driven through `mobium mcp`, the CLI over the named pipe, and all five clients, which passed every step on both. A sweep of the checks on the emulator found six things, all fixed: the daemon dying with the SSH session that started i…"}, {"id": "docs/WINDOWS.md#android-only-ios-is-not-possible-on-windows", "heading": "Android only. iOS is not possible on Windows.", "path": "docs/WINDOWS.md", "excerpt": "Said here rather than in a footnote, because it is the first question anyone asks and the answer is structural rather than a gap in the work. Mobium drives iOS through `xcrun simctl` — 41 call sites in `internal/device` alone — and through WebDriverAgent, which it installs as the prebuilt `WebDriverAgentRunner-Build-Sim-arm64.zip`. `simctl` ships inside Xcode and Xcode is macOS-only; the artifact is a *simulator* bui…"}], "retrieved": [{"id": "docs/WINDOWS.md#android-only-ios-is-not-possible-on-windows", "heading": "Android only. iOS is not possible on Windows.", "path": "docs/WINDOWS.md", "excerpt": "Said here rather than in a footnote, because it is the first question anyone asks and the answer is structural rather than a gap in the work. Mobium drives iOS through `xcrun simctl` — 41 call sites in `internal/device` alone — and through WebDriverAgent, which it installs as the prebuilt `WebDriverAgentRunner-Build-Sim-arm64.zip`. `simctl` ships inside Xcode and Xcode is macOS-only; the artifact is a *simulator* bui…", "gold": true}, {"id": "docs/ROADMAP.md#under-consideration", "heading": "Under consideration", "path": "docs/ROADMAP.md", "excerpt": "- **Locators for when there is no ref** (written down 2026-10-12). A ref from `map` lasts one map, so an agent has one and a `mobium test` file does not: a hand-written test has the flat `kind=value` locators — text, label, testid, role, class, path, narrowed by `,role=` — which match one element or are refused. That is right on a form and leaves nothing durable on a list. Every Ice Cubes post has a \"…\" (CHALLENGES 2…", "gold": false}, {"id": "tests/README.md#tests", "heading": "Tests", "path": "tests/README.md", "excerpt": "Mobium's own tests of MobiumApp, run by `mobium test` — and the suite that holds the runner to its word. The format is in the [test runner guide](../docs/guides/test-runner.md). ```sh cd tests mobium test --project android # emulator-5554 MOBIUM_IOS_DEVICE=<simulator-udid> mobium test # and an iOS simulator mobium test --reporter list,junit,html && mobium show-report mobium test --ui --open # pick, run and watch on a…", "gold": false}, {"id": "skills/mobile-check/SKILL.md#mobium-mobile-automation-cli-reference", "heading": "Mobium Mobile Automation — CLI Reference", "path": "skills/mobile-check/SKILL.md", "excerpt": "The `mobium` CLI automates **mobile apps** on Android emulators and phones, and iOS simulators and iPhones. A background daemon keeps the device session alive between commands, so each command is fast after the first. ``` mobium launch com.example.shop && mobium map && mobium tap @e5 && mobium map ``` What the app is built with decides how to reach it: | App type | How | | --- | --- | | Native (Android SDK, Jetpack C…", "gold": false}], "missed": false, "facts": ["Since 2026-10-22 an Android emulator and a phone have been driven from a Windows laptop through mobium mcp, the CLI and all five clients, but Windows is not yet declared supported. ⟦2026-10-22⟧", "iOS is not possible on Windows: Mobium drives iOS through xcrun simctl and WebDriverAgent built with Xcode, which is macOS-only. ⟦macOS-only⟧", "What is left before support is the checks a person at the machine runs and seven checks whose failures are not yet explained. ⟦not yet explained⟧"], "concern": "docs/quickstart/README.md#where-it-runs still says no emulator or phone has been driven from Windows, which README.md and WINDOWS.md contradict since #270/#271; the quick-start table is stale.", "check": "Claude's reading: Windows-specific code (named-pipe daemon, Detach, process path) is in internal/device/*_windows.go and builds for windows/amd64; iOS paths call xcrun throughout internal/device. README.md#platforms~2 restates the status in brief and will likely be retrieved; the stale quick-start table is a hard negative. Verified in: internal/device/detach_windows.go:21-27, internal/device/procpath_windows.go:8, internal/device/simctl.go:282."}, {"id": "g008", "kind": "fact", "question": "In Git Bash on Windows, pushing a file to /data/local/tmp on my Android device fails because Mobium sees the path as 'C:/Program Files/Git/data/local/tmp/x'. How do I fix it?", "tags": ["troubleshooting", "test-author", "new since 7b590a4"], "gold": [{"id": "docs/WINDOWS.md#also-expected-unverified", "heading": "Also expected, unverified", "path": "docs/WINDOWS.md", "excerpt": "- **iOS is macOS-only.** `simctl` does not exist on Windows. `mobium devices` should report that as a note rather than an error — the code path already does this for a missing toolchain, but it has never been exercised with Xcode genuinely absent on a non-Mac. - Paths in `app_install` and `screenshot -o` take Windows separators; nothing obviously assumes `/`, but nothing has tested it either. - **Git Bash rewrites a …"}], "retrieved": [{"id": "CHALLENGES#361", "heading": "361. In Git Bash, a device path was rewritten into a Windows one, and refused as not absolute", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** `device-paths.sh` and `network.sh` on the Windows laptop, run under Git Bash. `mobium shell --upload x /data/local/tmp/x` answered `\"C:/Program Files/Git/data/local/tmp/x\" is not an absolute path`, and its remedy — give an absolute path — was the one the caller had given. Git Bash rewrites any argument that starts with `/` into a path under its own install folder before a Windows program sees it, measur…", "gold": false}, {"id": "docs/SETUP.md#what-mobium-installs-and-removing-it", "heading": "What Mobium installs, and removing it", "path": "docs/SETUP.md", "excerpt": "On the machine, under `~/.mobium`: | | | | --- | --- | | `uiautomator2/`, `webdriveragent/` | pinned, checksummed device agents, ~40MB, downloaded on first use | | `webdriveragent-device/` | WebDriverAgent's pinned source and one signed build per team and phone, ~150MB — only once a real iPhone has been driven | | `daemon/` | socket and PID file, removed on shutdown | On an **Android** device, the default backend ins…", "gold": false}, {"id": "docs/WINDOWS.md#also-expected-unverified", "heading": "Also expected, unverified", "path": "docs/WINDOWS.md", "excerpt": "- **iOS is macOS-only.** `simctl` does not exist on Windows. `mobium devices` should report that as a note rather than an error — the code path already does this for a missing toolchain, but it has never been exercised with Xcode genuinely absent on a non-Mac. - Paths in `app_install` and `screenshot -o` take Windows separators; nothing obviously assumes `/`, but nothing has tested it either. - **Git Bash rewrites a …", "gold": true}, {"id": "docs/RELEASE-CHECKLIST.md#android-a-booted-pixel-7-avd", "heading": "Android — a booted Pixel 7 AVD", "path": "docs/RELEASE-CHECKLIST.md", "excerpt": "Setup is in [SETUP.md](SETUP.md), or [WINDOWS.md](WINDOWS.md) for Windows. Start the emulator, then `mobium daemon stop` so nothing serves a stale build. - [ ] `mobium devices` lists the emulator - [ ] `mobium map` on the launcher returns app icons as `button`, not `link` - [ ] `mobium launch com.android.settings && mobium tap \"text=Network & internet\"` with **no sleep between them** — the implicit wait is what makes…", "gold": false}, {"id": "skills/mobile-check/SKILL.md#files", "heading": "Files", "path": "skills/mobile-check/SKILL.md", "excerpt": "```sh mobium upload invoice.pdf # where a file picker looks mobium download report.csv # what the app saved there mobium upload ./seed --device-path /data/local/tmp/seed # Android, any shell path mobium download --app com.example.shop --device-path databases/shop.db # its private data mobium download --app com.example.Shop --device-path Library/Caches -o caches # iOS container ``` - Without `--device-path` a file goe…", "gold": false}], "missed": false, "facts": ["Git Bash rewrites any argument that starts with / into a path under Git's own folder before mobium sees it, and Mobium refuses such a path naming the rewrite. ⟦Git Bash⟧", "Set MSYS2_ARG_CONV_EXCL=\"/data/;/sdcard/\" to leave device paths alone (MSYS_NO_PATHCONV=1 stops every conversion), or run from PowerShell or cmd, which never rewrite. ⟦MSYS2_ARG_CONV_EXCL ; PowerShell⟧"], "concern": "", "check": "Claude's reading: CheckDevicePath refuses a path starting with a drive letter as a Git Bash rewrite and its remedy names MSYS2_ARG_CONV_EXCL, MSYS_NO_PATHCONV=1 and PowerShell or cmd (paths.go:126-135). CHALLENGES#361 tells the same story and is a near-equal answer. Verified in: internal/device/paths.go:126-135."}, {"id": "g009", "kind": "fact", "question": "On Windows, does a Mobium daemon that started inside an SSH session keep running after I disconnect, and what makes that work?", "tags": ["behavior", "ci-engineer", "new since 7b590a4"], "gold": [{"id": "docs/WINDOWS.md#4-devicedetach-internaldevicedetachwindowsgo-and-detachunixgo", "heading": "4. `device.Detach` — `internal/device/detach_windows.go` (and `detach_unix.go`)", "path": "docs/WINDOWS.md", "excerpt": "`CREATE_NEW_PROCESS_GROUP | DETACHED_PROCESS`: a Ctrl-C does not reach the daemon, and with no console it does not die when the terminal window closes. Neither leaves a job object, and Windows' OpenSSH server kills every process of a session's job when the session ends, so `Detach` also adds `CREATE_BREAKAWAY_FROM_JOB` when the job allows it — measured over SSH on a Windows 11 laptop, where the daemon otherwise died …"}], "retrieved": [{"id": "CHALLENGES#359", "heading": "359. On Windows, the daemon died with the SSH session that started it", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** the first device run from Windows, a Windows 11 laptop driven from a Mac over OpenSSH. Every command in one session reused the daemon; the next session found \"Daemon is not running\" and no `mobium` process. The SSH server runs each session in a job object with `KILL_ON_JOB_CLOSE` (limit flags `0x2800`), and `DETACHED_PROCESS` leaves the console, not the job, so ending the session ended the daemon — and …", "gold": false}, {"id": "docs/guides/cli.md#8-the-daemon-and-running-several-at-once", "heading": "8. The daemon, and running several at once", "path": "docs/guides/cli.md", "excerpt": "The first command starts a daemon in the background, which holds the device sessions and the refs between commands, and exits after 30 idle minutes: ``` $ mobium daemon status Daemon running (pid 4156, up 8s) version 0.1.0-dev socket ~/.mobium/daemon/mobium.sock ``` (The home directory is shortened to `~` here and below.) One daemon serves one call at a time. Two runs at once — two terminals, two CI jobs, two devices…", "gold": false}, {"id": "docs/SHUTDOWN.md#1-mobium-daemon-stop-always-first", "heading": "1. `mobium daemon stop`, always first", "path": "docs/SHUTDOWN.md", "excerpt": "The daemon owns the device-side sessions: a UiAutomator2 server running as instrumentation on Android, a WebDriverAgent process on an iOS simulator. Stopping it tells both to shut down. On an iOS simulator the next session starts on the home screen, whatever app was in front: WebDriverAgent's runner takes the foreground as it launches and leaves it to the home screen. The first command says so and names `app_launch` …", "gold": false}, {"id": "CHALLENGES#28", "heading": "28. `mobium daemon stop` returned before the daemon stopped", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** hitting it three times while doing other work, then reproducing it deliberately instead of retrying past it. `daemon stop` sent the shutdown request and returned as soon as it was acknowledged, while the daemon was still tearing down — closing a UiAutomator2 session takes about a second. The next command's auto-start then found the socket still held, failed to bind, and sat waiting ten seconds for a dae…", "gold": false}], "missed": true, "facts": ["Windows' OpenSSH server kills every process in a session's job when the session ends, which used to take the daemon with it. ⟦OpenSSH⟧", "Detach now adds CREATE_BREAKAWAY_FROM_JOB when the job allows breakaway, so the daemon outlives the session. ⟦CREATE_BREAKAWAY_FROM_JOB⟧"], "concern": "", "check": "Claude's reading: Detach sets CREATE_NEW_PROCESS_GROUP|DETACHED_PROCESS and adds CREATE_BREAKAWAY_FROM_JOB only when JOB_OBJECT_LIMIT_BREAKAWAY_OK is set (detach_windows.go:21-40); the auto-started daemon goes through it (daemon_client.go:119). CHALLENGES#359 is the defect behind it and an equally good source. Verified in: internal/device/detach_windows.go:13-40, cmd/mobium/daemon_client.go:114-119."}, {"id": "g010", "kind": "multi", "question": "My Android emulator on a Windows host has frozen: adb still lists it but every shell call times out. Will mobium shutdown end it, and how?", "tags": ["behavior", "test-author", "new since 7b590a4"], "gold": [{"id": "docs/SHUTDOWN.md#2-simulators-then-emulators", "heading": "2. Simulators, then emulators", "path": "docs/SHUTDOWN.md", "excerpt": "```sh xcrun simctl shutdown <udid> # or `all` adb -s emulator-5554 emu kill ``` `mobium shutdown <serial | avd | udid | simulator>` does this for one device in the same order — its session ended, then the device — and returns once the device is gone. It ends only its own daemon's session and does not check for other daemons on the device, so stop those first (`MOBIUM_SESSION=<name> mobium daemon stop` for each). A **…"}, {"id": "CHALLENGES#360", "heading": "360. On Windows, a frozen emulator could not be shut down, and the error said to shut it down", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** a sweep of the checks on the Windows laptop's emulator, which froze under `network.sh` twice — adb listed it as `device` and every shell call timed out. Every check after it was refused as \"not answering adb\", and the refusal's remedy was 285's: `mobium shutdown emulator-5554`. On Windows that answered \"ending an emulator by its process is not done on Windows\", and `boot.sh`, which shuts its AVD down fi…"}], "retrieved": [{"id": "CHALLENGES#360", "heading": "360. On Windows, a frozen emulator could not be shut down, and the error said to shut it down", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** a sweep of the checks on the Windows laptop's emulator, which froze under `network.sh` twice — adb listed it as `device` and every shell call timed out. Every check after it was refused as \"not answering adb\", and the refusal's remedy was 285's: `mobium shutdown emulator-5554`. On Windows that answered \"ending an emulator by its process is not done on Windows\", and `boot.sh`, which shuts its AVD down fi…", "gold": true}, {"id": "CHALLENGES#285", "heading": "285. A frozen emulator was told to try the other driver, and could not be shut down", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** the lead 284 left. An emulator stopped with SIGSTOP timed out on `adb shell` as a session opened, and the error added \"To run without the UiAutomator2 server, use --driver uiautomator\" — a driver that goes through the same adb. The remedy that would help, a restart, did not work either: `mobium shutdown` on the frozen emulator ran six minutes and ended \"read response: i/o timeout\" with the emulator stil…", "gold": false}, {"id": "docs/SHUTDOWN.md#2-simulators-then-emulators", "heading": "2. Simulators, then emulators", "path": "docs/SHUTDOWN.md", "excerpt": "```sh xcrun simctl shutdown <udid> # or `all` adb -s emulator-5554 emu kill ``` `mobium shutdown <serial | avd | udid | simulator>` does this for one device in the same order — its session ended, then the device — and returns once the device is gone. It ends only its own daemon's session and does not check for other daemons on the device, so stop those first (`MOBIUM_SESSION=<name> mobium daemon stop` for each). A **…", "gold": true}, {"id": "docs/WINDOWS.md#windows-support", "heading": "Windows support", "path": "docs/WINDOWS.md", "excerpt": "**Status: devices driven from Windows since 2026-10-22; not yet declared supported.** On a Windows 11 laptop (24H2, i7-8565U, 8 GB), an Android 15 emulator and a Pixel 8 Pro over USB were driven through `mobium mcp`, the CLI over the named pipe, and all five clients, which passed every step on both. A sweep of the checks on the emulator found six things, all fixed: the daemon dying with the SSH session that started i…", "gold": false}, {"id": "CHALLENGES#93", "heading": "93. Every Android session ended by leaving a crash report on the device", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** `app_crashes` itself, run on a Pixel 8 Pro (Android 17) while hardening it: of the phone's recorded crashes, most were `io.appium.uiautomator2.server` — `RuntimeException: Error while disconnecting UiAutomation`, caused by `DeadObjectException` — each one at the moment a Mobium session had ended. Teardown cancelled the host of `adb shell am instrument`, which takes the UiAutomation connection down with …", "gold": false}], "missed": false, "facts": ["mobium shutdown gives adb emu kill ten seconds, then ends the process the emulator's discovery file names once that process is an emulator by name. ⟦discovery file⟧", "On Windows this now works too: the process is read with QueryFullProcessImageName and ended, where it used to be refused. ⟦QueryFullProcessImageName⟧"], "concern": "docs/SHUTDOWN.md#2-simulators-then-emulators still ends with 'On Windows it does not end the process, and says so', but #268 (CHALLENGES 360) made killEmulatorProcess work on Windows (boot.go:400-428, procpath_windows.go); SHUTDOWN.md is stale.", "check": "Claude's reading: emuKillWait is 10s (boot.go:32) and killEmulatorProcess ends the discovery file's pid when its image name contains qemu or emulator, on every OS (boot.go:400-428). The SHUTDOWN.md section gives the mechanism and CHALLENGES 360 gives Windows; a right answer must say it works on Windows despite the stale line. Verified in: internal/device/boot.go:32, internal/device/boot.go:250-270, internal/device/boot.go:400-428, internal/device/procpath_windows.go:8-20."}, {"id": "g011", "kind": "multi", "question": "I run two Android emulators at once on one machine and want a test run on each in parallel without the two slowing each other down. How do I set that up?", "tags": ["how-to", "ci-engineer"], "gold": [{"id": "docs/SETUP.md#running-two-at-once", "heading": "Running two at once", "path": "docs/SETUP.md", "excerpt": "```sh emulator -avd mobium-test -no-snapshot-save -no-boot-anim & # 5554 emulator -avd mobium-test-17 -no-snapshot-save -no-boot-anim -port 5556 & # 5556 ``` Then pass `--device emulator-5556` to every command, or give a client the device option. With two ready, a call that names no device is refused, so `MOBIUM_SESSION` alone does not choose one: it gives each run its own daemon ([parallel runs](#parallel-runs)), an…"}, {"id": "docs/SETUP.md#parallel-runs", "heading": "Parallel runs", "path": "docs/SETUP.md", "excerpt": "**Give each run that drives a device at the same time as another its own daemon.** One daemon serves one call at a time, across every device it holds, so two runs sharing one go at the pace of the slower device. Measured on 2026-09-27, 15 `map` calls on each of an Android 15 emulator and an iPhone 17 Pro simulator at once: | | the emulator's 15 calls | | --- | --- | | alone | 0.3s | | sharing a daemon with the simula…"}], "retrieved": [{"id": "docs/SETUP.md#running-two-at-once", "heading": "Running two at once", "path": "docs/SETUP.md", "excerpt": "```sh emulator -avd mobium-test -no-snapshot-save -no-boot-anim & # 5554 emulator -avd mobium-test-17 -no-snapshot-save -no-boot-anim -port 5556 & # 5556 ``` Then pass `--device emulator-5556` to every command, or give a client the device option. With two ready, a call that names no device is refused, so `MOBIUM_SESSION` alone does not choose one: it gives each run its own daemon ([parallel runs](#parallel-runs)), an…", "gold": true}, {"id": "docs/SETUP.md#parallel-runs", "heading": "Parallel runs", "path": "docs/SETUP.md", "excerpt": "**Give each run that drives a device at the same time as another its own daemon.** One daemon serves one call at a time, across every device it holds, so two runs sharing one go at the pace of the slower device. Measured on 2026-09-27, 15 `map` calls on each of an Android 15 emulator and an iPhone 17 Pro simulator at once: | | the emulator's 15 calls | | --- | --- | | alone | 0.3s | | sharing a daemon with the simula…", "gold": true}, {"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": false}, {"id": "docs/guides/test-runner.md#6-more-than-one-device", "heading": "6. More than one device", "path": "docs/guides/test-runner.md", "excerpt": "Add a project per device. An iOS simulator's id is one Mac's, and a phone's is somebody's, so a project can take its device from the environment, and an unset variable is refused by name before any test runs: ```json { \"testDir\": \"tests\", \"projects\": [ {\"name\": \"android\", \"device\": \"emulator-5554\"}, {\"name\": \"ios\", \"device\": \"${MOBIUM_IOS_DEVICE}\", \"driver\": \"wda\"} ] } ``` ```sh MOBIUM_IOS_DEVICE=<simulator-udid> mob…", "gold": false}, {"id": "docs/ROADMAP.md#under-consideration", "heading": "Under consideration", "path": "docs/ROADMAP.md", "excerpt": "- **Locators for when there is no ref** (written down 2026-10-12). A ref from `map` lasts one map, so an agent has one and a `mobium test` file does not: a hand-written test has the flat `kind=value` locators — text, label, testid, role, class, path, narrowed by `,role=` — which match one element or are refused. That is right on a form and leaves nothing durable on a list. Every Ice Cubes post has a \"…\" (CHALLENGES 2…", "gold": false}], "missed": false, "facts": ["With two devices ready, a call that names no device is refused, so each run names its device with --device (or the client's device option); a second emulator gets its own console port with -port 5556. ⟦-port 5556⟧", "Give each run its own daemon by naming it with MOBIUM_SESSION, since one daemon serves one call at a time across every device it holds. ⟦MOBIUM_SESSION⟧", "Keep the session name short: it is part of a socket path capped at about 104 bytes. ⟦104⟧"], "concern": "", "check": "Claude's reading: adb.go:429 refuses with 'N devices are ready — pick one with --device'; the daemon serializes handlers with one mutex (daemon.go:30); paths.go names the socket from MOBIUM_SESSION and guards the 104-byte limit. docs/guides/cli.md#8 also explains MOBIUM_SESSION and is a near miss. Verified in: internal/device/adb.go:429, internal/daemon/daemon.go:30, internal/paths/paths.go:44-48, internal/paths/paths.go:77."}, {"id": "g012", "kind": "fact", "question": "If I leave Mobium alone for a while, does the background process it started keep running forever?", "tags": ["behavior", "new-user"], "gold": [{"id": "docs/guides/cli.md#8-the-daemon-and-running-several-at-once", "heading": "8. The daemon, and running several at once", "path": "docs/guides/cli.md", "excerpt": "The first command starts a daemon in the background, which holds the device sessions and the refs between commands, and exits after 30 idle minutes: ``` $ mobium daemon status Daemon running (pid 4156, up 8s) version 0.1.0-dev socket ~/.mobium/daemon/mobium.sock ``` (The home directory is shortened to `~` here and below.) One daemon serves one call at a time. Two runs at once — two terminals, two CI jobs, two devices…"}], "retrieved": [{"id": "docs/SHUTDOWN.md#1-mobium-daemon-stop-always-first", "heading": "1. `mobium daemon stop`, always first", "path": "docs/SHUTDOWN.md", "excerpt": "The daemon owns the device-side sessions: a UiAutomator2 server running as instrumentation on Android, a WebDriverAgent process on an iOS simulator. Stopping it tells both to shut down. On an iOS simulator the next session starts on the home screen, whatever app was in front: WebDriverAgent's runner takes the foreground as it launches and leaves it to the home screen. The first command says so and names `app_launch` …", "gold": false}, {"id": "docs/SHUTDOWN.md#a-leak-this-actually-caught", "heading": "A leak this actually caught", "path": "docs/SHUTDOWN.md", "excerpt": "A backgrounded wait loop of mine — `until adb shell getprop ...` against two attached devices, so it could never succeed — was still spinning `sleep 3` forty-two minutes later. It was reported as a *second daemon*, because its command line contained `bin/mobium daemon stop`. Two lessons in one process: a loop waiting on a condition that cannot be met runs forever, and a check matching command-line text will find your…", "gold": false}, {"id": "docs/SHUTDOWN.md#what-to-leave-alone", "heading": "What to leave alone", "path": "docs/SHUTDOWN.md", "excerpt": "- **`~/.mobium/uiautomator2` and `~/.mobium/webdriveragent`** — about 40MB of pinned, checksummed agents. Deleting them only costs the next run a download. - **A physical device.** Releasing the session is enough; unplugging is yours. USB and wireless debugging stay on until you turn them off — a network device's link is ended by `--quit`, its debugging setting is not. - **Anything you did not start.** Check what a p…", "gold": false}, {"id": "docs/guides/graybox.md#when-the-app-is-not-waited-for", "heading": "When the app is not waited for", "path": "docs/guides/graybox.md", "excerpt": "Three things end a wait early, and the result says which, so a check that did not run never reads as one that passed: - **The app went to the background.** The library says `away` and `back`; while the app is away, an action elsewhere is not held up by it. - **The app stopped saying it is busy.** Busy is a lease: while work is in flight the library restates the count every half second, from a native timer that a busy…", "gold": false}, {"id": "docs/guides/cli.md#8-the-daemon-and-running-several-at-once", "heading": "8. The daemon, and running several at once", "path": "docs/guides/cli.md", "excerpt": "The first command starts a daemon in the background, which holds the device sessions and the refs between commands, and exits after 30 idle minutes: ``` $ mobium daemon status Daemon running (pid 4156, up 8s) version 0.1.0-dev socket ~/.mobium/daemon/mobium.sock ``` (The home directory is shortened to `~` here and below.) One daemon serves one call at a time. Two runs at once — two terminals, two CI jobs, two devices…", "gold": true}], "missed": false, "facts": ["The first command starts a daemon in the background that holds the device sessions and refs, and it exits after 30 idle minutes. ⟦30 idle minutes⟧", "mobium daemon stop stops it, ending its sessions."], "concern": "", "check": "Claude's reading: the auto-start passes --idle-timeout 30m (daemon_client.go:19, 114) and watchIdle shuts the daemon down after that (daemon.go:184-210). The question avoids the word daemon on purpose. Verified in: cmd/mobium/daemon_client.go:16-19, cmd/mobium/daemon_client.go:114, internal/daemon/daemon.go:184-210."}, {"id": "g013", "kind": "multi", "question": "I have two lab Macs with emulators on them. How do I spread my test runs across both machines' devices, and what does each lab Mac need for that?", "tags": ["how-to", "ci-engineer"], "gold": [{"id": "docs/guides/grid.md#2-a-grid", "heading": "2. A grid", "path": "docs/guides/grid.md", "excerpt": "`MOBIUM_GRID=node1,node2` names the nodes. At a run's first call, mobium asks each node for its devices and which are held, takes the first free one that matches what the run asked for, and connects to its node as `--remote` would. `mobium grid status` shows the same answers routing reads: ``` $ MOBIUM_GRID=localhost mobium grid status NODE DEVICE PLATFORM OS MODEL STATE HELD BY localhost emulator-5554 android Androi…"}, {"id": "docs/guides/grid.md#what-a-node-needs", "heading": "What a node needs", "path": "docs/guides/grid.md", "excerpt": "A node is any Mac or Linux machine with devices and mobium on it. | | | | --- | --- | | **SSH without a prompt** | key-based login from your machine to the node. mobium runs SSH with `BatchMode=yes`, since a password prompt would land in the stream a client speaks. `MOBIUM_SSH` replaces the `ssh` command, options and all — `ssh -i ~/.ssh/node_key` | | **mobium on the node** | reachable by the node's non-interactive s…"}], "retrieved": [{"id": "docs/guides/grid.md#quick-start-another-machines-devices-and-a-grid", "heading": "Quick start: another machine's devices, and a grid", "path": "docs/guides/grid.md", "excerpt": "Two steps, the second built on the first: - **`--remote`** drives the devices plugged into one other machine, over SSH — with any command and any client, and no change to its code. - **`MOBIUM_GRID`** spreads runs over several machines' devices, with no hub: each run gets the first free device that matches, and waits when there is none. Every command and every line of output below is what mobium printed on 2026-09-28…", "gold": false}, {"id": "docs/guides/test-runner.md#6-more-than-one-device", "heading": "6. More than one device", "path": "docs/guides/test-runner.md", "excerpt": "Add a project per device. An iOS simulator's id is one Mac's, and a phone's is somebody's, so a project can take its device from the environment, and an unset variable is refused by name before any test runs: ```json { \"testDir\": \"tests\", \"projects\": [ {\"name\": \"android\", \"device\": \"emulator-5554\"}, {\"name\": \"ios\", \"device\": \"${MOBIUM_IOS_DEVICE}\", \"driver\": \"wda\"} ] } ``` ```sh MOBIUM_IOS_DEVICE=<simulator-udid> mob…", "gold": false}, {"id": "docs/ROADMAP.md#under-consideration", "heading": "Under consideration", "path": "docs/ROADMAP.md", "excerpt": "- **Locators for when there is no ref** (written down 2026-10-12). A ref from `map` lasts one map, so an agent has one and a `mobium test` file does not: a hand-written test has the flat `kind=value` locators — text, label, testid, role, class, path, narrowed by `,role=` — which match one element or are refused. That is right on a form and leaves nothing durable on a list. Every Ice Cubes post has a \"…\" (CHALLENGES 2…", "gold": false}, {"id": "docs/SETUP.md#running-two-at-once", "heading": "Running two at once", "path": "docs/SETUP.md", "excerpt": "```sh emulator -avd mobium-test -no-snapshot-save -no-boot-anim & # 5554 emulator -avd mobium-test-17 -no-snapshot-save -no-boot-anim -port 5556 & # 5556 ``` Then pass `--device emulator-5556` to every command, or give a client the device option. With two ready, a call that names no device is refused, so `MOBIUM_SESSION` alone does not choose one: it gives each run its own daemon ([parallel runs](#parallel-runs)), an…", "gold": false}, {"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": false}], "missed": true, "facts": ["Set MOBIUM_GRID=node1,node2; at a run's first call mobium asks each node for its devices and takes the first free one that matches. ⟦MOBIUM_GRID⟧", "Each node needs key-based SSH with no prompt (mobium runs SSH with BatchMode=yes) and mobium reachable by its non-interactive shell, set with MOBIUM_REMOTE_BIN if needed. ⟦BatchMode=yes ; MOBIUM_REMOTE_BIN⟧", "On a Mac node, Remote Login must be on. ⟦Remote Login⟧"], "concern": "", "check": "Claude's reading: grid.go splits MOBIUM_GRID on commas and remote.go adds -o BatchMode=yes and honors MOBIUM_SSH and MOBIUM_REMOTE_BIN. SETUP.md#a-grid and SETUP.md#driving-another-machines-devices say most of this too; Remote Login is only in the grid guide. Verified in: cmd/mobium/grid.go:23-40, cmd/mobium/remote.go:151-162, cmd/mobium/remote.go:183-186."}, {"id": "g014", "kind": "fact", "question": "A teammate's phone is plugged into one of our grid machines. Could a grid test run end up installing and tapping on it?", "tags": ["behavior", "ci-engineer"], "gold": [{"id": "docs/guides/grid.md#phones-on-a-grid", "heading": "Phones on a grid", "path": "docs/guides/grid.md", "excerpt": "A phone plugged into a node is usually somebody's, and a grid run would install on it, tap and change its settings. So the grid lends a physical device only when **the node's own** environment sets `MOBIUM_GRID_PHONES=1` — the node's choice, never the caller's. Until then a phone is listed as not offered, as above, and a run that asks for it by serial is told so. What a grid shows about a phone is its model, never it…"}], "retrieved": [{"id": "docs/guides/grid.md#phones-on-a-grid", "heading": "Phones on a grid", "path": "docs/guides/grid.md", "excerpt": "A phone plugged into a node is usually somebody's, and a grid run would install on it, tap and change its settings. So the grid lends a physical device only when **the node's own** environment sets `MOBIUM_GRID_PHONES=1` — the node's choice, never the caller's. Until then a phone is listed as not offered, as above, and a run that asks for it by serial is told so. What a grid shows about a phone is its model, never it…", "gold": true}, {"id": "docs/SETUP.md#a-grid", "heading": "A grid", "path": "docs/SETUP.md", "excerpt": "**`MOBIUM_GRID=node1,node2` spreads runs over several machines' devices**, with no hub. At a run's first call — which is where it says what it wants: a serial, or `platform` when it starts a session — mobium asks every node over SSH for its devices and which of them are held, takes the first free one that matches, and connects to its node as `--remote` would. The lease that keeps a device to one run lives on the node…", "gold": false}, {"id": "docs/guides/grid.md#quick-start-another-machines-devices-and-a-grid", "heading": "Quick start: another machine's devices, and a grid", "path": "docs/guides/grid.md", "excerpt": "Two steps, the second built on the first: - **`--remote`** drives the devices plugged into one other machine, over SSH — with any command and any client, and no change to its code. - **`MOBIUM_GRID`** spreads runs over several machines' devices, with no hub: each run gets the first free device that matches, and waits when there is none. Every command and every line of output below is what mobium printed on 2026-09-28…", "gold": false}, {"id": "docs/guides/grid.md#4-tests-on-a-grid", "heading": "4. Tests on a grid", "path": "docs/guides/grid.md", "excerpt": "`mobium test` goes through a grid the same way. A project that names no device asks for one by `platform`, and with `MOBIUM_GRID` set each project gets a connection of its own, which leases a device before any test runs and releases it when the run ends: ```json { \"testDir\": \"tests\", \"projects\": [ {\"name\": \"android-a\", \"platform\": \"android\"}, {\"name\": \"android-b\", \"platform\": \"android\"} ] } ``` ``` $ MOBIUM_GRID=loca…", "gold": false}, {"id": "docs/guides/grid.md#what-stays-local", "heading": "What stays local", "path": "docs/guides/grid.md", "excerpt": "`daemon`, `doctor` and `mcp` are about this machine and ignore `--remote`. One device still belongs to one run at a time, on a node as anywhere: a test run holds each project's device for the whole run, so a grid with two free devices serves two projects at once, not more.", "gold": false}], "missed": false, "facts": ["The grid lends a physical device only when the node's own environment sets MOBIUM_GRID_PHONES=1, the node's choice, never the caller's; until then it is listed as not offered. ⟦MOBIUM_GRID_PHONES=1⟧", "A grid shows a phone's model, never its name."], "concern": "", "check": "Claude's reading: grid.go marks a device Offered only if it is an emulator/simulator or the node's MOBIUM_GRID_PHONES is 1 (line 96) and tells a run asking for one so (line 211). SETUP.md#a-grid~1 also covers phones but not the model-not-name point. Verified in: cmd/mobium/grid.go:60-96, cmd/mobium/grid.go:211."}, {"id": "g015", "kind": "fact", "question": "How do I connect my Fire TV so Mobium can drive it over Wi-Fi from my Mac, and what do I do when adb connect says \"No route to host\" although the TV answers ping?", "tags": ["how-to", "new-user"], "gold": [{"id": "docs/SETUP.md#over-wi-fi", "heading": "Over Wi-Fi", "path": "docs/SETUP.md", "excerpt": "Android 11+. The phone and the Mac must be on the same network. 1. **Developer options → Wireless debugging → on.** 2. **\"Pair device with pairing code\"** — it shows an address and a six-digit code. Both expire in about a minute. 3. Find the address without reading it off the screen: ```sh adb mdns services # adb-3C19...-FIOvFv _adb-tls-pairing._tcp 10.0.0.96:33169 # adb-3C19...-FIOvFv _adb-tls-connect._tcp 10.0.0.96…"}], "retrieved": [{"id": "docs/SETUP.md#over-wi-fi", "heading": "Over Wi-Fi", "path": "docs/SETUP.md", "excerpt": "Android 11+. The phone and the Mac must be on the same network. 1. **Developer options → Wireless debugging → on.** 2. **\"Pair device with pairing code\"** — it shows an address and a six-digit code. Both expire in about a minute. 3. Find the address without reading it off the screen: ```sh adb mdns services # adb-3C19...-FIOvFv _adb-tls-pairing._tcp 10.0.0.96:33169 # adb-3C19...-FIOvFv _adb-tls-connect._tcp 10.0.0.96…", "gold": true}, {"id": "docs/SHUTDOWN.md#a-tv-or-anything-reached-by-adb-connect", "heading": "A TV, or anything reached by `adb connect`", "path": "docs/SHUTDOWN.md", "excerpt": "A Fire TV is reached over Wi-Fi with `adb connect <tv>:5555`, after ADB debugging is turned on in its Developer Options. It is somebody's living-room TV, so the device checks above run on it as on a phone, and four more run on every device: - **A screen mirror's server.** scrcpy was how the TV was watched while it was measured, and its server streams the screen off the device for as long as it runs. On the device it …", "gold": false}, {"id": "docs/ROADMAP.md#under-consideration", "heading": "Under consideration", "path": "docs/ROADMAP.md", "excerpt": "- **Locators for when there is no ref** (written down 2026-10-12). A ref from `map` lasts one map, so an agent has one and a `mobium test` file does not: a hand-written test has the flat `kind=value` locators — text, label, testid, role, class, path, narrowed by `,role=` — which match one element or are refused. That is right on a form and leaves nothing durable on a list. Every Ice Cubes post has a \"…\" (CHALLENGES 2…", "gold": false}], "missed": false, "facts": ["Turn on ADB Debugging in the Fire TV's Developer Options (shown under Settings > Device & Software after selecting the device name seven times in About), then run adb connect <tv>:5555 with the TV's IPv4 address and accept the prompt on the TV; a Fire TV has no pairing step. ⟦ADB Debugging ; 5555⟧", "\"No route to host\" while ping works is macOS Local Network privacy silently blocking an adb server that a background process started; run adb kill-server && adb connect <tv>:5555 from a Terminal window so macOS asks, and allow it. ⟦Local Network ; adb kill-server⟧"], "concern": "", "check": "Claude's reading: replaces a draft that duplicated g074 (simulator audio setup). Both facts are in SETUP.md#over-wi-fi; the Local Network trap is macOS behavior, measured on the Fire TV and recorded in the doc, not something the code can show, and the code's own part is the disconnect-then-connect before it reports a network device missing (internal/device/adb.go:358). SHUTDOWN.md's TV section repeats the trap and could also count. Verified in: internal/device/adb.go:358."}, {"id": "g016", "kind": "fact", "question": "How do I set up an Apple TV simulator for Mobium, and how do I move around in it given that it has no touch screen?", "tags": ["how-to", "test-author"], "gold": [{"id": "docs/SETUP.md#an-apple-tv-simulator", "heading": "An Apple TV simulator", "path": "docs/SETUP.md", "excerpt": "Verified on a tvOS 26.5 simulator (Apple TV 4K, 3rd generation, at 1080p) with Xcode 26.6, on 2026-10-09. The tvOS platform is a separate download: ```sh xcodebuild -downloadPlatform tvOS # or Xcode > Settings > Components xcrun simctl create \"Apple TV\" \\ com.apple.CoreSimulator.SimDeviceType.Apple-TV-4K-3rd-generation-1080p \\ com.apple.CoreSimulator.SimRuntime.tvOS-26-5 xcrun simctl boot <udid> && open -a Simulator …"}], "retrieved": [{"id": "docs/SETUP.md#an-apple-tv-simulator", "heading": "An Apple TV simulator", "path": "docs/SETUP.md", "excerpt": "Verified on a tvOS 26.5 simulator (Apple TV 4K, 3rd generation, at 1080p) with Xcode 26.6, on 2026-10-09. The tvOS platform is a separate download: ```sh xcodebuild -downloadPlatform tvOS # or Xcode > Settings > Components xcrun simctl create \"Apple TV\" \\ com.apple.CoreSimulator.SimDeviceType.Apple-TV-4K-3rd-generation-1080p \\ com.apple.CoreSimulator.SimRuntime.tvOS-26-5 xcrun simctl boot <udid> && open -a Simulator …", "gold": true}, {"id": "CHALLENGES#296", "heading": "296. On an Apple TV the runner kept the screen, and every press went to it", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** the first Apple TV simulator session (tvOS 26.5), 2026-10-09. The first daemon's launch put MobiumTV in front and every press worked. After a daemon restart `current` named WebDriverAgent's own runner, `map` found nothing, and two D-pad presses reported that nothing on screen had focus: tvOS's runner answers from the foreground and stays there, as an iPad's does before it answers at all (147). Home, pre…", "gold": false}, {"id": "docs/RELEASE-CHECKLIST.md#ios-a-booted-iphone-simulator", "heading": "iOS — a booted iPhone simulator", "path": "docs/RELEASE-CHECKLIST.md", "excerpt": "- [ ] `mobium --driver wda map` on the home screen returns icons - [ ] Wait for something already on screen, and across a cold app launch - [ ] `mobium scroll-to` reaches a Settings row below the fold, and tapping it opens that screen - [ ] `mobium grant com.apple.Preferences photos` succeeds and says it could not be verified - [ ] `mobium grant <anything> camera` is refused, naming the missing service - [ ] Coordina…", "gold": false}, {"id": "docs/BACK.md#ios", "heading": "iOS", "path": "docs/BACK.md", "excerpt": "iOS has no system back. Going back is the app's: a navigation bar's back button, and, for a `UINavigationController`, a swipe. Mobium refuses `press back` there by design (it is not an event iOS sends); `press back --gesture` sends the swipe, starting in the navigation bar, since the measurements below found a swipe over a list row taken by the row ([In Mobium](#in-mobium)). | | MobiumApp | Control | | --- | --- | --…", "gold": false}, {"id": "docs/SETUP.md#running-headless", "heading": "Running headless", "path": "docs/SETUP.md", "excerpt": "Add `-no-window`. Everything mobium does works unchanged, screenshots included — `adb exec-out screencap` reads the framebuffer, not the window: ```sh emulator -avd mobium-test -no-window -no-snapshot-save -no-boot-anim -no-audio & ``` **Unlike an iOS simulator, the window cannot be attached afterwards.** `simctl boot` is always headless and `open -a Simulator` shows it later; the Android emulator decides at launch, …", "gold": false}], "missed": false, "facts": ["The tvOS platform is a separate download: xcodebuild -downloadPlatform tvOS, then create and boot an Apple TV simulator; the first command installs WebDriverAgent's tvOS runner. ⟦-downloadPlatform tvOS⟧", "It is driven with the remote: press dpad-up/down/left/right and select, back is the Menu button; tap and other gestures are refused. ⟦dpad-up ; select⟧"], "concern": "", "check": "Claude's reading: remote.go and alerts.go refuse touches on an Apple TV because it has no touch screen, and buttons.go maps back to the remote's Menu button on tvOS. README.md#platforms~2 summarizes TVs and is a near miss without the setup commands. Verified in: internal/agent/remote.go:12, internal/mobiumdriver/buttons.go:194, internal/mobiumdriver/alerts.go:73."}, {"id": "g017", "kind": "fact", "question": "Does Mobium work with Wear OS watches, and what can't it do on one yet?", "tags": ["support", "test-author"], "gold": [{"id": "README.md#platforms", "heading": "Platforms", "path": "README.md", "excerpt": "Verified on devices, not only compiled: a Pixel 7 emulator on Android 15 and Android 17, a Pixel 8 Pro on Android 17, an iPhone 17 Pro simulator on iOS 26.5, and an iPhone 15 Plus on iOS 26.6.2. The end-to-end flows in [docs/checks/](docs/checks/) each drive a real device and assert on what happened rather than on an exit code. | | `uiautomator2` | `uiautomator` | `wda` | | --- | --- | --- | --- | | platform | Androi…"}], "retrieved": [{"id": "docs/SETUP.md#a-wear-os-emulator", "heading": "A Wear OS emulator", "path": "docs/SETUP.md", "excerpt": "Wear OS images are on the stable channel, Wear OS 3 to 6.1, and 7.0 at API 37. A watch is driven as any Android device, by the same backends: ```sh sdkmanager \"system-images;android-35-ext15;android-wear;arm64-v8a\" # Wear OS 5.1 avdmanager create avd -n mobium-wear -d wearos_large_round \\ -k \"system-images;android-35-ext15;android-wear;arm64-v8a\" emulator -avd mobium-wear -port 5558 -no-snapshot-load -no-boot-anim & …", "gold": false}, {"id": "docs/THREAT-MODEL.md#what-it-is-for-this-purpose", "heading": "What it is, for this purpose", "path": "docs/THREAT-MODEL.md", "excerpt": "- **Mobium does not run a model.** It is the hands of one: an agent, or a script, calls tools; Mobium acts on a device and reports what it saw. - **Everything it reports comes from apps it does not control.** `map` labels, `text`, `source`, WebView `eval` results, notifications, device logs, crash reports, the clipboard. Any app or page can put text there, including text written to be read by an agent as an instructi…", "gold": false}, {"id": "docs/ACCESSIBILITY.md#assistive-technology", "heading": "Assistive technology", "path": "docs/ACCESSIBILITY.md", "excerpt": "What Mobium can do with the tools disabled people use to operate a phone or a TV: screen readers, speech that drives the screen, and voice assistants that do a task without it. What was measured, what it found, and the plan to build on it, in the order it should be built. Each step names the control that shows it can fail before its result counts. **Status on 2026-10-20.** TalkBack stays on through a session (CHALLEN…", "gold": false}, {"id": "docs/ROADMAP.md#next", "heading": "Next", "path": "docs/ROADMAP.md", "excerpt": "- **Found reviewing the docs evaluation's golden set** (written down 2026-10-12, read from the code, not yet run on a device): 1. ~~**On an Apple TV, a dialog of three or more buttons named a remedy that cannot work.**~~ Done 2026-10-12, CHALLENGES 313: `app_alert` asks the driver whether the device is answered by its remote before choosing accept, dismiss or a button, and on a TV every one of them is refused naming …", "gold": false}, {"id": "docs/WINDOWS.md#what-is-expected-to-work-already", "heading": "What is expected to work already", "path": "docs/WINDOWS.md", "excerpt": "Never run against a device on Windows — that is the point of this exercise — but these have no platform-specific code: - the tool layer, the driver interface, the tree parser, locators and refs - `adb` discovery and every Android command, including port forwarding - the UiAutomator2 backend, its APK download and checksum verification - WebView contexts over CDP - **`mobium mcp`**, which runs the tool layer in-process…", "gold": false}], "missed": true, "facts": ["Wear OS is driven by the Android backends with nothing added, verified on a Wear OS 5.1 emulator, with swiping right as a watch's back. ⟦Wear OS 5.1⟧", "Not yet a real watch, and not the crown: press has no rotary input. ⟦rotary⟧"], "concern": "", "check": "Claude's reading: the press button list in schema.go has D-pad, select, back and media keys and no rotary or crown input; nothing in internal/ handles a crown. SETUP.md#a-wear-os-emulator says 'the crown has no command yet' but not that a real watch is untested, so README is the sufficient section. Verified in: internal/agent/schema.go:1438, internal/mobiumdriver/buttons.go:37."}, {"id": "g018", "kind": "fact", "question": "mobium doctor printed several 'note' lines on my machine. Does that mean my setup is broken, and will doctor fail a CI setup step because of them?", "tags": ["behavior", "ci-engineer"], "gold": [{"id": "docs/SETUP.md#setting-up-devices", "heading": "Setting up devices", "path": "docs/SETUP.md", "excerpt": "Everything Mobium needs on the machine and on the device, for all four kinds of target. Written from doing it: every trap below cost real time here, and most of them report something that names the wrong cause. **Run `mobium doctor` first.** It checks the whole list without needing a device, and exits non-zero if it found something: ``` ok adb Android Debug Bridge version 1.0.41 at /opt/homebrew/bin/adb note android …"}], "retrieved": [{"id": "docs/SETUP.md#setting-up-devices", "heading": "Setting up devices", "path": "docs/SETUP.md", "excerpt": "Everything Mobium needs on the machine and on the device, for all four kinds of target. Written from doing it: every trap below cost real time here, and most of them report something that names the wrong cause. **Run `mobium doctor` first.** It checks the whole list without needing a device, and exits non-zero if it found something: ``` ok adb Android Debug Bridge version 1.0.41 at /opt/homebrew/bin/adb note android …", "gold": true}, {"id": "CHALLENGES#32", "heading": "32. `doctor` could not run in the situation it exists for", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** testing it against a deliberately broken environment, which is the only way this would ever have shown up. The first version of `mobium doctor` went through the daemon like every other command. Pointed at a `MOBIUM_HOME` long enough to push the Unix socket path over the OS limit, it failed with *that* error instead of producing a report — the error it exists to explain. A diagnostic that only works on a…", "gold": false}, {"id": "docs/guides/test-runner.md#7-in-ci", "heading": "7. In CI", "path": "docs/guides/test-runner.md", "excerpt": "The command a CI job runs, and what it publishes: ```sh mobium test --reporter list,junit,html # junit: mobium-report/junit.xml — for the CI's test report # html: mobium-report/ — as a build artifact ``` The exit status is 0 when every test passed or was flaky, 1 when any failed, and one of mobium's own codes when the run could not start — 2 for a bad file or an unset device, 3 for no device — so a job can tell \"the …", "gold": false}, {"id": "CHALLENGES#if-you-are-seeing-something-odd-start-here", "heading": "If you are seeing something odd, start here", "path": "docs/CHALLENGES.md", "excerpt": "Symptom first, because that is what you have. Every row points at the entry with the evidence. | What you are seeing | What it usually is | | --- | --- | | A command \"succeeded\" and nothing changed | Nothing here reports failure by exit code. `pm grant`, `simctl privacy`, `am start`, `adb uninstall` and `uiautomator dump` each fail differently — 25, 26, 27, 30 | | An element is on screen but a locator says it is not …", "gold": false}, {"id": "skills/mobile-check/SKILL.md#when-something-fails-for-no-good-reason", "heading": "When something fails for no good reason", "path": "skills/mobile-check/SKILL.md", "excerpt": "`mobium doctor` checks the environment and needs no device — that is the point. Several of the toolchain's own errors name the wrong cause, so run it before believing one of them. It exits non-zero if it found anything.", "gold": false}], "missed": false, "facts": ["A note means something is missing that is only needed for part of the job, such as no Xcode on a machine doing Android work, which is normal. ⟦part of the job⟧", "doctor checks the whole list without a device and exits non-zero when it found a problem (a FAIL line), so a script can act on it. ⟦non-zero⟧"], "concern": "", "check": "Claude's reading: only checks with status problem (printed FAIL) count toward Problems, and the command exits non-zero only when Problems > 0, so notes alone exit zero. The doc says 'exits non-zero if it found something', which a reviewer may find vaguer than the code; the answer that notes do not fail is from the code, so the second fact is left to the judge on that point. Verified in: internal/agent/doctor.go:42-67, internal/agent/doctor.go:343-345, cmd/mobium/doctor.go:29-34."}, {"id": "g019", "kind": "unanswerable", "question": "How do I set up the Mobium daemon to start automatically at login as a launchd or systemd service, so it is always up before my tests run?", "tags": ["ci-engineer"], "gold": [], "retrieved": [{"id": "docs/quickstart/go.md#3-the-code", "heading": "3. The code", "path": "docs/quickstart/go.md", "excerpt": "Save this as `main.go` in the project folder — it is [examples/go/main.go](examples/go/main.go). ```go // Mobium quick start: start a session, drive Settings, quit. // // MOBIUM_PLATFORM=android go run . # or ios package main import ( \"context\" \"fmt\" \"log\" \"os\" \"strings\" \"time\" mobium \"github.com/mobiumdev/mobium/clients/go\" ) // Settings is on every emulator, simulator and phone, with nothing to install. var platfor…", "gold": false}, {"id": "docs/guides/inspector.md#4-record-a-test", "heading": "4. Record a test", "path": "docs/guides/inspector.md", "excerpt": "A test starts from a freshly launched app, so a recording should too: **Start from a fresh app** stops the app in front and launches it again, as `mobium test` does before each test, and starts recording. From there, every action is a step. Recorded on the Login Demo: ```json { \"app\": \"dev.mobium.mobiumapp\", \"description\": \"Recorded with mobium inspect.\", \"tests\": [ { \"name\": \"recorded\", \"steps\": [ {\"tap\": \"text=Logi…", "gold": false}, {"id": "docs/quickstart/README.md#contents", "heading": "Contents", "path": "docs/quickstart/README.md", "excerpt": "- [Where it runs](#where-it-runs) - [1. Install mobium](#1-install-mobium) - [2. Start a device](#2-start-a-device) - [3. Check the setup](#3-check-the-setup) - [4. Start, work, quit](#4-start-work-quit) - [Next](#next) - [When something goes wrong](#when-something-goes-wrong)", "gold": false}, {"id": "docs/quickstart/python.md#3-the-code", "heading": "3. The code", "path": "docs/quickstart/python.md", "excerpt": "Save this as `quickstart.py` in the project folder — it is [examples/python/quickstart.py](examples/python/quickstart.py). ```python \"\"\"Mobium quick start: start a session, drive Settings, quit. MOBIUM_PLATFORM=android python3 quickstart.py # or ios \"\"\" import os from mobium import start # Settings is on every emulator, simulator and phone, with nothing to install. PLATFORMS = { \"android\": {\"app\": \"com.android.settin…", "gold": false}, {"id": "docs/quickstart/cli.md#2-the-code", "heading": "2. The code", "path": "docs/quickstart/cli.md", "excerpt": "Save this as `quickstart.sh` — it is [examples/cli/quickstart.sh](examples/cli/quickstart.sh). ```sh #!/bin/sh # Mobium quick start from the command line: start a session, drive Settings, # quit. # # MOBIUM_PLATFORM=android sh quickstart.sh # or ios set -e PLATFORM=\"${MOBIUM_PLATFORM:-android}\" if [ \"$PLATFORM\" = ios ]; then APP=com.apple.Preferences ROW=General NEXT=\"label=About,role=button\" else APP=com.android.set…", "gold": false}], "missed": false, "facts": [], "concern": "", "check": "Claude's reading: the corpus mentions launchd only for simulator internals and Chrome's crash handler, never systemd or a login service; the code only auto-starts the daemon from the first command (daemon_client.go) or `daemon start`. The docs explain auto-start and idle exit, which a retriever will return, but never how to run it as a service. Nearest sections: docs/guides/cli.md#8-the-daemon-and-running-several-at-once, docs/SHUTDOWN.md#1-mobium-daemon-stop-always-first. Verified in: cmd/mobium/daemon_client.go:16-19, cmd/mobium/daemon_cmd.go:46."}, {"id": "g020", "kind": "unanswerable", "question": "When will Mobium's first prebuilt release, v0.1.0, be published so I can install without Go?", "tags": ["new-user"], "gold": [], "retrieved": [{"id": "docs/quickstart/README.md#1-install-mobium", "heading": "1. Install mobium", "path": "docs/quickstart/README.md", "excerpt": "Until the first release there are no prebuilt binaries: mobium installs with **Go 1.24 or later** ([go.dev/dl](https://go.dev/dl/)), and needs nothing else. ```sh go install github.com/mobiumdev/mobium/cmd/mobium@latest mobium --version ``` It lands in `$(go env GOPATH)/bin`; make sure that is on your `PATH`. Each client page says how to install that client. Python (with `git`) and Go install straight from GitHub tod…", "gold": false}, {"id": "docs/SETUP.md#installing-a-release", "heading": "Installing a release", "path": "docs/SETUP.md", "excerpt": "From the first tagged release on, each one carries mobium prebuilt for macOS, Linux and Windows, on amd64 and arm64, so installing it needs no Go: `mobium_<version>_<os>_<arch>.tar.gz` (`.zip` for Windows), each holding the binary, the license and its notices, and the README, and `SHA256SUMS` over all of them. The binary is static — nothing else to install with it. ```sh v=0.1.0; os=darwin; arch=arm64 # or linux / wi…", "gold": false}, {"id": "docs/ROADMAP.md#next", "heading": "Next", "path": "docs/ROADMAP.md", "excerpt": "- **Found reviewing the docs evaluation's golden set** (written down 2026-10-12, read from the code, not yet run on a device): 1. ~~**On an Apple TV, a dialog of three or more buttons named a remedy that cannot work.**~~ Done 2026-10-12, CHALLENGES 313: `app_alert` asks the driver whether the device is answered by its remote before choosing accept, dismiss or a button, and on a TV every one of them is refused naming …", "gold": false}, {"id": "README.md#quick-start", "heading": "Quick start", "path": "README.md", "excerpt": "Requirements: - **Go 1.24+**, to install it — prebuilt binaries arrive with the first release ([SETUP.md](docs/SETUP.md#installing-a-release)) - **Android:** platform-tools on `PATH` (or `ANDROID_HOME`, or `MOBIUM_ADB_PATH`), and an emulator or a phone with USB debugging on - **iOS:** full Xcode and a booted simulator — or an iPhone on a cable, with an Apple ID (a free one works) added to Xcode ```sh go install githu…", "gold": false}, {"id": "docs/upstream/webdriveragent-mjpeg-ignores-use-ip.md#what-mobium-does-meanwhile", "heading": "What Mobium does meanwhile", "path": "docs/upstream/webdriveragent-mjpeg-ignores-use-ip.md", "excerpt": "- **Real iPhone:** Mobium builds the runner from the pinned source and applies this line before building (`internal/device/wdapatch.go`), refusing to build if the line it attaches to is gone. - **Simulator:** Mobium installs the prebuilt release, which it does not patch. The server is bound with `USE_IP=127.0.0.1`; the stream is left to the Mac's firewall. A runner built for the simulator from source could not be lau…", "gold": false}], "missed": false, "facts": [], "concern": "", "check": "Claude's reading: the corpus describes what a release will contain and that installs need Go until the first release, and uses v0.1.0 as an example version, but states no date; release gating is a checklist, not a schedule. A right answer says the docs give no date. Nearest sections: docs/SETUP.md#installing-a-release, docs/quickstart/README.md#1-install-mobium. Verified in: docs/RELEASE-CHECKLIST.md."}, {"id": "g021", "kind": "fact", "question": "My locator text=Settings also clicks things like \"Display settings\" because it matches part of the text. How do I make a Mobium locator match only an element whose text is exactly Settings?", "tags": ["how-to", "test-author"], "gold": [{"id": "docs/guides/cli.md#4-locators-and-refs", "heading": "4. Locators and refs", "path": "docs/guides/cli.md", "excerpt": "Anything that takes a target takes either: - **a ref** from the last `map` — `@e3` — short, and valid until the screen changes; or - **a locator** — `testid=username`, `label=Login Demo`, `text=Sign in`, `role=button` — which survives across screens and runs, and is what a script or a test should use. `testid=` is the one that survives a translation and a redesign. A string locator matches part of the words, in any c…"}], "retrieved": [{"id": "CHALLENGES#306", "heading": "306. A locator printed as exact was pasted back as a part", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** writing down what a hand-written locator cannot say, for the roadmap's locators entry. CHALLENGES 233's wait for `text=Internet` was met by \"Network & internet\" on the screen being left, and 185 had already noted \"no syntax to ask for the whole of it\". The locators `map` derives are exact — byte for byte — but a locator printed itself without saying so: a near miss suggested `label=Card 8`, an exact mat…", "gold": false}, {"id": "CHALLENGES#315", "heading": "315. On a watch, `text=` found a control and its own title", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** measuring Wear OS for the docs evaluation's question about it (ROADMAP), on a Wear OS 5.1 emulator (API 35, 454×454 round). `text=\"Security\"` on Settings matched two elements and was refused, and so was every row: a Wear \"chip\" is a `Button` whose own `text` repeats its title's `TextView` (`wear_chip_primary_text`). A phone's settings row carries no text of its own, so there only the title matched. The …", "gold": false}, {"id": "README.md#refs", "heading": "Refs", "path": "README.md", "excerpt": "`mobium map` snapshots the accessibility hierarchy, keeps the nodes a person could act on, and gives each one the most durable locator that identifies it uniquely — a resource-id if there is one, then an accessibility label, then visible text, and a sibling path only as a last resort. `mobium tap @e5` **re-snapshots and re-resolves** that locator before touching anything. It never replays the coordinates from the map…", "gold": false}, {"id": "docs/guides/cli.md#4-locators-and-refs", "heading": "4. Locators and refs", "path": "docs/guides/cli.md", "excerpt": "Anything that takes a target takes either: - **a ref** from the last `map` — `@e3` — short, and valid until the screen changes; or - **a locator** — `testid=username`, `label=Login Demo`, `text=Sign in`, `role=button` — which survives across screens and runs, and is what a script or a test should use. `testid=` is the one that survives a translation and a redesign. A string locator matches part of the words, in any c…", "gold": true}], "missed": false, "facts": ["An unquoted string locator matches part of the words, in any case; putting the value in double quotes matches the whole of it (still in any case). ⟦double quotes⟧", "For example text=\"Internet\" finds only an element whose text is Internet, not \"Network & internet\". ⟦text=\"Internet\"⟧"], "concern": "", "check": "Claude's reading: cli.md section 4 states the quoted-whole rule; Locator.field compares a quoted (Whole) value with strings.EqualFold after trimming, and an unquoted one by case-insensitive substring (match). Reviewer: the question's example is mine, the anchor example is the doc's. Verified in: internal/uitree/locator.go:425, internal/uitree/locator.go:441."}, {"id": "g022", "kind": "fact", "question": "Every row in my list has its own \"More\" button. How do I write a locator in a test file for the More button in the row titled \"Card 8\", one that still works after the list scrolls?", "tags": ["how-to", "test-author"], "gold": [{"id": "docs/guides/cli.md#4-locators-and-refs", "heading": "4. Locators and refs", "path": "docs/guides/cli.md", "excerpt": "Anything that takes a target takes either: - **a ref** from the last `map` — `@e3` — short, and valid until the screen changes; or - **a locator** — `testid=username`, `label=Login Demo`, `text=Sign in`, `role=button` — which survives across screens and runs, and is what a script or a test should use. `testid=` is the one that survives a translation and a redesign. A string locator matches part of the words, in any c…"}], "retrieved": [{"id": "docs/guides/inspector.md#4-record-a-test", "heading": "4. Record a test", "path": "docs/guides/inspector.md", "excerpt": "A test starts from a freshly launched app, so a recording should too: **Start from a fresh app** stops the app in front and launches it again, as `mobium test` does before each test, and starts recording. From there, every action is a step. Recorded on the Login Demo: ```json { \"app\": \"dev.mobium.mobiumapp\", \"description\": \"Recorded with mobium inspect.\", \"tests\": [ { \"name\": \"recorded\", \"steps\": [ {\"tap\": \"text=Logi…", "gold": false}, {"id": "docs/guides/cli.md#4-locators-and-refs", "heading": "4. Locators and refs", "path": "docs/guides/cli.md", "excerpt": "Anything that takes a target takes either: - **a ref** from the last `map` — `@e3` — short, and valid until the screen changes; or - **a locator** — `testid=username`, `label=Login Demo`, `text=Sign in`, `role=button` — which survives across screens and runs, and is what a script or a test should use. `testid=` is the one that survives a translation and a redesign. A string locator matches part of the words, in any c…", "gold": true}, {"id": "CHALLENGES#307", "heading": "307. A scoped locator found the switch in the row beside it", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** the first run on a device of `within`, which scopes a locator to a row — `label=More within text=Card 8`, the More in Card 8's row. The rule keeps, of the target's matches, the one nearest the anchor, climbing from the anchor and stopping at the list, so a row without the target finds nothing rather than its neighbor's. The tests passed on lists built for them, each marked `scrollable=\"true\"`. On the An…", "gold": false}], "missed": false, "facts": ["Use within to scope a locator to a row, e.g. label=More within text=Card 8; both sides are whole locators. ⟦within text= / within label=⟧", "It keeps the match nearest the anchor and never reaches past the list holding the anchor, so a row without the target finds nothing rather than the neighbor's.", "Both sides are resolved again on every read, since a list reuses its rows as it scrolls (unlike a ref, which is gone with its map)."], "concern": "", "check": "Claude's reading: cli.md section 4 describes within; Locator.Resolve keeps the target matches nearest the anchor and the comment above it says the climb stops at a scroll container and resolves whole on every read. Facts 2 and 3 have no distinctive token and are left to the judge. Verified in: internal/uitree/locator.go:40, internal/uitree/locator.go:491, internal/uitree/locator.go:508."}, {"id": "g023", "kind": "multi", "question": "In my hybrid app the Save button sits inside an iframe on the embedded web page. How do I tap it from the Mobium CLI?", "tags": ["how-to", "test-author"], "gold": [{"id": "README.md#hybrid-apps-and-webviews", "heading": "Hybrid apps and WebViews", "path": "README.md", "excerpt": "A hybrid app's web content is not usable through the accessibility tree, so Mobium attaches to the WebView, and switching context changes what `map` and `tap` operate on: ``` $ mobium contexts NATIVE_APP (current) WEBVIEW_com.example — Checkout https://shop.example/cart $ mobium context WEBVIEW_com.example $ mobium map @e1 Promo code (input) @e2 Apply (button) $ mobium tap @e2 tapped @e2 at (462, 397) in WEBVIEW_com.…"}, {"id": "docs/guides/cli.md#4-locators-and-refs", "heading": "4. Locators and refs", "path": "docs/guides/cli.md", "excerpt": "Anything that takes a target takes either: - **a ref** from the last `map` — `@e3` — short, and valid until the screen changes; or - **a locator** — `testid=username`, `label=Login Demo`, `text=Sign in`, `role=button` — which survives across screens and runs, and is what a script or a test should use. `testid=` is the one that survives a translation and a redesign. A string locator matches part of the words, in any c…"}], "retrieved": [{"id": "CHALLENGES#228", "heading": "228. A WebView's map stopped at the edge of every frame", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** taking ROADMAP's \"Frames and iframes inside a WebView\" to MobiumApp's Frames page, built for it: a same-origin frame, a frame nested inside it and a cross-origin one, each of whose buttons tells the page it was tapped. In the WebView's context `map` listed the page's own button and nothing in any frame, on the simulator and an emulator alike: the scripts that find elements, check them and fill them read…", "gold": false}, {"id": "skills/mobile-check/SKILL.md#when-things-fail", "heading": "When things fail", "path": "skills/mobile-check/SKILL.md", "excerpt": "Mobium's errors say what to do; read them rather than retrying blindly. Every failure also carries a **code**, so you can act on the kind without parsing the sentence: `--json` prints it (`\"code\": \"no_such_element\"`, with a `remedy` and `details`), and the exit status groups it: | Exit | Codes | What to do | | --- | --- | --- | | 2 | `invalid_argument` | fix the command; retrying it unchanged cannot help | | 3 | `no_…", "gold": false}, {"id": "skills/mobile-check/SKILL.md#hybrid-apps-webviews", "heading": "Hybrid apps (WebViews)", "path": "skills/mobile-check/SKILL.md", "excerpt": "Web content inside an app is a separate context: ```sh mobium contexts # NATIVE_APP, WEBVIEW_com.example mobium context WEBVIEW_com.example # map and tap now work on the page mobium context NATIVE_APP # back to the native shell ``` This works on **both platforms**. Android WebViews must be debuggable (`setWebContentsDebuggingEnabled(true)`) and iOS WKWebViews must be inspectable (`webView.isInspectable = true` on iOS…", "gold": false}, {"id": "README.md#hybrid-apps-and-webviews", "heading": "Hybrid apps and WebViews", "path": "README.md", "excerpt": "A hybrid app's web content is not usable through the accessibility tree, so Mobium attaches to the WebView, and switching context changes what `map` and `tap` operate on: ``` $ mobium contexts NATIVE_APP (current) WEBVIEW_com.example — Checkout https://shop.example/cart $ mobium context WEBVIEW_com.example $ mobium map @e1 Promo code (input) @e2 Apply (button) $ mobium tap @e2 tapped @e2 at (462, 397) in WEBVIEW_com.…", "gold": true}, {"id": "docs/quickstart/cli.md#2-the-code", "heading": "2. The code", "path": "docs/quickstart/cli.md", "excerpt": "Save this as `quickstart.sh` — it is [examples/cli/quickstart.sh](examples/cli/quickstart.sh). ```sh #!/bin/sh # Mobium quick start from the command line: start a session, drive Settings, # quit. # # MOBIUM_PLATFORM=android sh quickstart.sh # or ios set -e PLATFORM=\"${MOBIUM_PLATFORM:-android}\" if [ \"$PLATFORM\" = ios ]; then APP=com.apple.Preferences ROW=General NEXT=\"label=About,role=button\" else APP=com.android.set…", "gold": false}], "missed": false, "facts": ["Switch to the WebView's context first (mobium contexts, then mobium context WEBVIEW_...), after which map and tap operate on the page. ⟦mobium context⟧", "Then use a css= locator with the frame's path before the selector, separated by >>, as map prints it, e.g. 'css=iframe#f >> button'. ⟦css= ; >>⟧"], "concern": "", "check": "Claude's reading: README's hybrid section gives the context switch, cli.md section 4 the css= selector with a frame path; findWebByLocator and webview/css.go split the selector on ' >> ' and resolve inside that frame. CHALLENGES 312 and SKILL 'When things fail' also mention the frame path; I kept gold to the two sections a new user needs. Verified in: internal/agent/webview.go:1057, internal/webview/css.go:35, internal/agent/webview.go:51."}, {"id": "g024", "kind": "multi", "question": "Is there a way to click an element on my device's screen and see which locator I should put in my test for it?", "tags": ["how-to", "new-user"], "gold": [{"id": "docs/guides/inspector.md#1-start-it", "heading": "1. Start it", "path": "docs/guides/inspector.md", "excerpt": "``` $ mobium inspect --device emulator-5554 mobium inspect on http://127.0.0.1:47311/819d02101356fef7563223333156107f/ — Ctrl-C to stop ``` Open that URL — `--open` does it for you. The long part of it is a token: the page answers nothing that does not carry it ([below](#who-can-reach-it)). It calls the same tools every command does, through the same daemon, so a terminal and the page drive one session: run `mobium t…"}, {"id": "docs/guides/inspector.md#2-find-the-locator-for-anything", "heading": "2. Find the locator for anything", "path": "docs/guides/inspector.md", "excerpt": "![The inspector on MobiumApp's Login Demo: the username field selected, its locator testid=username, its role, ref and bounds, and both buttons outlined in orange for role=button](images/inspector.jpg) Click an element on the screen, or in the list under it. The panel says what `map` says of it — label, role, ref, bounds, checked state — and, at the top, **the locator a test should use**: the one `map` derived as the…"}], "retrieved": [{"id": "docs/guides/inspector.md#2-find-the-locator-for-anything", "heading": "2. Find the locator for anything", "path": "docs/guides/inspector.md", "excerpt": "![The inspector on MobiumApp's Login Demo: the username field selected, its locator testid=username, its role, ref and bounds, and both buttons outlined in orange for role=button](images/inspector.jpg) Click an element on the screen, or in the list under it. The panel says what `map` says of it — label, role, ref, bounds, checked state — and, at the top, **the locator a test should use**: the one `map` derived as the…", "gold": true}, {"id": "docs/guides/inspector.md#quick-start-mobium-inspect", "heading": "Quick start: `mobium inspect`", "path": "docs/guides/inspector.md", "excerpt": "A page on your own machine with the device's screen in it: every element `map` finds outlined, the locator for the one you click, actions on it, a place to try a locator and see what it matches — and what you do, kept as a test `mobium test` runs. Everything below was run on 2026-09-29 against [MobiumApp](https://github.com/mobiumdev/mobium-app) on an Android 15 emulator; the output is what mobium printed. Before thi…", "gold": false}, {"id": "docs/guides/test-runner.md#writing-tests", "heading": "Writing tests", "path": "docs/guides/test-runner.md", "excerpt": "- **Find targets with `map` first.** `mobium map` on the screen you are testing gives each element's locator; `testid=` is the one that survives a translation and a redesign. - **Assert with `app_wait_for`**, never a sleep. `--for` in the CLI is `condition` in a step: `visible`, `hidden`, `text` (with `exact`), `value`, `enabled`, `disabled`, `checked`, `unchecked`, `selected`, `unselected`, `focused`, `count`, and `…", "gold": false}, {"id": "docs/ROADMAP.md#under-consideration", "heading": "Under consideration", "path": "docs/ROADMAP.md", "excerpt": "- **Locators for when there is no ref** (written down 2026-10-12). A ref from `map` lasts one map, so an agent has one and a `mobium test` file does not: a hand-written test has the flat `kind=value` locators — text, label, testid, role, class, path, narrowed by `,role=` — which match one element or are refused. That is right on a form and leaves nothing durable on a list. Every Ice Cubes post has a \"…\" (CHALLENGES 2…", "gold": false}, {"id": "docs/guides/cli.md#4-locators-and-refs", "heading": "4. Locators and refs", "path": "docs/guides/cli.md", "excerpt": "Anything that takes a target takes either: - **a ref** from the last `map` — `@e3` — short, and valid until the screen changes; or - **a locator** — `testid=username`, `label=Login Demo`, `text=Sign in`, `role=button` — which survives across screens and runs, and is what a script or a test should use. `testid=` is the one that survives a translation and a redesign. A string locator matches part of the words, in any c…", "gold": false}], "missed": false, "facts": ["Run mobium inspect (optionally --device and --open), which serves a local page showing the device's screen. ⟦mobium inspect ; --open⟧", "Clicking an element shows what map says of it, and at the top the locator a test should use: the most durable one that names it alone (the ref names it on this screen only). ⟦the locator a test should use⟧"], "concern": "", "check": "Claude's reading: inspector guide sections 1 and 2 together answer it; cmd/mobium/inspect.go defines --port, --open and --record, and inspect.go's target() returns map's derived locator as the one a test names. Section 3 (Try a locator) is related but not needed. Verified in: cmd/mobium/inspect.go:71, internal/inspect/inspect.go:205."}, {"id": "g025", "kind": "multi", "question": "On an Apple TV simulator mobium tap is refused. How do I get to a particular tile and open it, and how do I know which tile will be opened before I press?", "tags": ["how-to", "test-author", "new since 7b590a4"], "gold": [{"id": "docs/SETUP.md#an-apple-tv-simulator", "heading": "An Apple TV simulator", "path": "docs/SETUP.md", "excerpt": "Verified on a tvOS 26.5 simulator (Apple TV 4K, 3rd generation, at 1080p) with Xcode 26.6, on 2026-10-09. The tvOS platform is a separate download: ```sh xcodebuild -downloadPlatform tvOS # or Xcode > Settings > Components xcrun simctl create \"Apple TV\" \\ com.apple.CoreSimulator.SimDeviceType.Apple-TV-4K-3rd-generation-1080p \\ com.apple.CoreSimulator.SimRuntime.tvOS-26-5 xcrun simctl boot <udid> && open -a Simulator …"}, {"id": "CHALLENGES#355", "heading": "355. A TV's map did not say which tile select would press", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** the Fire TV and Apple TV entries in ROADMAP, then MobiumTV's home screen on the Android TV emulator and the Apple TV simulator. A TV is driven by focus: the D-pad moves it and select presses what has it. Both platforms report it on the node — Android's `focused`, and iOS's since 297 — and a D-pad press already read it back (\"focus moved to Focus or Select\"). But `map` built its entries without it, so af…"}], "retrieved": [{"id": "CHALLENGES#334", "heading": "334. On an Apple TV, a dialog rule tapped, and refusals said to tap", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** Morpho Market's Apple TV app, on a tvOS 26.5 simulator. Its tests start from `mobiumshop://reset`, and tvOS asks \"Open in “Morpho Market”?\" before a link opens the app, until Open is pressed once — as iOS does, where the phone suite answers it with a dialog rule. On the Apple TV the same rule failed every action it met: the rule tapped the button, and a TV refuses every tap (`an Apple TV has no touch sc…", "gold": false}, {"id": "docs/ROADMAP.md#under-consideration", "heading": "Under consideration", "path": "docs/ROADMAP.md", "excerpt": "- **Locators for when there is no ref** (written down 2026-10-12). A ref from `map` lasts one map, so an agent has one and a `mobium test` file does not: a hand-written test has the flat `kind=value` locators — text, label, testid, role, class, path, narrowed by `,role=` — which match one element or are refused. That is right on a form and leaves nothing durable on a list. Every Ice Cubes post has a \"…\" (CHALLENGES 2…", "gold": false}, {"id": "docs/RELEASE-CHECKLIST.md#ios-a-booted-iphone-simulator", "heading": "iOS — a booted iPhone simulator", "path": "docs/RELEASE-CHECKLIST.md", "excerpt": "- [ ] `mobium --driver wda map` on the home screen returns icons - [ ] Wait for something already on screen, and across a cold app launch - [ ] `mobium scroll-to` reaches a Settings row below the fold, and tapping it opens that screen - [ ] `mobium grant com.apple.Preferences photos` succeeds and says it could not be verified - [ ] `mobium grant <anything> camera` is refused, naming the missing service - [ ] Coordina…", "gold": false}, {"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": false}, {"id": "docs/SETUP.md#an-apple-tv-simulator", "heading": "An Apple TV simulator", "path": "docs/SETUP.md", "excerpt": "Verified on a tvOS 26.5 simulator (Apple TV 4K, 3rd generation, at 1080p) with Xcode 26.6, on 2026-10-09. The tvOS platform is a separate download: ```sh xcodebuild -downloadPlatform tvOS # or Xcode > Settings > Components xcrun simctl create \"Apple TV\" \\ com.apple.CoreSimulator.SimDeviceType.Apple-TV-4K-3rd-generation-1080p \\ com.apple.CoreSimulator.SimRuntime.tvOS-26-5 xcrun simctl boot <udid> && open -a Simulator …", "gold": true}], "missed": false, "facts": ["An Apple TV has no touch screen, so tap and other gestures are refused; it is driven with the remote: press dpad-up/down/left/right to move focus, and press select to press what has focus. ⟦dpad-down / dpad-right / dpad-up / dpad-left ; no touch screen⟧", "map marks the element with focus as (button, focused), and map --diff reports focus moving, so the focused tile is the one select will press. ⟦(button, focused)⟧"], "concern": "", "check": "Claude's reading: SETUP's Apple TV section gives the remote buttons and the refusal of tap; CHALLENGES 355 (#259, after the pin) adds focused to map and map --diff, which snapshot.go and mapdiff.go implement. ROADMAP 'Under consideration' also mentions 355 for the Fire TV. Verified in: internal/agent/remote.go:11, cmd/mobium/buttons.go:8, internal/uitree/snapshot.go:80, internal/agent/mapdiff.go:99."}, {"id": "g026", "kind": "fact", "question": "My Compose screen has a Material 3 RangeSlider for a price range, with a minimum and a maximum thumb. How do I set each thumb with Mobium, and how does Mobium move it?", "tags": ["how-to", "test-author", "new since 7b590a4"], "gold": [{"id": "CHALLENGES#357", "heading": "357. A two-thumb slider: a fill that moved nothing said it moved, and a thumb at the edge closed the app", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** native two-thumb sliders (ROADMAP, \"Sliders\"), on a price range added to Morpho Market for them — Material 3's `RangeSlider` on Android, and on iOS a control the app draws, since SwiftUI has none. Three things, each measured on the Android 15 emulator and the iPhone 17 Pro simulator: - **A fill that moved nothing was reported as moved.** Material reports each thumb as a seek bar the size of the thumb — …"}], "retrieved": [{"id": "docs/ROADMAP.md#under-consideration", "heading": "Under consideration", "path": "docs/ROADMAP.md", "excerpt": "- **Locators for when there is no ref** (written down 2026-10-12). A ref from `map` lasts one map, so an agent has one and a `mobium test` file does not: a hand-written test has the flat `kind=value` locators — text, label, testid, role, class, path, narrowed by `,role=` — which match one element or are refused. That is right on a form and leaves nothing durable on a list. Every Ice Cubes post has a \"…\" (CHALLENGES 2…", "gold": false}, {"id": "CHALLENGES#357", "heading": "357. A two-thumb slider: a fill that moved nothing said it moved, and a thumb at the edge closed the app", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** native two-thumb sliders (ROADMAP, \"Sliders\"), on a price range added to Morpho Market for them — Material 3's `RangeSlider` on Android, and on iOS a control the app draws, since SwiftUI has none. Three things, each measured on the Android 15 emulator and the iPhone 17 Pro simulator: - **A fill that moved nothing was reported as moved.** Material reports each thumb as a seek bar the size of the thumb — …", "gold": true}, {"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": false}, {"id": "CHALLENGES#320", "heading": "320. A two-thumb slider built from ARIA was not in `map`, and one built from ranges moved the wrong thumb", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** measuring two-thumb sliders, as pages build them, on MobiumApp's Slider Demo: Price, two `<input type=\"range\">` laid over one track, the minimum kept at or below the maximum by the page; and Hours, two `role=\"slider\"` thumbs on a drawn track, moved by a finger or the arrow keys, the way component libraries build one. Hours was not in `map` at all: the list of a page's elements had no `[role=slider]`. Pr…", "gold": false}], "missed": false, "facts": ["Each thumb is its own slider element (Material reports them as seek bars such as \"Range start\" and \"Range end\"), filled one at a time with fill and a position. ⟦Range start / Range end⟧", "A thumb of a two-thumb range is filled by dragging the thumb itself (a touch on the track would move the nearer thumb), and the result is read back from the thumb's own bounds, a short drag corrected. ⟦dragging the thumb itself⟧", "On Android the drag takes hold 32dp in from the screen's sides (20 points on iOS), so it is not taken as the system back gesture. ⟦32dp⟧"], "concern": "", "check": "Claude's reading: CHALLENGES 357 (#262, after the pin) is the only place the native two-thumb fill is described; RangeThumb recognizes two slider/adjustable children of one parent and dragThumb drags and reads back with up to three attempts. The 0-to-1 position rule itself is in CHALLENGES 219 and the fill help, not in 357; I did not make it a fact. Verified in: internal/uitree/rangethumb.go:13, internal/mobiumdriver/range.go:33, internal/agent/slider.go:37."}, {"id": "g027", "kind": "fact", "question": "After tapping Log In, my test needs to wait until the error label says exactly \"Incorrect username or password.\" How do I write that wait with Mobium, and how long does it wait before failing?", "tags": ["how-to", "test-author"], "gold": [{"id": "docs/guides/autowait.md#5-waiting-on-purpose-mobium-wait", "heading": "5. Waiting on purpose: `mobium wait`", "path": "docs/guides/autowait.md", "excerpt": "The checks above make each action wait for its own target. For everything else — a result to arrive, a spinner to go, a state to change — say what you are waiting for, instead of sleeping: ``` $ mobium wait testid=loginError --for text --text \"Incorrect username or password.\" --exact testid=loginError says exactly \"Incorrect username or password.\" after 1.631s — @e1 ScrollView (list) ``` It returned as soon as the te…"}], "retrieved": [{"id": "docs/guides/autowait.md#5-waiting-on-purpose-mobium-wait", "heading": "5. Waiting on purpose: `mobium wait`", "path": "docs/guides/autowait.md", "excerpt": "The checks above make each action wait for its own target. For everything else — a result to arrive, a spinner to go, a state to change — say what you are waiting for, instead of sleeping: ``` $ mobium wait testid=loginError --for text --text \"Incorrect username or password.\" --exact testid=loginError says exactly \"Incorrect username or password.\" after 1.631s — @e1 ScrollView (list) ``` It returned as soon as the te…", "gold": true}, {"id": "docs/guides/test-runner.md#4-run-only-what-failed", "heading": "4. Run only what failed", "path": "docs/guides/test-runner.md", "excerpt": "``` $ mobium test --last-failed FAIL [android] login.test.json › a wrong password is refused (8.7s) step 4 (app_wait_for): [timeout] step 4 of 4 (app_wait_for) failed: timed out after 3.018s waiting for testid=loginError to say exactly \"Wrong password.\" — its text is \"Incorrect username or password.\"; steps 1-3 ran before it, and nothing after 0 passed, 1 failed (8.7s) error: 1 of 1 tests failed ``` The previous run'…", "gold": false}, {"id": "docs/guides/autowait.md#2-waiting-for-a-control-to-be-enabled", "heading": "2. Waiting for a control to be enabled", "path": "docs/guides/autowait.md", "excerpt": "The Login Demo disables Log In while it signs in. Tap it, and tap it again at once: ``` $ mobium fill testid=username mobium typed \"mobium\" into testid=username $ mobium fill testid=password wrongpass1 typed 10 characters into testid=password, a password field — not echoed $ mobium tap testid=loginBtn tapped testid=loginBtn at (540, 1457) $ mobium wait testid=loginBtn --for disabled testid=loginBtn is disabled after …", "gold": false}, {"id": "docs/guides/cli.md#7-several-steps-in-one-call-batch", "heading": "7. Several steps in one call: `batch`", "path": "docs/guides/cli.md", "excerpt": "A known sequence can go as one call — from a file, or `-` for stdin. Every step is checked before the first runs, and it stops at the first failure, with that step's own error: ```json [ {\"name\": \"app_tap\", \"arguments\": {\"target\": \"label=Login Demo\"}}, {\"name\": \"app_fill\", \"arguments\": {\"target\": \"testid=username\", \"text\": \"mobium\"}}, {\"name\": \"app_fill\", \"arguments\": {\"target\": \"testid=password\", \"text\": \"hunter2\"}}…", "gold": false}, {"id": "skills/mobile-check/SKILL.md#waiting", "heading": "Waiting", "path": "skills/mobile-check/SKILL.md", "excerpt": "Never sleep. Every action already retries for two seconds while the screen settles, so a tap straight after a launch or another tap is fine. When something takes longer than that — a login, a network fetch — wait for the thing itself rather than for a duration: - `mobium wait \"text=Welcome back\"` — until it is on screen - `mobium wait 'text=\"Wi-Fi\"'` — quoted: the whole text, so a part of it on the screen you are lea…", "gold": false}], "missed": false, "facts": ["mobium wait <locator> --for text --text \"...\" --exact waits until the element's text is exactly that (without --exact it waits for the text to contain it). ⟦--exact ; --for text⟧", "The default timeout is 10 seconds; --timeout changes it, up to two minutes."], "concern": "", "check": "Claude's reading: autowait.md section 5 has the exact command and the timeout table; wait.go sets defaultWaitTimeout 10s and maxWaitTimeout 120s, and the CLI's --exact matches the whole text. The 10-second and two-minute numbers are too common in the corpus to anchor, so fact 2 is left to the judge. Verified in: cmd/mobium/wait.go:59, cmd/mobium/wait.go:61, internal/agent/wait.go:54."}, {"id": "g028", "kind": "fact", "question": "What does Mobium do when I tap a button that another view is drawn over, both when the cover hides the whole button and when it hides only the middle of it?", "tags": ["behavior", "test-author"], "gold": [{"id": "docs/guides/autowait.md#3-refusing-what-is-covered", "heading": "3. Refusing what is covered", "path": "docs/guides/autowait.md", "excerpt": "The Obstruction Demo draws controls over its targets — a full cover, a half cover over the center, an edge cover that leaves the center clear, views that take no touches, an overlay hidden from accessibility, a scrim: ![The Obstruction Demo: a column of buttons, each with something drawn over it](images/autowait-5-covers.jpg) One is covered entirely by another button: ``` $ mobium tap testid=fullTarget error: testid=…"}], "retrieved": [{"id": "docs/guides/autowait.md#3-refusing-what-is-covered", "heading": "3. Refusing what is covered", "path": "docs/guides/autowait.md", "excerpt": "The Obstruction Demo draws controls over its targets — a full cover, a half cover over the center, an edge cover that leaves the center clear, views that take no touches, an overlay hidden from accessibility, a scrim: ![The Obstruction Demo: a column of buttons, each with something drawn over it](images/autowait-5-covers.jpg) One is covered entirely by another button: ``` $ mobium tap testid=fullTarget error: testid=…", "gold": true}, {"id": "CHALLENGES#115", "heading": "115. A tap under the app's own overlay reported success", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** MobiumApp's Obstruction Demo, built for the purpose after the Dialog Demo's pinned button was seen covering the camera button while both platforms called both visible. Each case is a target with a known cover, every cover itself pressable, and one line saying which of them a tap really reached. On a Pixel 7 AVD and an iPhone 17 Pro simulator, `tap` answered \"tapped\" eight times out of eight, and six of …", "gold": false}, {"id": "CHALLENGES#107", "heading": "107. A tap on a button under the keyboard reported success", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** the iOS login demo, where Log In sat under the keyboard; the app's layout was fixed then, and the Dialog Demo's pinned button is the case kept on purpose. The keyboard is the dialog case one layer over, in the same two shapes. On iOS the keyboard is an `XCUIElementTypeKeyboard` in the app's tree, and what it covers stays there, marked not visible — the field being typed into included — so a locator reso…", "gold": false}, {"id": "docs/guides/autowait.md#what-it-does-not-see", "heading": "What it does not see", "path": "docs/guides/autowait.md", "excerpt": "- **An overlay hidden from accessibility on iOS.** On a real iPhone no action checks for one: a tap under it lands on the overlay and is reported as tapped. WebDriverAgent's tree does not contain it, and its own `hittable` gets it wrong too, measured. It is uncommon — none was met in five third-party apps driven on the phone — and asking each action would cost more than the action: through the gray box, one question …", "gold": false}], "missed": false, "facts": ["Fully covered: it waits about two seconds in case the cover goes (a toast does), then refuses with failed check receivesEvents, naming the cover, rather than pressing it. ⟦receivesEvents⟧", "Covered only over its center: it taps a clear point of the target and says so in the result. ⟦clear point⟧"], "concern": "", "check": "Claude's reading: autowait.md section 3 shows both outputs; resolveAim waits up to the implicit wait (2s; longer for a notification banner) for a full cover, then coveredBy refuses, and a center-only cover gets the 'touched at a clear point' note. Verified in: internal/agent/cover.go:73, internal/agent/cover.go:130, internal/agent/cover.go:153."}, {"id": "g029", "kind": "fact", "question": "How long will a Mobium tap keep waiting for a button that is still animating into place, and how long for one that is disabled, before it gives up?", "tags": ["behavior", "test-author"], "gold": [{"id": "docs/guides/autowait.md#the-checks", "heading": "The checks", "path": "docs/guides/autowait.md", "excerpt": "Five checks, each with a name that a refusal carries: | Check | What it asks | If it fails | | --- | --- | --- | | `visible` | is the target on the screen, not just in the hierarchy? | scrolls to it, then refuses | | `stable` | has it stopped moving? | waits, up to 5 seconds | | `enabled` | does it take input? | waits, up to the implicit wait of 2 seconds, then refuses | | `receivesEvents` | would a finger reach it —…"}], "retrieved": [{"id": "skills/mobile-check/SKILL.md#acting", "heading": "Acting", "path": "skills/mobile-check/SKILL.md", "excerpt": "Every action waits, for up to two seconds, until its target is on screen, **enabled** and holding still, and refuses — with a reason and a remedy — rather than tapping something a user could not: a target under a system dialog or under the keyboard, a control that stays disabled, or a button passed to `type`. - `mobium tap @e5` — tap a ref - `mobium tap \"text=Sign In\"` — tap by locator, no map needed - `mobium tap 54…", "gold": false}, {"id": "skills/mobile-check/SKILL.md#waiting", "heading": "Waiting", "path": "skills/mobile-check/SKILL.md", "excerpt": "Never sleep. Every action already retries for two seconds while the screen settles, so a tap straight after a launch or another tap is fine. When something takes longer than that — a login, a network fetch — wait for the thing itself rather than for a duration: - `mobium wait \"text=Welcome back\"` — until it is on screen - `mobium wait 'text=\"Wi-Fi\"'` — quoted: the whole text, so a part of it on the screen you are lea…", "gold": false}, {"id": "docs/guides/autowait.md#5-waiting-on-purpose-mobium-wait", "heading": "5. Waiting on purpose: `mobium wait`", "path": "docs/guides/autowait.md", "excerpt": "The checks above make each action wait for its own target. For everything else — a result to arrive, a spinner to go, a state to change — say what you are waiting for, instead of sleeping: ``` $ mobium wait testid=loginError --for text --text \"Incorrect username or password.\" --exact testid=loginError says exactly \"Incorrect username or password.\" after 1.631s — @e1 ScrollView (list) ``` It returned as soon as the te…", "gold": false}, {"id": "docs/guides/autowait.md#1-waiting-for-something-to-stop-moving", "heading": "1. Waiting for something to stop moving", "path": "docs/guides/autowait.md", "excerpt": "The Motion Demo's Replay button slides a target in over two seconds. Tap the target the moment after Replay, with no sleep in between: ``` $ mobium tap testid=ignoringReplay tapped testid=ignoringReplay at (540, 1315) $ mobium tap testid=ignoringTarget tapped testid=ignoringTarget at (316, 1472) $ mobium text testid=ignoringResult Ignoring: tapped 2697ms after replay ``` | Just after Replay: the target still sliding …", "gold": false}, {"id": "CHALLENGES#118", "heading": "118. A tap inside a WebView was never checked, and went wherever the page put it", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** MobiumApp's Actionability page, the Obstruction Demo's web counterpart, built once native actions had learned to wait and to refuse. In a WebView none of that applied: a tap resolved its ref to the element's rectangle and touched the center. On a Pixel 7 AVD and an iPhone 17 Pro simulator, `tap` answered \"tapped\" nine times out of nine: | Target | What the tap reached | | --- | --- | | sliding in over t…", "gold": false}], "missed": true, "facts": ["The stable check waits up to 5 seconds for the target to stop moving, then refuses. ⟦stable⟧", "The enabled check waits up to the implicit wait of 2 seconds for the control to take input, then refuses. ⟦implicit wait⟧"], "concern": "skills/mobile-check/SKILL.md#acting says every action waits 'for up to two seconds, until its target is on screen, enabled and holding still'; the code's settleTimeout for holding still is 5 seconds (internal/agent/wait.go:47), as autowait.md says. The skill's sentence understates the stable wait.", "check": "Claude's reading: autowait.md's checks table matches wait.go (implicitWait 2s, settleTimeout 5s) and the enabled poll in resolveNodeOnce uses h.implicitWait. The skill's 'up to two seconds' for all three is the disagreement in concern. The numbers are too common to anchor; the anchors are the check names, and the judge must hold 5 s and 2 s. Verified in: internal/agent/wait.go:32, internal/agent/wait.go:47, internal/agent/handlers.go:1835."}, {"id": "g030", "kind": "fact", "question": "After mobium press back on Android, how can my test tell whether the app went to its previous screen or closed altogether?", "tags": ["behavior", "test-author"], "gold": [{"id": "docs/BACK.md#in-mobium", "heading": "In Mobium", "path": "docs/BACK.md", "excerpt": "Fixed on 2026-10-01, and held by `docs/checks/back.sh`, which passed on the Pixel 8 Pro, both AVDs, the simulator and the iPhone 15 Plus: - `press back` says what back did: \"it left <app>; <app> is in the foreground\", or \"<app> is still in the foreground\", and on iOS what the navigation bar says now. It waits for that outcome by its own clock — a back that left an app handed focus over in about 0.1s — so a back insid…"}], "retrieved": [{"id": "docs/BACK.md#in-mobium", "heading": "In Mobium", "path": "docs/BACK.md", "excerpt": "Fixed on 2026-10-01, and held by `docs/checks/back.sh`, which passed on the Pixel 8 Pro, both AVDs, the simulator and the iPhone 15 Plus: - `press back` says what back did: \"it left <app>; <app> is in the foreground\", or \"<app> is still in the foreground\", and on iOS what the navigation bar says now. It waits for that outcome by its own clock — a back that left an app handed focus over in about 0.1s — so a back insid…", "gold": true}, {"id": "CHALLENGES#204", "heading": "204. Back said \"pressed back\" whether it went back or closed the app", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** Lana, on the Pixel 8 Pro: in MobiumApp a swipe back from any demo closed the app. Measuring it on five devices (docs/BACK.md) showed the app was at fault — it handled no back — and that Mobium would never have said so: `press back` answered \"pressed back\" whether the app went to its home screen or closed, its result claimed nothing, and a test using it saw the same answer for the bug and for the fix. Ba…", "gold": false}, {"id": "docs/BACK.md#back-on-each-platform", "heading": "Back, on each platform", "path": "docs/BACK.md", "excerpt": "What \"back\" is on Android and iOS, what Mobium sends for it, what MobiumApp did with it, and what is still missing before back can be relied on in a test. Every row below was measured on 2026-10-01; nothing here is from documentation alone unless it says so. It started with a report: on the Pixel 8 Pro, open MobiumApp, open any demo, swipe from the right edge — and the whole app closes, where Android users expect the…", "gold": false}, {"id": "CHALLENGES#findings-that-were-not-defects", "heading": "Findings that were not defects", "path": "docs/CHALLENGES.md", "excerpt": "Worth recording because each one closed off an approach that looked obvious. - **Predictive back on Android 15 closes a React Native app.** MobiumApp built with predictive back turned on went back to closing on every back from a demo on the Android 15 AVD, `BackHandler` never called, while on Android 17 — the AVD and the Pixel 8 Pro — it went back to its home screen. React Native 0.86 registers the callback that repl…", "gold": false}, {"id": "docs/ROADMAP.md#under-consideration", "heading": "Under consideration", "path": "docs/ROADMAP.md", "excerpt": "- **Locators for when there is no ref** (written down 2026-10-12). A ref from `map` lasts one map, so an agent has one and a `mobium test` file does not: a hand-written test has the flat `kind=value` locators — text, label, testid, role, class, path, narrowed by `,role=` — which match one element or are refused. That is right on a form and leaves nothing durable on a list. Every Ice Cubes post has a \"…\" (CHALLENGES 2…", "gold": false}], "missed": false, "facts": ["press back says what back did: 'it left <app>; <app> is in the foreground' when back left the app, or '<app> is still in the foreground' when it stayed inside it. ⟦it left ; still in the foreground⟧"], "concern": "", "check": "Claude's reading: BACK.md 'In Mobium' lists the outcome wording; backOutcome in back.go builds exactly those strings. SKILL 'Interruptions and hardware buttons' says the same; I kept gold to BACK.md, so a reviewer may want to add the skill section as an alternative. Verified in: internal/agent/back.go:160."}, {"id": "g031", "kind": "fact", "question": "My CI script needs to tell a tap refused because something covered the target apart from other failures. What exit status and JSON fields should it check?", "tags": ["behavior", "ci-engineer"], "gold": [{"id": "docs/guides/autowait.md#6-reading-a-refusal-from-code", "heading": "6. Reading a refusal from code", "path": "docs/guides/autowait.md", "excerpt": "`--json` gives the structured half of every answer. The same covered tap: ``` $ mobium --json tap testid=fullTarget { \"error\": \"testid=fullTarget failed check receivesEvents: it is covered by \\\"full cover\\\" (button), and was for 2.2s — a touch there would press that instead; wait for it to go, dismiss it, or tap its own ref from app_map if it is what you meant\", \"code\": \"element_not_reachable\", \"message\": \"testid=ful…"}], "retrieved": [{"id": "docs/guides/autowait.md#6-reading-a-refusal-from-code", "heading": "6. Reading a refusal from code", "path": "docs/guides/autowait.md", "excerpt": "`--json` gives the structured half of every answer. The same covered tap: ``` $ mobium --json tap testid=fullTarget { \"error\": \"testid=fullTarget failed check receivesEvents: it is covered by \\\"full cover\\\" (button), and was for 2.2s — a touch there would press that instead; wait for it to go, dismiss it, or tap its own ref from app_map if it is what you meant\", \"code\": \"element_not_reachable\", \"message\": \"testid=ful…", "gold": true}, {"id": "docs/guides/autowait.md#3-refusing-what-is-covered", "heading": "3. Refusing what is covered", "path": "docs/guides/autowait.md", "excerpt": "The Obstruction Demo draws controls over its targets — a full cover, a half cover over the center, an edge cover that leaves the center clear, views that take no touches, an overlay hidden from accessibility, a scrim: ![The Obstruction Demo: a column of buttons, each with something drawn over it](images/autowait-5-covers.jpg) One is covered entirely by another button: ``` $ mobium tap testid=fullTarget error: testid=…", "gold": false}, {"id": "CHALLENGES#118", "heading": "118. A tap inside a WebView was never checked, and went wherever the page put it", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** MobiumApp's Actionability page, the Obstruction Demo's web counterpart, built once native actions had learned to wait and to refuse. In a WebView none of that applied: a tap resolved its ref to the element's rectangle and touched the center. On a Pixel 7 AVD and an iPhone 17 Pro simulator, `tap` answered \"tapped\" nine times out of nine: | Target | What the tap reached | | --- | --- | | sliding in over t…", "gold": false}, {"id": "README.md#actions-wait-and-refuse-what-they-cannot-do", "heading": "Actions wait, and refuse what they cannot do", "path": "README.md", "excerpt": "Before acting, every action waits for its target to exist, be in view, stop moving and be enabled, and scrolls to it if it is off screen. It refuses — rather than taps — a target under a dialog or the keyboard, and `type` refuses what is certainly not a text field. When the app itself has drawn a control over the target, a tap aims at a clear part of it, waits for the cover to go, or refuses and names the cover; anyt…", "gold": false}, {"id": "docs/guides/autowait.md#4-refusing-the-wrong-kind-of-target", "heading": "4. Refusing the wrong kind of target", "path": "docs/guides/autowait.md", "excerpt": "`type` and `fill` go into text fields. Anything that is certainly not one is refused before a key is sent: ``` $ mobium type testid=loginBtn hello error: testid=loginBtn failed check editable: it is a button, not a text field — app_type types into a field; to press it, use app_tap ```", "gold": false}], "missed": false, "facts": ["With --json the refusal has code element_not_reachable, and the CLI exits with status 4. ⟦element_not_reachable ; exit status (4⟧", "details.check names the failed check (receivesEvents for a cover); decide by code and details.check, never by the message text, which may change. ⟦details.check⟧"], "concern": "", "check": "Claude's reading: autowait.md section 6 shows the JSON and names exit 4; mobiumerr.ExitCode returns 4 for element_not_reachable and failedCheck puts check and reason in details. Exit 4 also covers no_such_element and ambiguous_locator, so the code field is what separates them. Verified in: internal/mobiumerr/mobiumerr.go:245, internal/agent/handlers.go:1142."}, {"id": "g032", "kind": "fact", "question": "In my Compose app the Price filter chip is off the right edge of a horizontal row of chips that sits above a large product grid. Which container does mobium scroll-to --direction right swipe to find it?", "tags": ["behavior", "test-author", "new since 7b590a4"], "gold": [{"id": "CHALLENGES#358", "heading": "358. A sideways scroll swiped the list below the row it was for", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** Morpho Market's Price chip, past the right edge of its category row, on the Android 15 emulator: `scroll-to testid=priceFilter --direction right` said \"scrolled right to the end of the list (1 scroll) without bringing it into view\", and the row had not moved. Compose leaves a chip off the row's edge out of the tree, so the loop had no node to ask which container held it, took the largest scrollable on t…"}], "retrieved": [{"id": "CHALLENGES#358", "heading": "358. A sideways scroll swiped the list below the row it was for", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** Morpho Market's Price chip, past the right edge of its category row, on the Android 15 emulator: `scroll-to testid=priceFilter --direction right` said \"scrolled right to the end of the list (1 scroll) without bringing it into view\", and the row had not moved. Compose leaves a chip off the row's edge out of the tree, so the loop had no node to ask which container held it, took the largest scrollable on t…", "gold": true}, {"id": "CHALLENGES#241", "heading": "241. A chip taller than its row was scrolled for fifteen times", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** the same search. A tap on the Podcasts filter chip swiped the results down fifteen times and gave up — \"on the screen but never scrolled fully into view\" — with the chip in plain sight throughout, and the swipes left the results scrolled over it. The chips are 36 points high in a horizontal scroll view 34 points high, a point over each edge, and a target had to fit inside its container's view to count a…", "gold": false}, {"id": "CHALLENGES#322", "heading": "322. A chip in plain sight, a point past its row, was swiped for", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** a SwiftUI checkout app written to be tested (Morpho Market, mobiumdev/morpho-market), on the iPhone 17 Pro simulator, iOS 26.5. Its size and category chips are capsules with an outline, and SwiftUI reports each one's frame a point outside its horizontal scroll view: 34 points high from y=452 in a row from y=453 to 486, and the first chip a point past the leading edge too. A target had to fit inside its …", "gold": false}, {"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": false}, {"id": "CHALLENGES#176", "heading": "176. Every Compose icon button mapped twice", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** `mobium map` on Seal, a Jetpack Compose app from F-Droid, on the first screen — the first Compose app this project had driven. Its three icon buttons came out as six entries: \"Settings\", and \"Settings (button)\". Compose wraps an icon button in a tooltip box, long-clickable so a long press shows the tooltip, and lays it out a pixel off the button's own bounds: `[32,95][158,221]` around `[33,96][159,222]`…", "gold": false}], "missed": false, "facts": ["A scroll given a direction swipes the largest scrollable whose class says it scrolls that way; Compose reports a horizontalScroll row as HorizontalScrollView, so the chip row is swiped, not the grid. ⟦HorizontalScrollView⟧", "An up or down scroll never swipes a row that says it scrolls sideways; nothing infers an axis that no class states. ⟦never swipes⟧"], "concern": "skills/mobile-check/SKILL.md#reaching-things-below-the-fold says scroll-to is for 'Vertical lists only. For a horizontal pager or carousel use mobium swipe left', but scroll-to takes --direction left/right (cmd/mobium/scroll.go:17 and :27, example 'a horizontal pager') and scrollContainerFor picks a sideways row (internal/agent/scroll.go:893). The skill is stale.", "check": "Claude's reading: CHALLENGES 358 (#262, after the pin) is the only description; scrollContainerFor in scroll.go matches it line for line. The skill's 'vertical lists only' contradicts the code; see concern. Verified in: internal/agent/scroll.go:893, cmd/mobium/scroll.go:27."}, {"id": "g033", "kind": "multi", "question": "mobium press back --gesture is refused on my Android emulator, while plain press back works. Why, and how do I check which mode the device is in?", "tags": ["troubleshooting", "test-author"], "gold": [{"id": "docs/BACK.md#mobiumapp-as-shipped", "heading": "MobiumApp as shipped", "path": "docs/BACK.md", "excerpt": "The same on all three devices, gesture navigation: | Input | After | Process | Activities | Reopened at | | --- | --- | --- | --- | --- | | key | launcher | alive | 0 | home | | right edge | launcher | alive | 0 | home | | left edge | launcher | alive | 0 | home | So the report is exact: every back from a demo left the app, its activity was destroyed, and reopening it started again at home. Settings, given the same t…"}, {"id": "docs/BACK.md#in-mobium", "heading": "In Mobium", "path": "docs/BACK.md", "excerpt": "Fixed on 2026-10-01, and held by `docs/checks/back.sh`, which passed on the Pixel 8 Pro, both AVDs, the simulator and the iPhone 15 Plus: - `press back` says what back did: \"it left <app>; <app> is in the foreground\", or \"<app> is still in the foreground\", and on iOS what the navigation bar says now. It waits for that outcome by its own clock — a back that left an app handed focus over in about 0.1s — so a back insid…"}], "retrieved": [{"id": "skills/mobile-check/SKILL.md#interruptions-and-hardware-buttons", "heading": "Interruptions and hardware buttons", "path": "skills/mobile-check/SKILL.md", "excerpt": "```sh mobium press back # primary navigation on Android; says where it went mobium press back --gesture # the swipe in from the edge; the only back on iOS mobium press home # says the launcher came forward mobium lock lock # a state, not a toggle mobium call ring # then accept, or hang mobium sms \"your code is 123456\" mobium timezone Asia/Tokyo mobium notifications # what is in the shade? mobium notifications --post …", "gold": false}, {"id": "docs/BACK.md#in-mobium", "heading": "In Mobium", "path": "docs/BACK.md", "excerpt": "Fixed on 2026-10-01, and held by `docs/checks/back.sh`, which passed on the Pixel 8 Pro, both AVDs, the simulator and the iPhone 15 Plus: - `press back` says what back did: \"it left <app>; <app> is in the foreground\", or \"<app> is still in the foreground\", and on iOS what the navigation bar says now. It waits for that outcome by its own clock — a back that left an app handed focus over in about 0.1s — so a back insid…", "gold": true}, {"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": false}, {"id": "docs/BACK.md#ios", "heading": "iOS", "path": "docs/BACK.md", "excerpt": "iOS has no system back. Going back is the app's: a navigation bar's back button, and, for a `UINavigationController`, a swipe. Mobium refuses `press back` there by design (it is not an event iOS sends); `press back --gesture` sends the swipe, starting in the navigation bar, since the measurements below found a swipe over a list row taken by the row ([In Mobium](#in-mobium)). | | MobiumApp | Control | | --- | --- | --…", "gold": false}], "missed": false, "facts": ["An edge swipe is back only in gesture navigation; with three-button navigation it does nothing, so press back --gesture is refused there and the back button (plain press back) is the user's back. ⟦three-button⟧", "The mode can be read with settings get secure navigation_mode (2 gestures, 0 three buttons), and mobium devices names an Android device's navigation mode. ⟦navigation_mode⟧"], "concern": "", "check": "Claude's reading: BACK.md 'MobiumApp as shipped' measured that edge swipes do nothing in three-button mode and gives navigation_mode values; 'In Mobium' says --gesture is refused on button navigation and devices names the mode. gestureBack returns unsupported unless the mode is gestures. Verified in: internal/agent/back.go:46, internal/agent/back.go:51."}, {"id": "g034", "kind": "fact", "question": "mobium contexts lists only NATIVE_APP for my app even though a screen clearly shows web content. Why can't Mobium see the WebView, and what has to change?", "tags": ["troubleshooting", "test-author"], "gold": [{"id": "README.md#hybrid-apps-and-webviews", "heading": "Hybrid apps and WebViews", "path": "README.md", "excerpt": "A hybrid app's web content is not usable through the accessibility tree, so Mobium attaches to the WebView, and switching context changes what `map` and `tap` operate on: ``` $ mobium contexts NATIVE_APP (current) WEBVIEW_com.example — Checkout https://shop.example/cart $ mobium context WEBVIEW_com.example $ mobium map @e1 Promo code (input) @e2 Apply (button) $ mobium tap @e2 tapped @e2 at (462, 397) in WEBVIEW_com.…"}], "retrieved": [{"id": "skills/mobile-check/SKILL.md#hybrid-apps-webviews", "heading": "Hybrid apps (WebViews)", "path": "skills/mobile-check/SKILL.md", "excerpt": "Web content inside an app is a separate context: ```sh mobium contexts # NATIVE_APP, WEBVIEW_com.example mobium context WEBVIEW_com.example # map and tap now work on the page mobium context NATIVE_APP # back to the native shell ``` This works on **both platforms**. Android WebViews must be debuggable (`setWebContentsDebuggingEnabled(true)`) and iOS WKWebViews must be inspectable (`webView.isInspectable = true` on iOS…", "gold": false}, {"id": "README.md#hybrid-apps-and-webviews", "heading": "Hybrid apps and WebViews", "path": "README.md", "excerpt": "A hybrid app's web content is not usable through the accessibility tree, so Mobium attaches to the WebView, and switching context changes what `map` and `tap` operate on: ``` $ mobium contexts NATIVE_APP (current) WEBVIEW_com.example — Checkout https://shop.example/cart $ mobium context WEBVIEW_com.example $ mobium map @e1 Promo code (input) @e2 Apply (button) $ mobium tap @e2 tapped @e2 at (462, 397) in WEBVIEW_com.…", "gold": true}, {"id": "docs/APP-TYPES.md#hybrid", "heading": "Hybrid", "path": "docs/APP-TYPES.md", "excerpt": "A native app with a WebView inside it. The article's point that a hybrid app is *technically a subcategory of native* — because the outermost component is native — is exactly the shape of Mobium's context model: `NATIVE_APP` is the shell, and each page is its own `WEBVIEW_<package>` context. The more useful observation is the one about **ratio**: some hybrid apps are almost entirely WebView, others expose a small one…", "gold": false}, {"id": "CHALLENGES#312", "heading": "312. `find` inside a WebView answered from the native screen", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** giving WebViews locators (ROADMAP, locators item 4) and checking them on MobiumApp's Actionability and Frames pages, each tap judged by what the page said it reached. With a WebView's context selected, every action named the page's element, but `find role=button` listed the app's own Back button first and then the page's buttons as the platform's accessibility saw them: `app_find` never asked which cont…", "gold": false}, {"id": "CHALLENGES#138", "heading": "138. On iOS, `contexts` listed the pages of apps not in front", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** listing contexts on the iPhone 15 Plus with Wikipedia in front and seeing Safari's page; reproduced with MobiumApp, three times in three, after opening a page in Safari and coming back. Every application webinspectord knew was asked for its pages, and every page was listed, whichever app was on screen. Switching to one attached a page that was not on screen, and a tap into it would have been aimed throu…", "gold": false}], "missed": false, "facts": ["A WebView is reachable only if the app opted in: WebView.setWebContentsDebuggingEnabled(true) on Android, isInspectable on iOS 16.4 and later; neither can be forced from outside. ⟦setWebContentsDebuggingEnabled(true) ; isInspectable⟧"], "concern": "", "check": "Claude's reading: README's hybrid section states the opt-in; noWebViewsHint gives the same remedy per platform when contexts finds none, and adds that a page must be open on iOS. SKILL 'Hybrid apps' repeats it; gold kept to README. Verified in: internal/agent/webview.go:702, internal/agent/webview.go:108."}, {"id": "g035", "kind": "fact", "question": "On an iPhone, my tap on Add to Cart is refused because the on-screen keyboard covers the button. How do I get the keyboard out of the way?", "tags": ["troubleshooting", "agent-builder"], "gold": [{"id": "skills/mobile-check/SKILL.md#when-things-fail", "heading": "When things fail", "path": "skills/mobile-check/SKILL.md", "excerpt": "Mobium's errors say what to do; read them rather than retrying blindly. Every failure also carries a **code**, so you can act on the kind without parsing the sentence: `--json` prints it (`\"code\": \"no_such_element\"`, with a `remedy` and `details`), and the exit status groups it: | Exit | Codes | What to do | | --- | --- | --- | | 2 | `invalid_argument` | fix the command; retrying it unchanged cannot help | | 3 | `no_…"}], "retrieved": [{"id": "CHALLENGES#325", "heading": "325. A button under the keyboard was blamed on another screen", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** checking 322's fix on a SwiftUI checkout app written to be tested (Morpho Market, mobiumdev/morpho-market), on the iPhone 17 Pro simulator, iOS 26.5. With the keyboard up after typing a gift card's email, Add to Cart sat under the keys, and the tap was refused: \"another screen of the app is in front of it — close the screen in front first\". There was no such screen. With the keyboard up, SwiftUI reports…", "gold": false}, {"id": "CHALLENGES#107", "heading": "107. A tap on a button under the keyboard reported success", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** the iOS login demo, where Log In sat under the keyboard; the app's layout was fixed then, and the Dialog Demo's pinned button is the case kept on purpose. The keyboard is the dialog case one layer over, in the same two shapes. On iOS the keyboard is an `XCUIElementTypeKeyboard` in the app's tree, and what it covers stays there, marked not visible — the field being typed into included — so a locator reso…", "gold": false}, {"id": "CHALLENGES#184", "heading": "184. Reading a label under the keyboard was refused as if it were a tap", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** MobiumApp's OTP Demo on an iPhone 17 Pro simulator, typing a code into the six boxes and reading back the line that says what they hold. The one-time-code number pad was up over it, and `app_text` answered \"failed check receivesEvents: the keyboard is over it\". Nothing was being touched: iOS keeps what the keyboard covers in the tree, with its text, and the text was right there — `app_find` printed it i…", "gold": false}, {"id": "docs/guides/autowait.md#3-refusing-what-is-covered", "heading": "3. Refusing what is covered", "path": "docs/guides/autowait.md", "excerpt": "The Obstruction Demo draws controls over its targets — a full cover, a half cover over the center, an edge cover that leaves the center clear, views that take no touches, an overlay hidden from accessibility, a scrim: ![The Obstruction Demo: a column of buttons, each with something drawn over it](images/autowait-5-covers.jpg) One is covered entirely by another button: ``` $ mobium tap testid=fullTarget error: testid=…", "gold": false}, {"id": "CHALLENGES#230", "heading": "230. With the iOS keyboard up, every action in a WebView was refused", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** typing into MobiumApp's cross-origin frame field on the iPhone simulator (CHALLENGES 229), and then on its Web form, which has no frames: once a tap on a web field raised the keyboard, a `type` or a `tap` in the same WebView was refused — \"the WebView element is 584 CSS pixels tall but the page's viewport is 571, so the page does not fill its host\". That check was written for mobile Safari, whose chrome…", "gold": false}], "missed": true, "facts": ["On an iPhone, which has no hide key, use mobium keyboard --key enter; elsewhere mobium keyboard --hide. ⟦keyboard --key enter ; keyboard --hide⟧"], "concern": "", "check": "Claude's reading: the skill's receivesEvents bullet gives both commands; handlers.go's hideKeyboard remedy text says the same, naming the iPhone's missing hide key. CHALLENGES 325 shows keyboard --key enter working on a simulator but is not needed. Verified in: internal/agent/handlers.go:1237."}, {"id": "g036", "kind": "fact", "question": "Can Mobium move the two thumbs of a range slider in an Android app built with Views, using the Material Components RangeSlider rather than Compose?", "tags": ["support", "test-author", "new since 7b590a4"], "gold": [{"id": "docs/ROADMAP.md#under-consideration", "heading": "Under consideration", "path": "docs/ROADMAP.md", "excerpt": "- **Locators for when there is no ref** (written down 2026-10-12). A ref from `map` lasts one map, so an agent has one and a `mobium test` file does not: a hand-written test has the flat `kind=value` locators — text, label, testid, role, class, path, narrowed by `,role=` — which match one element or are refused. That is right on a form and leaves nothing durable on a list. Every Ice Cubes post has a \"…\" (CHALLENGES 2…"}], "retrieved": [{"id": "docs/ROADMAP.md#under-consideration", "heading": "Under consideration", "path": "docs/ROADMAP.md", "excerpt": "- **Locators for when there is no ref** (written down 2026-10-12). A ref from `map` lasts one map, so an agent has one and a `mobium test` file does not: a hand-written test has the flat `kind=value` locators — text, label, testid, role, class, path, narrowed by `,role=` — which match one element or are refused. That is right on a form and leaves nothing durable on a list. Every Ice Cubes post has a \"…\" (CHALLENGES 2…", "gold": true}, {"id": "CHALLENGES#320", "heading": "320. A two-thumb slider built from ARIA was not in `map`, and one built from ranges moved the wrong thumb", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** measuring two-thumb sliders, as pages build them, on MobiumApp's Slider Demo: Price, two `<input type=\"range\">` laid over one track, the minimum kept at or below the maximum by the page; and Hours, two `role=\"slider\"` thumbs on a drawn track, moved by a finger or the arrow keys, the way component libraries build one. Hours was not in `map` at all: the list of a page's elements had no `[role=slider]`. Pr…", "gold": false}, {"id": "CHALLENGES#357", "heading": "357. A two-thumb slider: a fill that moved nothing said it moved, and a thumb at the edge closed the app", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** native two-thumb sliders (ROADMAP, \"Sliders\"), on a price range added to Morpho Market for them — Material 3's `RangeSlider` on Android, and on iOS a control the app draws, since SwiftUI has none. Three things, each measured on the Android 15 emulator and the iPhone 17 Pro simulator: - **A fill that moved nothing was reported as moved.** Material reports each thumb as a seek bar the size of the thumb — …", "gold": false}, {"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": false}], "missed": false, "facts": ["Native two-thumb sliders are done for Material 3's RangeSlider in Compose and an iOS app's own (since 2026-10-22); a View-system RangeSlider (Material Components) is not yet supported, nor measured on a phone. ⟦View-system ; Material 3⟧"], "concern": "", "check": "Claude's reading: ROADMAP 'Under consideration', Sliders entry, says not yet for a View-system RangeSlider; RangeThumb needs two slider children under one parent, which the Compose and iOS builds give — a View RangeSlider is one view, so it would not be recognized. That last point is my reading of the code, not measured. Verified in: internal/uitree/rangethumb.go:7."}, {"id": "g037", "kind": "fact", "question": "Why does mobium tap @e5 look the element up again instead of tapping the coordinates that mobium map printed for it?", "tags": ["rationale", "new-user"], "gold": [{"id": "README.md#refs", "heading": "Refs", "path": "README.md", "excerpt": "`mobium map` snapshots the accessibility hierarchy, keeps the nodes a person could act on, and gives each one the most durable locator that identifies it uniquely — a resource-id if there is one, then an accessibility label, then visible text, and a sibling path only as a last resort. `mobium tap @e5` **re-snapshots and re-resolves** that locator before touching anything. It never replays the coordinates from the map…"}], "retrieved": [{"id": "README.md#refs", "heading": "Refs", "path": "README.md", "excerpt": "`mobium map` snapshots the accessibility hierarchy, keeps the nodes a person could act on, and gives each one the most durable locator that identifies it uniquely — a resource-id if there is one, then an accessibility label, then visible text, and a sibling path only as a last resort. `mobium tap @e5` **re-snapshots and re-resolves** that locator before touching anything. It never replays the coordinates from the map…", "gold": true}, {"id": "docs/ARCHITECTURE.md#one-call-end-to-end", "heading": "One call, end to end", "path": "docs/ARCHITECTURE.md", "excerpt": "`mobium tap @e5`, on Android with the default backend: ```mermaid sequenceDiagram participant CLI as mobium tap @e5 participant D as daemon participant A as internal/agent participant U as uiautomator2 driver participant S as UiAutomator2 server CLI->>D: tools/call app_tap {target: \"@e5\"} D->>A: dispatch A->>A: look up @e5's locator from the last map loop until settled, or the wait runs out A->>U: snapshot U->>S: GET…", "gold": false}, {"id": "skills/mobile-check/SKILL.md#core-workflow", "heading": "Core Workflow", "path": "skills/mobile-check/SKILL.md", "excerpt": "Every automation follows the same loop: 1. **Map**: `mobium map` — lists what is on screen as `@e1`, `@e2`, … 2. **Act**: `mobium tap @e5`, `mobium type @e2 \"text\"`, `mobium swipe up` 3. **Re-map**: after anything that changes the screen, run `mobium map` again **Refs are only valid for the screen they were taken from.** A ref is re-resolved against a fresh snapshot before every action, so a stale one fails loudly ra…", "gold": false}, {"id": "skills/mobile-check/SKILL.md#acting", "heading": "Acting", "path": "skills/mobile-check/SKILL.md", "excerpt": "Every action waits, for up to two seconds, until its target is on screen, **enabled** and holding still, and refuses — with a reason and a remedy — rather than tapping something a user could not: a target under a system dialog or under the keyboard, a control that stays disabled, or a button passed to `type`. - `mobium tap @e5` — tap a ref - `mobium tap \"text=Sign In\"` — tap by locator, no map needed - `mobium tap 54…", "gold": false}, {"id": "skills/mobile-check/SKILL.md#when-things-fail", "heading": "When things fail", "path": "skills/mobile-check/SKILL.md", "excerpt": "Mobium's errors say what to do; read them rather than retrying blindly. Every failure also carries a **code**, so you can act on the kind without parsing the sentence: `--json` prints it (`\"code\": \"no_such_element\"`, with a `remedy` and `details`), and the exit status groups it: | Exit | Codes | What to do | | --- | --- | --- | | 2 | `invalid_argument` | fix the command; retrying it unchanged cannot help | | 3 | `no_…", "gold": false}], "missed": false, "facts": ["tap re-snapshots and re-resolves the ref's locator before touching anything. ⟦re-resolves / re-snapshots⟧", "It never replays map's coordinates because the screen moves between commands, and a tap at a stale point fails silently; a locator that became ambiguous is refused rather than guessed. ⟦stale point⟧"], "concern": "", "check": "Claude's reading: README 'Refs' gives the reason; the comment on resolveNode says every action re-snapshots, since acting on a node from an older snapshot lands on whatever moved into its place. Verified in: internal/agent/handlers.go:1548."}, {"id": "g038", "kind": "fact", "question": "Why does Mobium refuse press-tap (hold one finger, then tap with a second) on an iPhone instead of just sending it?", "tags": ["rationale", "test-author"], "gold": [{"id": "docs/GESTURES.md#three-ways-a-second-finger-went-wrong", "heading": "Three ways a second finger went wrong", "path": "docs/GESTURES.md", "excerpt": "All three were found by a witness, and none was visible to the tool, which reported every gesture as delivered until the last one, which reported a failure and left the device unable to accept any touch at all. **UiAutomator2 forgets a finger that pauses.** It builds each step's Android `MotionEvent` from the fingers that have an event *in that step*, and counts the fingers already down from the same events. A holdin…"}], "retrieved": [{"id": "docs/GESTURES.md#three-ways-a-second-finger-went-wrong", "heading": "Three ways a second finger went wrong", "path": "docs/GESTURES.md", "excerpt": "All three were found by a witness, and none was visible to the tool, which reported every gesture as delivered until the last one, which reported a failure and left the device unable to accept any touch at all. **UiAutomator2 forgets a finger that pauses.** It builds each step's Android `MotionEvent` from the fingers that have an event *in that step*, and counts the fingers already down from the same events. A holdin…", "gold": true}, {"id": "CHALLENGES#86", "heading": "86. On Android 16 and later, one press-tap breaks injected touch for the whole device", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** the gesture check on a Pixel 8 Pro (Android 17), where press-tap failed with UiAutomator2's \"Unable to perform W3C actions\" — and then so did everything after it, plain taps included, and `adb shell input tap` too. UiAutomator2 (10.6.6, the newest release) stamps each event with the down time of the finger that produced it (`startTimestamp + event.startDelta`, the chain's own `pointerDown`). Android's c…", "gold": false}, {"id": "CHALLENGES#149", "heading": "149. `double-tap` reached a React Native control on iOS as one press", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** a person, as the control ROADMAP had asked for: Lana double-tapped MobiumApp's Press target on the iPhone 15 Plus and it counted two presses 200ms apart, where `double-tap` on the same target counted one. Mobium used WebDriverAgent's own double-tap endpoint, Apple's primitive, and a React Native `Pressable` reports that as one press — which 70 had taken for the Pressable coalescing any double tap. The W…", "gold": false}, {"id": "docs/guides/autowait.md#auto-wait-what-an-action-waits-for-and-what-it-refuses", "heading": "Auto-wait: what an action waits for, and what it refuses", "path": "docs/guides/autowait.md", "excerpt": "A tap in Mobium is not a touch at some coordinates. Before it touches anything, an action finds its target on a fresh read of the screen and checks that a finger could really press it. It **waits** for the checks that time can fix, and **refuses** the ones it can't — with a reason, never with a touch somewhere else reported as success. This guide goes through each check on [MobiumApp](https://github.com/mobiumdev/mob…", "gold": false}, {"id": "docs/GESTURES.md#the-chart", "heading": "The chart", "path": "docs/GESTURES.md", "excerpt": "Three sources name the gestures, and they agree more than they differ: the familiar touch-gesture reference chart (tap, double tap, drag, flick, pinch, spread, press, press and tap, press and drag, rotate), Apple's Human Interface Guidelines (tap, swipe, drag, touch and hold, double tap, zoom, rotate), and Android's Compose gesture guide (tap, double tap, long press and press through `detectTapGestures`; drag in thre…", "gold": false}], "missed": false, "facts": ["XCTest (through WebDriverAgent) gives a finger that lands after the gesture began an extra zero-length touch at its target at time zero. ⟦zero-length touch⟧", "An app can read that instant touch as a tap before the gesture, so Mobium refuses press-tap and press-drag on iOS rather than send a gesture that is also something else; multi-finger taps are unaffected. ⟦refuses press-tap⟧"], "concern": "", "check": "Claude's reading: GESTURES.md 'Three ways a second finger went wrong' explains it; errLateFinger in multitouch.go carries the same reason. Android 16+ is refused for a different reason (UiAutomator2's down time), in the same section's second part — not asked here. Verified in: internal/mobiumdriver/multitouch.go:181."}, {"id": "g039", "kind": "unanswerable", "question": "How do I raise Mobium's implicit wait so every tap waits up to 10 seconds for its target instead of 2?", "tags": ["how-to", "test-author"], "gold": [], "retrieved": [{"id": "skills/mobile-check/SKILL.md#waiting", "heading": "Waiting", "path": "skills/mobile-check/SKILL.md", "excerpt": "Never sleep. Every action already retries for two seconds while the screen settles, so a tap straight after a launch or another tap is fine. When something takes longer than that — a login, a network fetch — wait for the thing itself rather than for a duration: - `mobium wait \"text=Welcome back\"` — until it is on screen - `mobium wait 'text=\"Wi-Fi\"'` — quoted: the whole text, so a part of it on the screen you are lea…", "gold": false}, {"id": "skills/mobile-check/SKILL.md#acting", "heading": "Acting", "path": "skills/mobile-check/SKILL.md", "excerpt": "Every action waits, for up to two seconds, until its target is on screen, **enabled** and holding still, and refuses — with a reason and a remedy — rather than tapping something a user could not: a target under a system dialog or under the keyboard, a control that stays disabled, or a button passed to `type`. - `mobium tap @e5` — tap a ref - `mobium tap \"text=Sign In\"` — tap by locator, no map needed - `mobium tap 54…", "gold": false}, {"id": "docs/guides/autowait.md#1-waiting-for-something-to-stop-moving", "heading": "1. Waiting for something to stop moving", "path": "docs/guides/autowait.md", "excerpt": "The Motion Demo's Replay button slides a target in over two seconds. Tap the target the moment after Replay, with no sleep in between: ``` $ mobium tap testid=ignoringReplay tapped testid=ignoringReplay at (540, 1315) $ mobium tap testid=ignoringTarget tapped testid=ignoringTarget at (316, 1472) $ mobium text testid=ignoringResult Ignoring: tapped 2697ms after replay ``` | Just after Replay: the target still sliding …", "gold": false}, {"id": "docs/guides/graybox-tutorial.md#1-the-test", "heading": "1. The test", "path": "docs/guides/graybox-tutorial.md", "excerpt": "The Busy Demo's **Refresh quietly** starts 0.4 to 1.6 seconds of work and leaves the old rows up while it runs; then a new generation of rows replaces them. Tapping a row says whether it was `current` or `stale`. The test taps the refresh, then Row B, and expects the row to be current — five times, each from a fresh app: ``` busy-tests/ mobium.config.json tests/ busy.test.json ``` ```json { \"testDir\": \"tests\", \"proje…", "gold": false}, {"id": "docs/guides/graybox.md#what-an-action-does", "heading": "What an action does", "path": "docs/guides/graybox.md", "excerpt": "Before an action finds its target, it waits until the app has nothing in flight. The result says what it waited for (the iPhone): ``` $ mobium tap testid=busyQuiet tapped testid=busyQuiet at (645, 1011) gray box: waited 35 ms for the app to go idle $ mobium tap testid=busyRowB tapped testid=busyRowB at (645, 1218) gray box: waited 1018 ms for the app to go idle (busy: quiet) $ mobium text testid=busyOutcome row B, ge…", "gold": false}], "missed": false, "facts": [], "concern": "", "check": "Claude's reading: the docs state the 2-second implicit wait but never say whether it can be changed; no flag, env var or argument sets it — implicitWait is a constant (wait.go:32) whose comment says longer waits belong in an explicit wait. A retriever will return the checks table and mobium wait's --timeout, which answers a different question. Nearest sections: docs/guides/autowait.md#the-checks, skills/mobile-check/SKILL.md#acting, docs/guides/autowait.md#5-waiting-on-purpose-mobium-wait. Verified in: internal/agent/wait.go:32."}, {"id": "g040", "kind": "unanswerable", "question": "How long does mobium long-press hold the press by default when I don't pass --duration?", "tags": ["behavior", "test-author"], "gold": [], "retrieved": [{"id": "CHALLENGES#126", "heading": "126. On iOS a drag never held before it moved", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** the same run on an iPhone 17 Pro simulator. MobiumApp's drop zone measures the hold before a drag moves: asked for 1500ms, it read 183ms, three times in three, while the hold before the finger lifted arrived in full at 1517ms. The drop still succeeded, which is why `GESTURES.md` had drag down as working on iOS; but a list that arms reordering on a long press would never have armed. WebDriverAgent shorte…", "gold": false}, {"id": "skills/mobile-check/SKILL.md#waiting", "heading": "Waiting", "path": "skills/mobile-check/SKILL.md", "excerpt": "Never sleep. Every action already retries for two seconds while the screen settles, so a tap straight after a launch or another tap is fine. When something takes longer than that — a login, a network fetch — wait for the thing itself rather than for a duration: - `mobium wait \"text=Welcome back\"` — until it is on screen - `mobium wait 'text=\"Wi-Fi\"'` — quoted: the whole text, so a part of it on the screen you are lea…", "gold": false}, {"id": "skills/mobile-check/SKILL.md#acting", "heading": "Acting", "path": "skills/mobile-check/SKILL.md", "excerpt": "Every action waits, for up to two seconds, until its target is on screen, **enabled** and holding still, and refuses — with a reason and a remedy — rather than tapping something a user could not: a target under a system dialog or under the keyboard, a control that stays disabled, or a button passed to `type`. - `mobium tap @e5` — tap a ref - `mobium tap \"text=Sign In\"` — tap by locator, no map needed - `mobium tap 54…", "gold": false}, {"id": "docs/guides/autowait.md#5-waiting-on-purpose-mobium-wait", "heading": "5. Waiting on purpose: `mobium wait`", "path": "docs/guides/autowait.md", "excerpt": "The checks above make each action wait for its own target. For everything else — a result to arrive, a spinner to go, a state to change — say what you are waiting for, instead of sleeping: ``` $ mobium wait testid=loginError --for text --text \"Incorrect username or password.\" --exact testid=loginError says exactly \"Incorrect username or password.\" after 1.631s — @e1 ScrollView (list) ``` It returned as soon as the te…", "gold": false}, {"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": false}], "missed": false, "facts": [], "concern": "", "check": "Claude's reading: the default is 800ms in code (CLI flag and app_long_press's duration_ms), but no corpus section states it; GESTURES only says a 50ms hold must read as a tap, and FLAGS lists --duration without a default. CHALLENGES 86 mentions --lead-ms 800 for press-tap, a likely false match. Nearest sections: docs/GESTURES.md#the-chart, skills/mobile-check/SKILL.md#acting, docs/FLAGS.md#commands-and-what-they-send. Verified in: cmd/mobium/swipe.go:75, internal/agent/handlers.go:2466."}, {"id": "g041", "kind": "fact", "question": "I recorded a flow in mobium inspect. How do I get it as a Python program instead of a .test.json file, and which device will that program drive?", "tags": ["how-to", "test-author", "new since 7b590a4"], "gold": [{"id": "docs/guides/inspector.md#5-download-it-as-code", "heading": "5. Download it as code", "path": "docs/guides/inspector.md", "excerpt": "Next to **Download**, pick the language: the test file, or a program in Python, JavaScript, Go, Java or .NET. Every step is one tool call and every client has every tool, so the program is the same steps through the client's own methods, starting from the app launched fresh. The Table Demo recording above, as Python: ```python # Recorded with mobium inspect. from mobium import start with start() as device: device.ter…"}], "retrieved": [{"id": "docs/guides/inspector.md#5-download-it-as-code", "heading": "5. Download it as code", "path": "docs/guides/inspector.md", "excerpt": "Next to **Download**, pick the language: the test file, or a program in Python, JavaScript, Go, Java or .NET. Every step is one tool call and every client has every tool, so the program is the same steps through the client's own methods, starting from the app launched fresh. The Table Demo recording above, as Python: ```python # Recorded with mobium inspect. from mobium import start with start() as device: device.ter…", "gold": true}, {"id": "docs/guides/inspector.md#4-record-a-test", "heading": "4. Record a test", "path": "docs/guides/inspector.md", "excerpt": "A test starts from a freshly launched app, so a recording should too: **Start from a fresh app** stops the app in front and launches it again, as `mobium test` does before each test, and starts recording. From there, every action is a step. Recorded on the Login Demo: ```json { \"app\": \"dev.mobium.mobiumapp\", \"description\": \"Recorded with mobium inspect.\", \"tests\": [ { \"name\": \"recorded\", \"steps\": [ {\"tap\": \"text=Logi…", "gold": false}, {"id": "docs/guides/test-runner.md#the-commands", "heading": "The commands", "path": "docs/guides/test-runner.md", "excerpt": "| Command | What it does | | --- | --- | | `mobium test` | runs every `*.test.json` under the config's `testDir`, on every project | | `mobium test tests/login.test.json` | runs one file, or every file under a directory | | `mobium test -g login` | runs the tests whose title — \"file › name\" — matches a regular expression | | `mobium test --last-failed` | runs only the tests that failed last time | | `mobium test --pr…", "gold": false}, {"id": "docs/DEVELOPMENT.md#5-work-on-a-client", "heading": "5. Work on a client", "path": "docs/DEVELOPMENT.md", "excerpt": "Each client's tests start a fake `mobium` and need no device: | Client | Its tests | Run a program against it from this clone | | --- | --- | --- | | Python | `make clients` | `pip install ./clients/python` in a virtualenv | | JavaScript | `make clients` | `npm install ./clients/javascript` | | Go | `make test` | `go mod edit -replace=github.com/mobiumdev/mobium/clients/go=<path to this clone>/clients/go` in your mod…", "gold": false}, {"id": "docs/checks/README.md#device-checks", "heading": "Device checks", "path": "docs/checks/README.md", "excerpt": "Scripts that drive a real flow end to end through mobium's CLI and assert on the result. Not part of `make ci` — they need a device — but they are the thing [RELEASE-CHECKLIST.md](../RELEASE-CHECKLIST.md) asks you to run, written down so nobody has to invent them again. ```sh ./docs/checks/calculator.sh emulator-5554 ./docs/checks/calculator.sh <serial> ``` Getting a device attached in the first place is [../SETUP.md…", "gold": false}], "missed": false, "facts": ["Next to Download in the inspector, pick the language: the test file, or a program in Python, JavaScript, Go, Java or .NET. ⟦pick the language⟧", "The program starts from the app launched fresh (terminated, then launched), as mobium test starts each test. ⟦the app launched fresh⟧", "The program names no device: start() takes the only one running, and start(device=...) names one. ⟦start(device=...)⟧"], "concern": "", "check": "Claude's reading: inspector.md section 5 (added in #261, after 7b590a4) answers all three; codegen.Program prepends app_terminate and app_launch, and the Python writer emits `with start() as device:`. The device-selection part comes from the same section, so the question stays a single fact. Verified in: internal/codegen/codegen.go:24, internal/codegen/codegen.go:46, internal/codegen/languages.go:21, internal/inspect/inspect.go:464."}, {"id": "g042", "kind": "fact", "question": "While I click through my app in the inspector, how can I have the recording written into a file in my project as it grows, and which kinds of file can it write?", "tags": ["how-to", "test-author", "new since 7b590a4"], "gold": [{"id": "docs/guides/inspector.md#4-record-a-test", "heading": "4. Record a test", "path": "docs/guides/inspector.md", "excerpt": "A test starts from a freshly launched app, so a recording should too: **Start from a fresh app** stops the app in front and launches it again, as `mobium test` does before each test, and starts recording. From there, every action is a step. Recorded on the Login Demo: ```json { \"app\": \"dev.mobium.mobiumapp\", \"description\": \"Recorded with mobium inspect.\", \"tests\": [ { \"name\": \"recorded\", \"steps\": [ {\"tap\": \"text=Logi…"}], "retrieved": [{"id": "docs/guides/inspector.md#5-download-it-as-code", "heading": "5. Download it as code", "path": "docs/guides/inspector.md", "excerpt": "Next to **Download**, pick the language: the test file, or a program in Python, JavaScript, Go, Java or .NET. Every step is one tool call and every client has every tool, so the program is the same steps through the client's own methods, starting from the app launched fresh. The Table Demo recording above, as Python: ```python # Recorded with mobium inspect. from mobium import start with start() as device: device.ter…", "gold": false}, {"id": "docs/guides/inspector.md#4-record-a-test", "heading": "4. Record a test", "path": "docs/guides/inspector.md", "excerpt": "A test starts from a freshly launched app, so a recording should too: **Start from a fresh app** stops the app in front and launches it again, as `mobium test` does before each test, and starts recording. From there, every action is a step. Recorded on the Login Demo: ```json { \"app\": \"dev.mobium.mobiumapp\", \"description\": \"Recorded with mobium inspect.\", \"tests\": [ { \"name\": \"recorded\", \"steps\": [ {\"tap\": \"text=Logi…", "gold": true}, {"id": "docs/ROADMAP.md#under-consideration", "heading": "Under consideration", "path": "docs/ROADMAP.md", "excerpt": "- **Locators for when there is no ref** (written down 2026-10-12). A ref from `map` lasts one map, so an agent has one and a `mobium test` file does not: a hand-written test has the flat `kind=value` locators — text, label, testid, role, class, path, narrowed by `,role=` — which match one element or are refused. That is right on a form and leaves nothing durable on a list. Every Ice Cubes post has a \"…\" (CHALLENGES 2…", "gold": false}, {"id": "CHALLENGES#314", "heading": "314. A recording wrote locators that named less than `map` had, and refs", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** writing down a recording as code (ROADMAP, #202) and reading the recorder's `target` for what it would emit. Two things, both measured after: `map` derives every native locator as the whole value and checks it names one element so (`uitree.Derive`), and the inspector rebuilt it without `Exact`. So it recorded `text=Welcome`, which \"Welcome back\" meets too: the race of CHALLENGES 233, written into a test…", "gold": false}], "missed": false, "facts": ["mobium inspect --record <file> writes the recording after every step. ⟦--record⟧", "The file is a .test.json, or a program chosen by its extension: .py, .mjs, .go, .java or .cs, the same file the download gives. ⟦.mjs ; .cs⟧"], "concern": "", "check": "Claude's reading: the --record paragraph sits at the end of inspector.md section 4, not section 5, which is why the gold is #4; the extension table in codegen.go matches the doc's five. New since the pin (#261). Verified in: cmd/mobium/inspect.go:30, cmd/mobium/inspect.go:72, internal/codegen/codegen.go:28, internal/inspect/inspect.go:57."}, {"id": "g043", "kind": "fact", "question": "My inspector recording includes a two-finger tap. What happens when I try to download it as a Go program?", "tags": ["behavior", "test-author", "new since 7b590a4"], "gold": [{"id": "docs/guides/inspector.md#5-download-it-as-code", "heading": "5. Download it as code", "path": "docs/guides/inspector.md", "excerpt": "Next to **Download**, pick the language: the test file, or a program in Python, JavaScript, Go, Java or .NET. Every step is one tool call and every client has every tool, so the program is the same steps through the client's own methods, starting from the app launched fresh. The Table Demo recording above, as Python: ```python # Recorded with mobium inspect. from mobium import start with start() as device: device.ter…"}], "retrieved": [{"id": "CHALLENGES#86", "heading": "86. On Android 16 and later, one press-tap breaks injected touch for the whole device", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** the gesture check on a Pixel 8 Pro (Android 17), where press-tap failed with UiAutomator2's \"Unable to perform W3C actions\" — and then so did everything after it, plain taps included, and `adb shell input tap` too. UiAutomator2 (10.6.6, the newest release) stamps each event with the down time of the finger that produced it (`startTimestamp + event.startDelta`, the chain's own `pointerDown`). Android's c…", "gold": false}, {"id": "CHALLENGES#84", "heading": "84. UiAutomator2 forgets a finger that pauses", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** press-tap, on the Multi-Touch pad, which said \"one finger\" for a gesture the tool reported as two. Android's own pointer-location overlay agreed — `P: 0 / 1`, against `P: 0 / 2` for a two-finger tap, its control. UiAutomator2 (10.6.6, `ActionsExecutor.executeMotionEvents`) builds each W3C step's `MotionEvent` from the fingers that have an event in that step, and counts the fingers already down from the …", "gold": false}, {"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": false}, {"id": "CHALLENGES#67", "heading": "67. WebDriverAgent honors a pause only while the finger is down", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** a double tap that the page refused to call one. `app_tap --double` on Android made a WKWebView's counterpart fire `dblclick` immediately; on iOS the same code produced two clicks and no double, every time. Instrumenting the page gave the answer in one line. The touch stream was `down 43452, up 43519, down 43519, up 43586` — two taps, 67ms each, and **zero milliseconds between them**. The 120ms pause bet…", "gold": false}, {"id": "docs/GESTURES.md#three-ways-a-second-finger-went-wrong", "heading": "Three ways a second finger went wrong", "path": "docs/GESTURES.md", "excerpt": "All three were found by a witness, and none was visible to the tool, which reported every gesture as delivered until the last one, which reported a failure and left the device unable to accept any touch at all. **UiAutomator2 forgets a finger that pauses.** It builds each step's Android `MotionEvent` from the fingers that have an event *in that step*, and counts the fingers already down from the same events. A holdin…", "gold": false}], "missed": true, "facts": ["A step the language table cannot write exactly, such as a two-finger tap or a wait for a count, is refused when you download, naming the step, rather than written as a different step. ⟦refused when you download⟧", "For such a recording, download the test file instead. ⟦download the test file⟧"], "concern": "", "check": "Claude's reading: codegen.unsupported returns an unsupported error \"step N (...) cannot be written as code\" with the remedy \"download the recording as a test file and run it with mobium test\", matching the doc. Note the code also refuses an expect or soft step (codegen.go:52), which the doc does not mention but the inspector records waits, not expects. Verified in: internal/codegen/codegen.go:67, internal/codegen/codegen.go:77, internal/codegen/codegen.go:104."}, {"id": "g044", "kind": "fact", "question": "In a list where every row has its own More button, why does the inspector record my tap on one of them with a `within` locator instead of the path that map showed for that button?", "tags": ["rationale", "test-author", "new since 7b590a4"], "gold": [{"id": "docs/guides/inspector.md#4-record-a-test", "heading": "4. Record a test", "path": "docs/guides/inspector.md", "excerpt": "A test starts from a freshly launched app, so a recording should too: **Start from a fresh app** stops the app in front and launches it again, as `mobium test` does before each test, and starts recording. From there, every action is a step. Recorded on the Login Demo: ```json { \"app\": \"dev.mobium.mobiumapp\", \"description\": \"Recorded with mobium inspect.\", \"tests\": [ { \"name\": \"recorded\", \"steps\": [ {\"tap\": \"text=Logi…"}], "retrieved": [{"id": "docs/guides/inspector.md#4-record-a-test", "heading": "4. Record a test", "path": "docs/guides/inspector.md", "excerpt": "A test starts from a freshly launched app, so a recording should too: **Start from a fresh app** stops the app in front and launches it again, as `mobium test` does before each test, and starts recording. From there, every action is a step. Recorded on the Login Demo: ```json { \"app\": \"dev.mobium.mobiumapp\", \"description\": \"Recorded with mobium inspect.\", \"tests\": [ { \"name\": \"recorded\", \"steps\": [ {\"tap\": \"text=Logi…", "gold": true}, {"id": "CHALLENGES#356", "heading": "356. A recorded look-alike was named by its path, which the next row moves", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** building the recording as code (ROADMAP, \"A recording as code\", item 4) and recording a tap on MobiumApp's Table Demo, where every row has a More and a Delete. `map` names a look-alike by `path=` when nothing else names it alone — Item 2's More was `path=0/0/0/0/0/0/4/0/8` — and the recorder kept whatever `map` gave, so the test held the More's place in the tree. A path is the element's index under each…", "gold": false}, {"id": "CHALLENGES#307", "heading": "307. A scoped locator found the switch in the row beside it", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** the first run on a device of `within`, which scopes a locator to a row — `label=More within text=Card 8`, the More in Card 8's row. The rule keeps, of the target's matches, the one nearest the anchor, climbing from the anchor and stopping at the list, so a row without the target finds nothing rather than its neighbor's. The tests passed on lists built for them, each marked `scrollable=\"true\"`. On the An…", "gold": false}, {"id": "CHALLENGES#236", "heading": "236. A checkmark mapped as a target of its own, under its image's name", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** Pocket Casts' onboarding, on the simulator and the iPhone. Its \"Receive Notifications\" row is a button the app labeled whole, and inside it one button iOS calls not accessible draws the checkmark. `map` listed both, the checkmark as `discover_tick (button)` — the name of the image it draws, since the app gave it none — because the rule that put Ice Cubes' Reply, Boost, Favorite and Share in `map` (214) …", "gold": false}, {"id": "docs/guides/inspector.md#2-find-the-locator-for-anything", "heading": "2. Find the locator for anything", "path": "docs/guides/inspector.md", "excerpt": "![The inspector on MobiumApp's Login Demo: the username field selected, its locator testid=username, its role, ref and bounds, and both buttons outlined in orange for role=button](images/inspector.jpg) Click an element on the screen, or in the list under it. The panel says what `map` says of it — label, role, ref, bounds, checked state — and, at the top, **the locator a test should use**: the one `map` derived as the…", "gold": false}], "missed": false, "facts": ["A path (and a ref) names the element on this screen only: a ref lasts one map, and a path moves whenever the list adds or reuses a row, so a replay would tap another row's button or none. ⟦adds or reuses a row⟧", "The recorder tries the element's name within the nearest element with a locator or within a text on the screen, then its place among the look-alikes with nth=, keeping a candidate only if find shows it names that element alone. ⟦among the look-alikes⟧"], "concern": "", "check": "Claude's reading: inspector.md section 4 explains the scoping and why; CHALLENGES 356 tells the same story as a defect but is not needed for the answer, so it is left out of gold (a retriever may bring it back, which is fine). New since the pin (#261). Verified in: internal/inspect/inspect.go:308, internal/inspect/inspect.go:347, internal/inspect/inspect.go:364."}, {"id": "g045", "kind": "fact", "question": "I want one sign-in test to run with several different bad passwords and show up as separate results. How do I write that in a .test.json file?", "tags": ["how-to", "test-author"], "gold": [{"id": "docs/guides/test-runner.md#9-one-test-over-several-cases-each", "heading": "9. One test over several cases: `each`", "path": "docs/guides/test-runner.md", "excerpt": "A test with `\"each\"` runs once per case, as a test of its own. `${key}` in any string of its steps is that case's value; a string that is nothing but `${key}` keeps the value's type, so a count stays a number. `$${` writes a literal `${`. ```json {\"name\": \"a bad sign-in is refused, and says why: ${why}\", \"each\": [ {\"why\": \"a wrong password\", \"pass\": \"wrongpass1\", \"error\": \"loginError\"}, {\"why\": \"a short password\", \"p…"}], "retrieved": [{"id": "docs/guides/test-runner.md#9-one-test-over-several-cases-each", "heading": "9. One test over several cases: `each`", "path": "docs/guides/test-runner.md", "excerpt": "A test with `\"each\"` runs once per case, as a test of its own. `${key}` in any string of its steps is that case's value; a string that is nothing but `${key}` keeps the value's type, so a count stays a number. `$${` writes a literal `${`. ```json {\"name\": \"a bad sign-in is refused, and says why: ${why}\", \"each\": [ {\"why\": \"a wrong password\", \"pass\": \"wrongpass1\", \"error\": \"loginError\"}, {\"why\": \"a short password\", \"p…", "gold": true}, {"id": "docs/guides/test-runner.md#1-a-config-and-a-test-file", "heading": "1. A config and a test file", "path": "docs/guides/test-runner.md", "excerpt": "``` login-tests/ mobium.config.json tests/ login.test.json ``` `mobium.config.json` says where the tests are and which devices they run on. A **project** is a device to run on: ```json { \"testDir\": \"tests\", \"projects\": [ {\"name\": \"android\", \"device\": \"emulator-5554\"} ] } ``` `tests/login.test.json` is two tests of MobiumApp's Login Demo. Each step is exactly what [`app_batch`](../API.md) takes — a tool and its argume…", "gold": false}, {"id": "docs/guides/test-runner.md#writing-tests", "heading": "Writing tests", "path": "docs/guides/test-runner.md", "excerpt": "- **Find targets with `map` first.** `mobium map` on the screen you are testing gives each element's locator; `testid=` is the one that survives a translation and a redesign. - **Assert with `app_wait_for`**, never a sleep. `--for` in the CLI is `condition` in a step: `visible`, `hidden`, `text` (with `exact`), `value`, `enabled`, `disabled`, `checked`, `unchecked`, `selected`, `unselected`, `focused`, `count`, and `…", "gold": false}, {"id": "docs/guides/test-runner.md#2-run-it", "heading": "2. Run it", "path": "docs/guides/test-runner.md", "excerpt": "From the directory with the config: ``` $ mobium test ok [android] login.test.json › a wrong password is refused (7.7s) ok [android] login.test.json › the demo account signs in (7.8s) 2 passed (15.5s) ``` Exit status 0. Nothing in the test sleeps: every action waits for its own target ([auto-wait](autowait.md)), and every assertion retries until it holds or its timeout — ten seconds unless the step says otherwise.", "gold": false}, {"id": "docs/guides/test-runner.md#3-a-failure-and-what-it-leaves", "heading": "3. A failure, and what it leaves", "path": "docs/guides/test-runner.md", "excerpt": "Change the first test to expect a message the app never shows — `\"text\": \"Wrong password.\"`, with `\"timeout_ms\": 3000` — and run just that test, with all three reports: ``` $ mobium test -g \"wrong password\" --reporter list,junit,html FAIL [android] login.test.json › a wrong password is refused (9.5s) step 4 (app_wait_for): [timeout] step 4 of 4 (app_wait_for) failed: timed out after 3.012s waiting for testid=loginErr…", "gold": false}], "missed": false, "facts": ["Give the test an \"each\" array of cases; ${key} in any string of its steps is that case's value, and each case runs as a test of its own. ⟦\"each\" ; ${key}⟧", "Without a ${key} in the test's name the cases are numbered [1], [2] rather than named after values that may be a password. ⟦[1]⟧", "Each case starts over: the app is stopped and launched and beforeEach runs again. ⟦starts over⟧"], "concern": "", "check": "Claude's reading: expandEach in file.go makes one test per case, names unnamed cases \"<name> [i]\", keeps a lone ${key}'s type, and refuses a missing key, all as test-runner.md section 9 says. Verified in: internal/testrun/file.go:44, internal/testrun/file.go:539, internal/testrun/file.go:560, internal/testrun/file.go:598."}, {"id": "g046", "kind": "multi", "question": "Our mobium.config.json takes the iOS simulator from ${MOBIUM_IOS_DEVICE}. If a CI job runs mobium test without that variable set, what happens and what exit status does the job get?", "tags": ["behavior", "ci-engineer"], "gold": [{"id": "docs/guides/test-runner.md#6-more-than-one-device", "heading": "6. More than one device", "path": "docs/guides/test-runner.md", "excerpt": "Add a project per device. An iOS simulator's id is one Mac's, and a phone's is somebody's, so a project can take its device from the environment, and an unset variable is refused by name before any test runs: ```json { \"testDir\": \"tests\", \"projects\": [ {\"name\": \"android\", \"device\": \"emulator-5554\"}, {\"name\": \"ios\", \"device\": \"${MOBIUM_IOS_DEVICE}\", \"driver\": \"wda\"} ] } ``` ```sh MOBIUM_IOS_DEVICE=<simulator-udid> mob…"}, {"id": "docs/guides/test-runner.md#7-in-ci", "heading": "7. In CI", "path": "docs/guides/test-runner.md", "excerpt": "The command a CI job runs, and what it publishes: ```sh mobium test --reporter list,junit,html # junit: mobium-report/junit.xml — for the CI's test report # html: mobium-report/ — as a build artifact ``` The exit status is 0 when every test passed or was flaky, 1 when any failed, and one of mobium's own codes when the run could not start — 2 for a bad file or an unset device, 3 for no device — so a job can tell \"the …"}], "retrieved": [{"id": "tests/README.md#tests", "heading": "Tests", "path": "tests/README.md", "excerpt": "Mobium's own tests of MobiumApp, run by `mobium test` — and the suite that holds the runner to its word. The format is in the [test runner guide](../docs/guides/test-runner.md). ```sh cd tests mobium test --project android # emulator-5554 MOBIUM_IOS_DEVICE=<simulator-udid> mobium test # and an iOS simulator mobium test --reporter list,junit,html && mobium show-report mobium test --ui --open # pick, run and watch on a…", "gold": false}, {"id": "CHALLENGES#162", "heading": "162. An unset device refused every project, not just its own", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** running `docs/checks/test-runner.sh` in the Android-only mode its own header documents — not a device's doing. A project can take its device from the environment, `\"${MOBIUM_IOS_DEVICE}\"`, and an unset variable is refused by name. It was refused when the config was read, so `mobium test --project android` failed over the iOS project's variable, which that run never needed; every earlier run had happened…", "gold": false}, {"id": "docs/guides/test-runner.md#1-a-config-and-a-test-file", "heading": "1. A config and a test file", "path": "docs/guides/test-runner.md", "excerpt": "``` login-tests/ mobium.config.json tests/ login.test.json ``` `mobium.config.json` says where the tests are and which devices they run on. A **project** is a device to run on: ```json { \"testDir\": \"tests\", \"projects\": [ {\"name\": \"android\", \"device\": \"emulator-5554\"} ] } ``` `tests/login.test.json` is two tests of MobiumApp's Login Demo. Each step is exactly what [`app_batch`](../API.md) takes — a tool and its argume…", "gold": false}, {"id": "docs/checks/README.md#device-checks", "heading": "Device checks", "path": "docs/checks/README.md", "excerpt": "Scripts that drive a real flow end to end through mobium's CLI and assert on the result. Not part of `make ci` — they need a device — but they are the thing [RELEASE-CHECKLIST.md](../RELEASE-CHECKLIST.md) asks you to run, written down so nobody has to invent them again. ```sh ./docs/checks/calculator.sh emulator-5554 ./docs/checks/calculator.sh <serial> ``` Getting a device attached in the first place is [../SETUP.md…", "gold": false}, {"id": "docs/guides/test-runner.md#the-commands", "heading": "The commands", "path": "docs/guides/test-runner.md", "excerpt": "| Command | What it does | | --- | --- | | `mobium test` | runs every `*.test.json` under the config's `testDir`, on every project | | `mobium test tests/login.test.json` | runs one file, or every file under a directory | | `mobium test -g login` | runs the tests whose title — \"file › name\" — matches a regular expression | | `mobium test --last-failed` | runs only the tests that failed last time | | `mobium test --pr…", "gold": false}], "missed": true, "facts": ["An unset variable in a project's device is refused by name before any test runs. ⟦refused by name⟧", "The run exits with mobium's own code 2 (a bad file or an unset device), not 1, which means a test failed, so a job can tell a broken run from a broken app. ⟦2 for a bad file or an unset device⟧"], "concern": "", "check": "Claude's reading: run.go refuses a project with unset variables as invalid_argument naming the variable, and ExitCode maps invalid_argument to 2; section 6 has the refusal and section 7 the exit code, so both are needed. Verified in: internal/testrun/file.go:410, internal/testrun/run.go:242, internal/mobiumerr/mobiumerr.go:239, cmd/mobium/test.go:228."}, {"id": "g047", "kind": "multi", "question": "How do I get mobium test results into my CI system's test report, and how does a test that only passed on a retry show up there?", "tags": ["how-to", "ci-engineer"], "gold": [{"id": "docs/guides/test-runner.md#7-in-ci", "heading": "7. In CI", "path": "docs/guides/test-runner.md", "excerpt": "The command a CI job runs, and what it publishes: ```sh mobium test --reporter list,junit,html # junit: mobium-report/junit.xml — for the CI's test report # html: mobium-report/ — as a build artifact ``` The exit status is 0 when every test passed or was flaky, 1 when any failed, and one of mobium's own codes when the run could not start — 2 for a bad file or an unset device, 3 for no device — so a job can tell \"the …"}, {"id": "docs/guides/test-runner.md#5-retries-and-flaky", "heading": "5. Retries, and flaky", "path": "docs/guides/test-runner.md", "excerpt": "`--retries N` runs a failed test again, from a fresh app, up to N times. A test that fails and then passes is **flaky**: the run passes, and it says so. This is the runner's own control for it, from `tests/controls/` in this repository — it saves a counter, and passes only once the counter reaches 2, which the retry's relaunch makes it do. It counts from cleared app data, so clear it first — a counter left at 2 by an…"}], "retrieved": [{"id": "docs/guides/test-runner.md#quick-start-mobium-test", "heading": "Quick start: `mobium test`", "path": "docs/guides/test-runner.md", "excerpt": "From an empty directory to a test suite that runs on a device, fails with evidence, retries, and leaves a report CI can publish. Every command and every line of output below is what `mobium test` printed on 2026-09-28 — section 8 on 2026-09-29 — against [MobiumApp](https://github.com/mobiumdev/mobium-app) on an Android 15 emulator. Where a path to a report is shortened, it says so. Before this guide: [the quick start…", "gold": false}, {"id": "docs/guides/test-runner.md#7-in-ci", "heading": "7. In CI", "path": "docs/guides/test-runner.md", "excerpt": "The command a CI job runs, and what it publishes: ```sh mobium test --reporter list,junit,html # junit: mobium-report/junit.xml — for the CI's test report # html: mobium-report/ — as a build artifact ``` The exit status is 0 when every test passed or was flaky, 1 when any failed, and one of mobium's own codes when the run could not start — 2 for a bad file or an unset device, 3 for no device — so a job can tell \"the …", "gold": true}, {"id": "docs/guides/inspector.md#4-record-a-test", "heading": "4. Record a test", "path": "docs/guides/inspector.md", "excerpt": "A test starts from a freshly launched app, so a recording should too: **Start from a fresh app** stops the app in front and launches it again, as `mobium test` does before each test, and starts recording. From there, every action is a step. Recorded on the Login Demo: ```json { \"app\": \"dev.mobium.mobiumapp\", \"description\": \"Recorded with mobium inspect.\", \"tests\": [ { \"name\": \"recorded\", \"steps\": [ {\"tap\": \"text=Logi…", "gold": false}, {"id": "docs/guides/grid.md#4-tests-on-a-grid", "heading": "4. Tests on a grid", "path": "docs/guides/grid.md", "excerpt": "`mobium test` goes through a grid the same way. A project that names no device asks for one by `platform`, and with `MOBIUM_GRID` set each project gets a connection of its own, which leases a device before any test runs and releases it when the run ends: ```json { \"testDir\": \"tests\", \"projects\": [ {\"name\": \"android-a\", \"platform\": \"android\"}, {\"name\": \"android-b\", \"platform\": \"android\"} ] } ``` ``` $ MOBIUM_GRID=loca…", "gold": false}, {"id": "docs/guides/test-runner.md#5-retries-and-flaky", "heading": "5. Retries, and flaky", "path": "docs/guides/test-runner.md", "excerpt": "`--retries N` runs a failed test again, from a fresh app, up to N times. A test that fails and then passes is **flaky**: the run passes, and it says so. This is the runner's own control for it, from `tests/controls/` in this repository — it saves a counter, and passes only once the counter reaches 2, which the retry's relaunch makes it do. It counts from cleared app data, so clear it first — a counter left at 2 by an…", "gold": true}], "missed": false, "facts": ["Run mobium test --reporter list,junit,html; the JUnit file is mobium-report/junit.xml, for the CI's test report. ⟦mobium-report/junit.xml⟧", "With --retries, a test that fails then passes is flaky; in JUnit it is a pass with a flaky property. ⟦pass with a flaky property⟧", "The exit status is 0 when every test passed or was flaky. ⟦0 when every test passed or was flaky⟧"], "concern": "", "check": "Claude's reading: WriteJUnit writes junit.xml with a `flaky` property \"passed on attempt N\" and the command fails only when a test failed; section 7 has the command and path, section 5 the flaky-in-JUnit rule. Verified in: internal/testrun/report.go:137, internal/testrun/report.go:169, cmd/mobium/test.go:228."}, {"id": "g048", "kind": "fact", "question": "I only want step-by-step screenshots and a replayable recording for the tests that fail in my nightly mobium test run. What do I pass, and where does the recording end up?", "tags": ["how-to", "test-author"], "gold": [{"id": "docs/guides/test-runner.md#a-trace", "heading": "A trace", "path": "docs/guides/test-runner.md", "excerpt": "`--trace on` keeps a screenshot and the map after every step, and the HTML report shows them as a filmstrip; `--trace retain-on-failure` keeps them only for a test that failed. `trace` in the config sets the default. Each attempt is also kept as a recording in Vibium's record format, at `mobium-report/artifacts/trace/<project>-<file>-<test>-<attempt>/trace.zip`, which the report links and [player.vibium.dev](https://…"}], "retrieved": [{"id": "docs/guides/test-runner.md#a-trace", "heading": "A trace", "path": "docs/guides/test-runner.md", "excerpt": "`--trace on` keeps a screenshot and the map after every step, and the HTML report shows them as a filmstrip; `--trace retain-on-failure` keeps them only for a test that failed. `trace` in the config sets the default. Each attempt is also kept as a recording in Vibium's record format, at `mobium-report/artifacts/trace/<project>-<file>-<test>-<attempt>/trace.zip`, which the report links and [player.vibium.dev](https://…", "gold": true}, {"id": "CHALLENGES#274", "heading": "274. A capture saved into a folder not yet made was lost", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** the audio demo's repository, whose test file saved its capture to `mobium-report/sequence.wav` before anything had made that folder. Mobium's own `tests/audio/` had passed only because its `mobium-report/` was already there. The step failed with \"no such file or directory\" — after the capture had stopped, so the capture went with it, and a test meant to pass reported two failures that were not the app's…", "gold": false}, {"id": "CHALLENGES#212", "heading": "212. A trace went with its session, and a passing test kept none", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** recording a test on a Fire TV over Wi-Fi to play it in Vibium's player. The test passed with `--trace on` and its report had a screenshot for every step and no trace. The link had dropped and come back mid-run, so the next call found the session unhealthy and replaced it — and the running trace was a field of the session, closed with it. The runner's `app_trace stop` then found no trace, and the runner …", "gold": false}, {"id": "docs/guides/test-runner.md#the-commands", "heading": "The commands", "path": "docs/guides/test-runner.md", "excerpt": "| Command | What it does | | --- | --- | | `mobium test` | runs every `*.test.json` under the config's `testDir`, on every project | | `mobium test tests/login.test.json` | runs one file, or every file under a directory | | `mobium test -g login` | runs the tests whose title — \"file › name\" — matches a regular expression | | `mobium test --last-failed` | runs only the tests that failed last time | | `mobium test --pr…", "gold": false}, {"id": "docs/guides/test-runner.md#10-a-page-to-run-tests-from---ui", "heading": "10. A page to run tests from: `--ui`", "path": "docs/guides/test-runner.md", "excerpt": "```sh mobium test --ui --open ``` serves a page on this machine that lists the suite by file, with each test's result on each project. ▶ runs one test, a file, or everything; each step appears with the screen after it as it runs, and **Re-run failed** runs exactly what failed. The files are read again for every run, so a test you just saved is the test that runs. A run from the page is the run `mobium test` makes fro…", "gold": false}], "missed": false, "facts": ["--trace retain-on-failure keeps the screenshot and map after every step only for a test that failed (trace in the config sets the default). ⟦retain-on-failure⟧", "The recording is a zip in Vibium's record format at mobium-report/artifacts/trace/<project>-<file>-<test>-<attempt>/trace.zip, linked from the report. ⟦trace.zip⟧", "player.vibium.dev opens it. ⟦player.vibium.dev⟧"], "concern": "test-runner.md 'A trace' says \"Each attempt is also kept as a recording\", but run.go:477-487 keeps only the attempt reported (a flaky test's first failure, a failed test's last attempt, a pass) and pruneTraces deletes the other attempts' trace directories.", "check": "Claude's reading: the flag, the path and the player match the code. A reviewer should look at the concern: the doc says each attempt is kept, the code keeps one. Verified in: cmd/mobium/test.go:103, internal/testrun/run.go:477, internal/testrun/run.go:509, internal/testrun/run.go:513."}, {"id": "g049", "kind": "fact", "question": "If I attach the trace zip from a sign-in test to a bug report, will the username and password I typed be readable in it?", "tags": ["behavior", "test-author"], "gold": [{"id": "CHALLENGES#327", "heading": "327. A trace held an expect as a bare read, and said typed text was not in it", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** turning a `mobium test` trace back into a test, one step per traced call, and running both on MobiumApp builds with a deliberate bug each (the round-trip probe, mobiumdev/mobium-roundtrip), on the Android 15 emulator. The generated suite caught every bug the original did but lost one (bug, test) cell: \"the app is in front throughout\" is two `expect`s, and a trace kept each as the read it made — `app_sta…"}], "retrieved": [{"id": "CHALLENGES#327", "heading": "327. A trace held an expect as a bare read, and said typed text was not in it", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** turning a `mobium test` trace back into a test, one step per traced call, and running both on MobiumApp builds with a deliberate bug each (the round-trip probe, mobiumdev/mobium-roundtrip), on the Android 15 emulator. The generated suite caught every bug the original did but lost one (bug, test) cell: \"the app is in front throughout\" is two `expect`s, and a trace kept each as the read it made — `app_sta…", "gold": true}, {"id": "docs/guides/test-runner.md#a-trace", "heading": "A trace", "path": "docs/guides/test-runner.md", "excerpt": "`--trace on` keeps a screenshot and the map after every step, and the HTML report shows them as a filmstrip; `--trace retain-on-failure` keeps them only for a test that failed. `trace` in the config sets the default. Each attempt is also kept as a recording in Vibium's record format, at `mobium-report/artifacts/trace/<project>-<file>-<test>-<attempt>/trace.zip`, which the report links and [player.vibium.dev](https://…", "gold": false}, {"id": "docs/ROADMAP.md#under-consideration", "heading": "Under consideration", "path": "docs/ROADMAP.md", "excerpt": "- **Locators for when there is no ref** (written down 2026-10-12). A ref from `map` lasts one map, so an agent has one and a `mobium test` file does not: a hand-written test has the flat `kind=value` locators — text, label, testid, role, class, path, narrowed by `,role=` — which match one element or are refused. That is right on a form and leaves nothing durable on a list. Every Ice Cubes post has a \"…\" (CHALLENGES 2…", "gold": false}, {"id": "CHALLENGES#55", "heading": "55. Text entry failed on a field `map` had just handed out a ref for", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** the first React Native app this project has driven. Every prior Android app was Google's, Wikipedia's, F-Droid's or Aegis's, and every one of them reports a resource-id in the fully qualified form `com.example:id/name`. React Native reports a bare one. A `testID` of `password` arrives as `resource-id=\"password\"`, with no package. `map` handled it correctly — the node, the label, the `role=password` and …", "gold": false}, {"id": "CHALLENGES#43", "heading": "43. `map` printed a password in plaintext", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** the second and third real third-party apps. Typing into Aegis's master-password field and running `map` again gave: ``` @e2 Sup3rSecret! (input) ``` Android marks the node `password=\"true\"` **and** puts the typed value straight into its `text` attribute. Mobium parsed that flag into `Node.Password` and consulted it nowhere — the same shape as [defect 39](#39-a-visibility-field-that-nothing-consulted), f…", "gold": false}], "missed": false, "facts": ["A password is not recorded, only its length. ⟦only its length⟧", "Other typed text, such as the username, is in the trace: in the call's result and the screen after it. ⟦in the call's result⟧"], "concern": "", "check": "Claude's reading: only CHALLENGES 327 (its second part) states the corrected rule in the corpus; the CLI help and app_trace schema say the same, but neither is in the corpus. checks/README's trace.sh row adds that a typed password appears nowhere in the zip but does not cover other text. Verified in: cmd/mobium/trace.go:20, internal/agent/schema.go:882."}, {"id": "g050", "kind": "fact", "question": "My app polls a server in the background forever, and I launched it with --gray-box. What happens when I tap something?", "tags": ["behavior", "test-author"], "gold": [{"id": "docs/guides/graybox.md#what-an-action-does", "heading": "What an action does", "path": "docs/guides/graybox.md", "excerpt": "Before an action finds its target, it waits until the app has nothing in flight. The result says what it waited for (the iPhone): ``` $ mobium tap testid=busyQuiet tapped testid=busyQuiet at (645, 1011) gray box: waited 35 ms for the app to go idle $ mobium tap testid=busyRowB tapped testid=busyRowB at (645, 1218) gray box: waited 1018 ms for the app to go idle (busy: quiet) $ mobium text testid=busyOutcome row B, ge…"}], "retrieved": [{"id": "docs/guides/graybox.md#what-an-action-does", "heading": "What an action does", "path": "docs/guides/graybox.md", "excerpt": "Before an action finds its target, it waits until the app has nothing in flight. The result says what it waited for (the iPhone): ``` $ mobium tap testid=busyQuiet tapped testid=busyQuiet at (645, 1011) gray box: waited 35 ms for the app to go idle $ mobium tap testid=busyRowB tapped testid=busyRowB at (645, 1218) gray box: waited 1018 ms for the app to go idle (busy: quiet) $ mobium text testid=busyOutcome row B, ge…", "gold": true}, {"id": "CHALLENGES#251", "heading": "251. `launch --gray-box` of a running iOS app never reached it", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** walking the gray-box demo's quick start from scratch on the simulator, exactly as written. The quick start launches MobiumApp normally, opens the Busy Demo, and then launches it with `--gray-box` — without stopping it in between, as nobody would. The launch reported that the app had not answered the gray box, the app stayed on the Busy Demo, and the next tap landed stale. A launch argument reaches only …", "gold": false}, {"id": "docs/guides/graybox.md#gray-box-waiting-for-the-app-to-say-it-is-idle", "heading": "Gray box: waiting for the app to say it is idle", "path": "docs/guides/graybox.md", "excerpt": "Auto-wait judges a screen by what it shows: a target is there, has stopped moving, is enabled and is not covered. That cannot see work the screen does not show — a request in flight behind rows that look finished, which a tap then lands on just before they are replaced. Gray box asks the app instead. An app built with Mobium's gray-box library, and launched with `--gray-box`, says in the device log when it starts wor…", "gold": false}, {"id": "docs/guides/graybox.md#hooks-calling-into-the-app", "heading": "Hooks: calling into the app", "path": "docs/guides/graybox.md", "excerpt": "Waiting is the way out of the app. Hooks are the way in: functions the app registers by name, which a test calls to set up state without walking the UI — sign in, seed data, raise a toast. MobiumApp registers three; in outline: ```ts GrayBox.register('raiseToast', message => { showToast(message); return 'shown'; }); GrayBox.register('screen', () => screenRef.current); GrayBox.register('signIn', username => { setLogge…", "gold": false}, {"id": "docs/guides/graybox-tutorial.md#4-turning-the-gray-box-on", "heading": "4. Turning the gray box on", "path": "docs/guides/graybox-tutorial.md", "excerpt": "One key in the test file, beside `app`: ```json { \"app\": \"dev.mobium.mobiumapp\", \"grayBox\": true, \"beforeEach\": [ ``` Each test's launch now turns the library on, and every step waits for the app to say it is idle before finding its target: ``` $ mobium test ok [android · emulator-5554] busy.test.json › a row tapped after a quiet refresh is current (1) (7s) ok [android · emulator-5554] busy.test.json › a row tapped a…", "gold": false}], "missed": false, "facts": ["After 10 seconds the action is refused as a timeout that failed check idle, naming what the app said kept it busy. ⟦after 10 seconds ; failed check idle⟧", "The remedy is to launch the app again without the gray box, to act on the screen as it is. ⟦without --gray-box / without gray_box⟧"], "concern": "", "check": "Claude's reading: grayBoxIdleLimit is 10 s in agent/graybox.go, and the refusal text in the guide's example ends \"launch the app again without gray_box\". Verified in: internal/agent/graybox.go:28."}, {"id": "g051", "kind": "fact", "question": "My mobium test suite runs on a Fire TV over Wi-Fi whose adb link keeps dropping for a few seconds. What does the runner do with a step when the link goes?", "tags": ["behavior", "test-author"], "gold": [{"id": "docs/guides/test-runner.md#a-device-that-drops-off-and-comes-back", "heading": "A device that drops off and comes back", "path": "docs/guides/test-runner.md", "excerpt": "A retry starts the test over. A device whose link drops for a few seconds — a TV or a phone over Wi-Fi — is waited out within the test instead: a step whose call **never reached the device** is made again once it is back, for up to 90 seconds and never past the test's own time. A device reached by `adb connect` is connected again for you. Only that failure is waited out, and an error says which it was (`details.reach…"}], "retrieved": [{"id": "CHALLENGES#210", "heading": "210. A dropped link was reported as a failed install, with advice that could not work", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** running scenarios on a Fire TV over Wi-Fi, whose link drops every few minutes. A `map` called while it was down answered \"installing UiAutomator2 server\", then failed with `install server.apk: … adb: device offline` and advised `--driver uiautomator` — on a TV that had the pinned server installed, version 10.6.6, the whole time. Asking whether the server is installed treated a failed `dumpsys` or `pm li…", "gold": false}, {"id": "docs/SETUP.md#over-wi-fi", "heading": "Over Wi-Fi", "path": "docs/SETUP.md", "excerpt": "Android 11+. The phone and the Mac must be on the same network. 1. **Developer options → Wireless debugging → on.** 2. **\"Pair device with pairing code\"** — it shows an address and a six-digit code. Both expire in about a minute. 3. Find the address without reading it off the screen: ```sh adb mdns services # adb-3C19...-FIOvFv _adb-tls-pairing._tcp 10.0.0.96:33169 # adb-3C19...-FIOvFv _adb-tls-connect._tcp 10.0.0.96…", "gold": false}, {"id": "docs/ROADMAP.md#under-consideration", "heading": "Under consideration", "path": "docs/ROADMAP.md", "excerpt": "- **Locators for when there is no ref** (written down 2026-10-12). A ref from `map` lasts one map, so an agent has one and a `mobium test` file does not: a hand-written test has the flat `kind=value` locators — text, label, testid, role, class, path, narrowed by `,role=` — which match one element or are refused. That is right on a form and leaves nothing durable on a list. Every Ice Cubes post has a \"…\" (CHALLENGES 2…", "gold": false}, {"id": "docs/guides/test-runner.md#a-device-that-drops-off-and-comes-back", "heading": "A device that drops off and comes back", "path": "docs/guides/test-runner.md", "excerpt": "A retry starts the test over. A device whose link drops for a few seconds — a TV or a phone over Wi-Fi — is waited out within the test instead: a step whose call **never reached the device** is made again once it is back, for up to 90 seconds and never past the test's own time. A device reached by `adb connect` is connected again for you. Only that failure is waited out, and an error says which it was (`details.reach…", "gold": true}, {"id": "docs/SHUTDOWN.md#a-tv-or-anything-reached-by-adb-connect", "heading": "A TV, or anything reached by `adb connect`", "path": "docs/SHUTDOWN.md", "excerpt": "A Fire TV is reached over Wi-Fi with `adb connect <tv>:5555`, after ADB debugging is turned on in its Developer Options. It is somebody's living-room TV, so the device checks above run on it as on a phone, and four more run on every device: - **A screen mirror's server.** scrcpy was how the TV was watched while it was measured, and its server streams the screen off the device for as long as it runs. On the device it …", "gold": false}], "missed": false, "facts": ["A step whose call never reached the device is made again once the device is back, for up to 90 seconds and never past the test's own time; a device reached by adb connect is connected again. ⟦90 seconds ; connected again⟧", "A failure from a call that may have reached the device fails the step as before, because making it again could press twice. ⟦press twice⟧"], "concern": "", "check": "Claude's reading: callReaching retries only device.Unreached errors, every 2 s, until linkWait (90 s) or the test's deadline, as the section says. Verified in: internal/testrun/run.go:800, internal/testrun/run.go:807."}, {"id": "g052", "kind": "fact", "question": "I changed some Go code in Mobium and ran make build, but the CLI still behaves exactly as before my change. What am I missing?", "tags": ["troubleshooting", "contributor"], "gold": [{"id": "docs/DEVELOPMENT.md#3-run-what-ci-runs", "heading": "3. Run what CI runs", "path": "docs/DEVELOPMENT.md", "excerpt": "```sh make ci ``` It is exactly what the CI workflow runs, so a green local run means a green build. Among its other lines it prints `gofmt clean`, `clients parse`, a line per JavaScript and Python client check, a `checks, 0 failed` total for each of the Java and .NET suites, `license copies match` and `docs: spelling, anchors and quick-start pages clean`; the counts in them grow with the API, so none is quoted here.…"}], "retrieved": [{"id": "CLAUDE.md#rules", "heading": "Rules", "path": "CLAUDE.md", "excerpt": "- Run `make ci` before committing. After adding a tool, a flag or a schema property, run `make api flags` and add it everywhere — CLI, MCP schema, all five clients (CONTRIBUTING.md, \"Adding a tool, a flag or an error\") - Every error has a code: `mobiumerr.New(mobiumerr.<Code>, ...)`, never a bare `fmt.Errorf` - The CLI implements no behavior; it calls a tool. Behavior lives in `internal/agent` - After rebuilding, `mo…", "gold": false}, {"id": "docs/API.md#the-api-surface", "heading": "The API surface", "path": "docs/API.md", "excerpt": "**Generated — do not edit.** Run `make api` to rebuild this and [api/surface.json](api/surface.json) from the source. Mobium's architecture rests on one claim: every front door reaches the same tool layer, so a CLI command and an MCP tool cannot answer differently. This is that claim, enumerated, and a drift check keeps it true — `internal/apisurface` fails the build if any tool stops being reachable from any surface…", "gold": false}, {"id": "CONTRIBUTING.md#adding-a-tool-a-flag-or-an-error", "heading": "Adding a tool, a flag or an error", "path": "CONTRIBUTING.md", "excerpt": "- **A tool** goes everywhere at once: the CLI, the MCP schema and all five clients. `internal/apisurface` fails the build otherwise; a deliberate gap is declared there with a reason. Run `make api` to regenerate [docs/API.md](docs/API.md). - **A flag or schema property** is the same rule one level down: every argument a tool declares must be settable from the CLI, and every key a command sends must be one the tool de…", "gold": false}, {"id": "CONTRIBUTING.md#building-and-testing", "heading": "Building and testing", "path": "CONTRIBUTING.md", "excerpt": "[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) is the step-by-step version: the toolchains, a fresh clone to a passing `make ci`, driving a device, working on a client, and sending a pull request. In short: ```sh make build # -> bin/mobium make ci # what CI runs: gofmt, vet, lint, tests, client checks, # cross-compilation, and the generated-doc and spelling checks ``` Run `make ci` before sending a change; a green local …", "gold": false}, {"id": "docs/WINDOWS.md#project-rules-that-apply", "heading": "Project rules that apply", "path": "docs/WINDOWS.md", "excerpt": "From [CONTRIBUTING.md](../CONTRIBUTING.md): - **Verify by outcome, never exit code.** Especially here: a named pipe that accepts a connection and never answers looks identical to success. - Run `make ci` before committing, and `mobium daemon stop` after rebuilding, or you will debug a binary you are not running. - Never name a Go file `*_windows.go` unless you intend the build constraint — though here, you do.", "gold": false}], "missed": true, "facts": ["A daemon already running keeps serving the old binary; run bin/mobium daemon stop after rebuilding. ⟦bin/mobium daemon stop ; keeps serving the old binary⟧"], "concern": "", "check": "Claude's reading: the CLI sends every call to the running daemon and starts a new one only on a connection error, so a stale daemon is never replaced by itself. CONTRIBUTING.md#building-and-testing says the same; either section alone answers, and DEVELOPMENT is the step-by-step one. Verified in: cmd/mobium/daemon_client.go:50, cmd/mobium/daemon_client.go:56, cmd/mobium/daemon_client.go:66."}, {"id": "g053", "kind": "fact", "question": "I ran make api after adding a tool, but make ci still fails saying docs/API.md is not current. Why?", "tags": ["troubleshooting", "contributor"], "gold": [{"id": "docs/DEVELOPMENT.md#6-regenerate-what-is-generated", "heading": "6. Regenerate what is generated", "path": "docs/DEVELOPMENT.md", "excerpt": "Some documents are built from the code, and `make ci` fails when one is stale: | When you change | Run | It writes | | --- | --- | --- | | a tool, or which surfaces reach it | `make api` | [API.md](API.md) | | a tool's arguments or a command's flags | `make flags` | [FLAGS.md](FLAGS.md) | | a quick-start example or its captured output | `make quickstart` | the [quick start](quickstart/README.md) pages | | the root `L…"}], "retrieved": [{"id": "CLAUDE.md#rules", "heading": "Rules", "path": "CLAUDE.md", "excerpt": "- Run `make ci` before committing. After adding a tool, a flag or a schema property, run `make api flags` and add it everywhere — CLI, MCP schema, all five clients (CONTRIBUTING.md, \"Adding a tool, a flag or an error\") - Every error has a code: `mobiumerr.New(mobiumerr.<Code>, ...)`, never a bare `fmt.Errorf` - The CLI implements no behavior; it calls a tool. Behavior lives in `internal/agent` - After rebuilding, `mo…", "gold": false}, {"id": "CONTRIBUTING.md#adding-a-tool-a-flag-or-an-error", "heading": "Adding a tool, a flag or an error", "path": "CONTRIBUTING.md", "excerpt": "- **A tool** goes everywhere at once: the CLI, the MCP schema and all five clients. `internal/apisurface` fails the build otherwise; a deliberate gap is declared there with a reason. Run `make api` to regenerate [docs/API.md](docs/API.md). - **A flag or schema property** is the same rule one level down: every argument a tool declares must be settable from the CLI, and every key a command sends must be one the tool de…", "gold": false}, {"id": "docs/API.md#the-api-surface", "heading": "The API surface", "path": "docs/API.md", "excerpt": "**Generated — do not edit.** Run `make api` to rebuild this and [api/surface.json](api/surface.json) from the source. Mobium's architecture rests on one claim: every front door reaches the same tool layer, so a CLI command and an MCP tool cannot answer differently. This is that claim, enumerated, and a drift check keeps it true — `internal/apisurface` fails the build if any tool stops being reachable from any surface…", "gold": false}, {"id": "docs/DEVELOPMENT.md#6-regenerate-what-is-generated", "heading": "6. Regenerate what is generated", "path": "docs/DEVELOPMENT.md", "excerpt": "Some documents are built from the code, and `make ci` fails when one is stale: | When you change | Run | It writes | | --- | --- | --- | | a tool, or which surfaces reach it | `make api` | [API.md](API.md) | | a tool's arguments or a command's flags | `make flags` | [FLAGS.md](FLAGS.md) | | a quick-start example or its captured output | `make quickstart` | the [quick start](quickstart/README.md) pages | | the root `L…", "gold": true}, {"id": "docs/DEVELOPMENT.md#3-run-what-ci-runs", "heading": "3. Run what CI runs", "path": "docs/DEVELOPMENT.md", "excerpt": "```sh make ci ``` It is exactly what the CI workflow runs, so a green local run means a green build. Among its other lines it prints `gofmt clean`, `clients parse`, a line per JavaScript and Python client check, a `checks, 0 failed` total for each of the Java and .NET suites, `license copies match` and `docs: spelling, anchors and quick-start pages clean`; the counts in them grow with the API, so none is quoted here.…", "gold": false}], "missed": false, "facts": ["The generated-doc checks compare against the git index, so git add the regenerated files before running make ci. ⟦git index ; git add⟧"], "concern": "", "check": "Claude's reading: api-check and flags-check run `git diff --quiet -- docs/API.md docs/api/surface.json` (and FLAGS), which compares the working tree with the index, so unstaged regenerated files fail; the docs check uses git ls-files too. Verified in: Makefile:159, Makefile:191, Makefile:240."}, {"id": "g054", "kind": "fact", "question": "I started a second Mobium device check script on an emulator where another check was already running, and it stopped at once with a FAIL saying the device is in use. How do I run several checks at once?", "tags": ["troubleshooting", "contributor"], "gold": [{"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…"}], "retrieved": [{"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": true}, {"id": "CHALLENGES#276", "heading": "276. A check passed for a device it never touched", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** sweeping `audio.sh` on both emulators at once. Its last step runs `mobium test --project android`, and `tests/mobium.config.json` names that project's device `emulator-5554`. So `audio.sh emulator-5556` ran its test step on 5554: Android 17's pass never tested that step on Android 17, and the two checks' test steps started UiAutomator2 servers on 5554 within a third of a second — each start stops the se…", "gold": false}, {"id": "CHALLENGES#199", "heading": "199. An interrupted test run left its daemons running", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** `docs/checks/test-ui.sh`, which failed on its first draft partway through a run on an emulator and a simulator; its cleanup killed `mobium test --ui`, and two daemons, `mobium-<run>-1` and `-2`, were still running afterwards with their sockets left. A run gives each project a `mobium pipe` and a daemon of its own and stops them when it ends — in a deferred cleanup, which a killed process never reaches. …", "gold": false}, {"id": "docs/DEVELOPMENT.md#4-drive-a-device", "heading": "4. Drive a device", "path": "docs/DEVELOPMENT.md", "excerpt": "The Go suite is hermetic — fake servers and captured fixtures, no device. Behavior on a device is checked by the scripts in [checks/](checks/), each of which drives a real emulator, simulator or phone and asserts on what happened rather than on an exit code. Start one device — `mobium boot mobium-test` for an emulator, `mobium boot \"iPhone 17 Pro\"` for a simulator; [SETUP.md](SETUP.md) has every kind, and the traps —…", "gold": false}], "missed": false, "facts": ["Checks run one per device: check_lock takes the device, a second check on it is refused naming the first, and a lock whose holder has gone is taken over. ⟦check_lock⟧", "Checks on different devices can run side by side, each with a daemon of its own (MOBIUM_SESSION) stopped when it ends. ⟦of its own (MOBIUM_SESSION)⟧"], "concern": "", "check": "Claude's reading: lib.sh's check_lock prints \"is in use by another check ... run one check per device at a time\" and exits 2 when the holder's pid is alive, and takes over a dead holder's lock. The gold section is very long (the whole checks table); the answer is in its first part. Verified in: docs/checks/lib.sh:33, docs/checks/lib.sh:125, docs/checks/lib.sh:136."}, {"id": "g055", "kind": "multi", "question": "Can Mobium's gray box wait for my app's background work on a real iPhone, and can I use it with an app installed from the App Store?", "tags": ["support", "new-user"], "gold": [{"id": "docs/guides/graybox.md#gray-box-waiting-for-the-app-to-say-it-is-idle", "heading": "Gray box: waiting for the app to say it is idle", "path": "docs/guides/graybox.md", "excerpt": "Auto-wait judges a screen by what it shows: a target is there, has stopped moving, is enabled and is not covered. That cannot see work the screen does not show — a request in flight behind rows that look finished, which a tap then lands on just before they are replaced. Gray box asks the app instead. An app built with Mobium's gray-box library, and launched with `--gray-box`, says in the device log when it starts wor…"}, {"id": "docs/guides/graybox.md#what-it-does-not-do", "heading": "What it does not do", "path": "docs/guides/graybox.md", "excerpt": "- **Detect work.** The app says when it is busy. Work it does not declare is not waited for, and an app that says it is idle too early is believed. - **An app without the library** — anything from an app store — which stays driven the ordinary way. - **`--hit-test` together with it**, for now: launch with one of them. - **Switching apps.** The gray box belongs to the app last launched with it. An ordinary launch of a…"}], "retrieved": [{"id": "docs/guides/graybox.md#gray-box-waiting-for-the-app-to-say-it-is-idle", "heading": "Gray box: waiting for the app to say it is idle", "path": "docs/guides/graybox.md", "excerpt": "Auto-wait judges a screen by what it shows: a target is there, has stopped moving, is enabled and is not covered. That cannot see work the screen does not show — a request in flight behind rows that look finished, which a tap then lands on just before they are replaced. Gray box asks the app instead. An app built with Mobium's gray-box library, and launched with `--gray-box`, says in the device log when it starts wor…", "gold": true}, {"id": "docs/guides/graybox.md#hooks-calling-into-the-app", "heading": "Hooks: calling into the app", "path": "docs/guides/graybox.md", "excerpt": "Waiting is the way out of the app. Hooks are the way in: functions the app registers by name, which a test calls to set up state without walking the UI — sign in, seed data, raise a toast. MobiumApp registers three; in outline: ```ts GrayBox.register('raiseToast', message => { showToast(message); return 'shown'; }); GrayBox.register('screen', () => screenRef.current); GrayBox.register('signIn', username => { setLogge…", "gold": false}, {"id": "docs/guides/graybox-tutorial.md#5-your-own-app", "heading": "5. Your own app", "path": "docs/guides/graybox-tutorial.md", "excerpt": "The library is small, and what it writes is the whole contract. In a React Native app, copy MobiumApp's `modules/graybox` (Swift and Kotlin, about 160 lines between them) and call `busy` and `idle` around the work a test should wait for. In a native app, write the same lines yourself, only when launched with the gray box on — on iOS the argument `-MobiumGrayBox YES`, on Android the intent extra `MobiumGrayBox=true`: …", "gold": false}, {"id": "docs/guides/graybox.md#turning-it-on", "heading": "Turning it on", "path": "docs/guides/graybox.md", "excerpt": "``` $ mobium launch --gray-box dev.mobium.mobiumapp launched dev.mobium.mobiumapp, with the gray box: every action waits for the app to say it is idle ``` On iOS, `--gray-box` launches the app with the argument `-MobiumGrayBox YES`, which iOS keeps for that launch only. On Android it starts the app afresh — stopped first, so its activity reads what it was started with — with the intent extra `MobiumGrayBox=true`, whi…", "gold": false}, {"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": false}], "missed": false, "facts": ["Gray box works on iOS and Android, on simulators, emulators and phones, for an app built with Mobium's gray-box library and launched with --gray-box. ⟦simulators, emulators and phones⟧", "An app without the library, such as anything from an app store, is not waited for and stays driven the ordinary way. ⟦anything from an app store⟧"], "concern": "", "check": "Claude's reading: the intro states where it runs and that the app must link the library; 'What it does not do' states the app-store case. In code an app that never answers is launched normally with \"actions are not waited for\". Verified in: internal/agent/graybox.go:128, internal/device/graybox.go:74, internal/device/grayboxstream.go:77."}, {"id": "g056", "kind": "fact", "question": "Why doesn't Mobium's own CI run its tests on a hosted Android emulator or iOS simulator?", "tags": ["rationale", "contributor"], "gold": [{"id": "docs/RELEASE-CHECKLIST.md#why-there-is-no-device-job-in-ci", "heading": "Why there is no device job in CI", "path": "docs/RELEASE-CHECKLIST.md", "excerpt": "A hosted Android emulator job is possible and a hosted iOS simulator job is easy. Neither is here, for one reason: **a device test that runs unattended tells you it failed, not what the screen looked like.** Every defect in [CHALLENGES.md](CHALLENGES.md) was diagnosed by reading a hierarchy or comparing a computed point against a screenshot, which is a human activity. That is a judgment, not a law. Revisit it when th…"}], "retrieved": [{"id": "docs/RELEASE-CHECKLIST.md#why-there-is-no-device-job-in-ci", "heading": "Why there is no device job in CI", "path": "docs/RELEASE-CHECKLIST.md", "excerpt": "A hosted Android emulator job is possible and a hosted iOS simulator job is easy. Neither is here, for one reason: **a device test that runs unattended tells you it failed, not what the screen looked like.** Every defect in [CHALLENGES.md](CHALLENGES.md) was diagnosed by reading a hierarchy or comparing a computed point against a screenshot, which is a human activity. That is a judgment, not a law. Revisit it when th…", "gold": true}, {"id": "tests/README.md#tests", "heading": "Tests", "path": "tests/README.md", "excerpt": "Mobium's own tests of MobiumApp, run by `mobium test` — and the suite that holds the runner to its word. The format is in the [test runner guide](../docs/guides/test-runner.md). ```sh cd tests mobium test --project android # emulator-5554 MOBIUM_IOS_DEVICE=<simulator-udid> mobium test # and an iOS simulator mobium test --reporter list,junit,html && mobium show-report mobium test --ui --open # pick, run and watch on a…", "gold": false}, {"id": "docs/ROADMAP.md#under-consideration", "heading": "Under consideration", "path": "docs/ROADMAP.md", "excerpt": "- **Locators for when there is no ref** (written down 2026-10-12). A ref from `map` lasts one map, so an agent has one and a `mobium test` file does not: a hand-written test has the flat `kind=value` locators — text, label, testid, role, class, path, narrowed by `,role=` — which match one element or are refused. That is right on a form and leaves nothing durable on a list. Every Ice Cubes post has a \"…\" (CHALLENGES 2…", "gold": false}, {"id": "docs/FORMFLUX.md#running-it", "heading": "Running it", "path": "docs/FORMFLUX.md", "excerpt": "The parsing is covered by fixtures captured from the device. The behavior is not, and cannot be — so there is a device-backed test, opt-in like the network one: ```sh MOBIUM_DEVICE_TESTS=1 MOBIUM_DEVICE=emulator-5554 \\ go test ./internal/formflux/ -run Device -v ``` `TestDeviceCatchesThePlantedTargets` needs MobiumApp installed, and skips without it. The iOS test has its own switch, because it may create and delete s…", "gold": false}, {"id": "docs/guides/network.md#why-not-the-emulators-own-throttling", "heading": "Why not the emulator's own throttling", "path": "docs/guides/network.md", "excerpt": "The Android emulator's console has `network speed` and `network delay`, and they look made for this. They accept a setting and read it back — and change nothing: on emulator 37.1.11, 2MB at a 1000 kbit/s limit still arrived in 1.1 seconds where 16 were due, and a 500ms delay left a ping at 1ms. So Mobium does not use them; it shapes the traffic itself, and every figure above was measured from the traffic, not the set…", "gold": false}], "missed": false, "facts": ["A device test that runs unattended tells you it failed, not what the screen looked like; every defect was diagnosed by a person reading a hierarchy or a screenshot. ⟦not what the screen looked like⟧", "Here the harness is the thing under test and its defects are mostly misreadings of a device that a green unattended run would pass, so what an assertion can decide is in make ci and what needs a person is in the release checklist. ⟦harness is the thing under test⟧"], "concern": "", "check": "Claude's reading: a rationale section with nothing to check in code beyond the ci target having no device job (Makefile:240). The section quotes the author's own article; that is a public link, not private data. Verified in: Makefile:240."}, {"id": "g057", "kind": "fact", "question": "Walking through the login screen at the start of every test is slow. How can a test put my app straight into a signed-in state instead?", "tags": ["how-to", "test-author"], "gold": [{"id": "docs/guides/graybox.md#hooks-calling-into-the-app", "heading": "Hooks: calling into the app", "path": "docs/guides/graybox.md", "excerpt": "Waiting is the way out of the app. Hooks are the way in: functions the app registers by name, which a test calls to set up state without walking the UI — sign in, seed data, raise a toast. MobiumApp registers three; in outline: ```ts GrayBox.register('raiseToast', message => { showToast(message); return 'shown'; }); GrayBox.register('screen', () => screenRef.current); GrayBox.register('signIn', username => { setLogge…"}], "retrieved": [{"id": "docs/guides/inspector.md#4-record-a-test", "heading": "4. Record a test", "path": "docs/guides/inspector.md", "excerpt": "A test starts from a freshly launched app, so a recording should too: **Start from a fresh app** stops the app in front and launches it again, as `mobium test` does before each test, and starts recording. From there, every action is a step. Recorded on the Login Demo: ```json { \"app\": \"dev.mobium.mobiumapp\", \"description\": \"Recorded with mobium inspect.\", \"tests\": [ { \"name\": \"recorded\", \"steps\": [ {\"tap\": \"text=Logi…", "gold": false}, {"id": "docs/guides/graybox.md#hooks-calling-into-the-app", "heading": "Hooks: calling into the app", "path": "docs/guides/graybox.md", "excerpt": "Waiting is the way out of the app. Hooks are the way in: functions the app registers by name, which a test calls to set up state without walking the UI — sign in, seed data, raise a toast. MobiumApp registers three; in outline: ```ts GrayBox.register('raiseToast', message => { showToast(message); return 'shown'; }); GrayBox.register('screen', () => screenRef.current); GrayBox.register('signIn', username => { setLogge…", "gold": true}, {"id": "docs/guides/network.md#4-in-a-test", "heading": "4. In a test", "path": "docs/guides/network.md", "excerpt": "`app_network` is a step like any other in a [`mobium test`](test-runner.md) file, and its answer can be expected on: ```json { \"app\": \"dev.mobium.mobiumapp\", \"beforeEach\": [ {\"name\": \"app_network\", \"arguments\": {\"reset\": true}, \"description\": \"every test starts online and unshaped, whatever the last one left\"} ], \"tests\": [ { \"name\": \"the device goes offline, and comes back\", \"steps\": [ {\"name\": \"app_network\", \"argum…", "gold": false}, {"id": "docs/guides/test-runner.md#1-a-config-and-a-test-file", "heading": "1. A config and a test file", "path": "docs/guides/test-runner.md", "excerpt": "``` login-tests/ mobium.config.json tests/ login.test.json ``` `mobium.config.json` says where the tests are and which devices they run on. A **project** is a device to run on: ```json { \"testDir\": \"tests\", \"projects\": [ {\"name\": \"android\", \"device\": \"emulator-5554\"} ] } ``` `tests/login.test.json` is two tests of MobiumApp's Login Demo. Each step is exactly what [`app_batch`](../API.md) takes — a tool and its argume…", "gold": false}, {"id": "docs/guides/test-runner.md#stepping-through-a-test", "heading": "Stepping through a test", "path": "docs/guides/test-runner.md", "excerpt": "`--debug` stops before every step, prints it and the screen, and waits: Enter runs the step, `m` maps again, `c` runs the rest of the test, `q` quits. One project at a time, and the test's timeout is off while you read. ``` $ mobium test mobiumapp/form.test.json -g checkbox --project android --debug [android] form.test.json › a checkbox reaches the state asked for — beforeEach {\"arguments\":{\"target\":\"label=Form Demo\"…", "gold": false}], "missed": false, "facts": ["The app registers hooks by name with the gray-box library (GrayBox.register), and a test calls one with mobium hook <name> [args], or app_hook from MCP, getting back what it returned. ⟦GrayBox.register ; mobium hook / app_hook⟧", "Hooks answer only when the app was launched with --gray-box; otherwise the call is device_not_ready. ⟦without --gray-box is device_not_ready⟧"], "concern": "", "check": "Claude's reading: hook.go's help and agent/graybox.go (15 s default limit, device_not_ready when not launched with the gray box) match the guide's Hooks section. Verified in: cmd/mobium/hook.go:8, internal/agent/graybox.go:150, internal/agent/graybox.go:192."}, {"id": "g058", "kind": "multi", "question": "My app is native Swift and Kotlin, not React Native. What does it have to do so that mobium test waits for its background loading before each step?", "tags": ["how-to", "test-author"], "gold": [{"id": "docs/guides/graybox-tutorial.md#5-your-own-app", "heading": "5. Your own app", "path": "docs/guides/graybox-tutorial.md", "excerpt": "The library is small, and what it writes is the whole contract. In a React Native app, copy MobiumApp's `modules/graybox` (Swift and Kotlin, about 160 lines between them) and call `busy` and `idle` around the work a test should wait for. In a native app, write the same lines yourself, only when launched with the gray box on — on iOS the argument `-MobiumGrayBox YES`, on Android the intent extra `MobiumGrayBox=true`: …"}, {"id": "docs/guides/graybox-tutorial.md#4-turning-the-gray-box-on", "heading": "4. Turning the gray box on", "path": "docs/guides/graybox-tutorial.md", "excerpt": "One key in the test file, beside `app`: ```json { \"app\": \"dev.mobium.mobiumapp\", \"grayBox\": true, \"beforeEach\": [ ``` Each test's launch now turns the library on, and every step waits for the app to say it is idle before finding its target: ``` $ mobium test ok [android · emulator-5554] busy.test.json › a row tapped after a quiet refresh is current (1) (7s) ok [android · emulator-5554] busy.test.json › a row tapped a…"}], "retrieved": [{"id": "docs/guides/graybox-tutorial.md#5-your-own-app", "heading": "5. Your own app", "path": "docs/guides/graybox-tutorial.md", "excerpt": "The library is small, and what it writes is the whole contract. In a React Native app, copy MobiumApp's `modules/graybox` (Swift and Kotlin, about 160 lines between them) and call `busy` and `idle` around the work a test should wait for. In a native app, write the same lines yourself, only when launched with the gray box on — on iOS the argument `-MobiumGrayBox YES`, on Android the intent extra `MobiumGrayBox=true`: …", "gold": true}, {"id": "skills/mobile-check/SKILL.md#mobium-mobile-automation-cli-reference", "heading": "Mobium Mobile Automation — CLI Reference", "path": "skills/mobile-check/SKILL.md", "excerpt": "The `mobium` CLI automates **mobile apps** on Android emulators and phones, and iOS simulators and iPhones. A background daemon keeps the device session alive between commands, so each command is fast after the first. ``` mobium launch com.example.shop && mobium map && mobium tap @e5 && mobium map ``` What the app is built with decides how to reach it: | App type | How | | --- | --- | | Native (Android SDK, Jetpack C…", "gold": false}, {"id": "skills/mobile-check/SKILL.md#hybrid-apps-webviews", "heading": "Hybrid apps (WebViews)", "path": "skills/mobile-check/SKILL.md", "excerpt": "Web content inside an app is a separate context: ```sh mobium contexts # NATIVE_APP, WEBVIEW_com.example mobium context WEBVIEW_com.example # map and tap now work on the page mobium context NATIVE_APP # back to the native shell ``` This works on **both platforms**. Android WebViews must be debuggable (`setWebContentsDebuggingEnabled(true)`) and iOS WKWebViews must be inspectable (`webView.isInspectable = true` on iOS…", "gold": false}, {"id": "skills/mobile-check/SKILL.md#getting-to-the-screen-you-want", "heading": "Getting to the screen you want", "path": "skills/mobile-check/SKILL.md", "excerpt": "- `mobium current` — which app is in the foreground - `mobium state <package|bundle-id>` — any app: not installed, not running, background or foreground - `mobium shake` — shake an emulator or simulator (shake-to-undo, a debug menu); a real phone refuses. Check the screen after: whether the app reacts is its own detector's business - `mobium biometric` — whether a face or finger is enrolled; `enroll` / `unenroll` set…", "gold": false}, {"id": "docs/BACK.md#with-predictive-back-turned-on", "heading": "With predictive back turned on", "path": "docs/BACK.md", "excerpt": "Apps targeting Android 16 and later are moving to predictive back, so on 2026-10-02 MobiumApp was built once with Expo's `predictiveBackGestureEnabled: true` — `android:enableOnBackInvokedCallback=\"true\"` in the manifest, everything else the same — and the probe and `back.sh` run against it: | Device | key, right edge, left edge from a demo | Back from home | | --- | --- | --- | | Pixel 8 Pro, Android 17 | demo → hom…", "gold": false}], "missed": false, "facts": ["Write MOBIUM-GRAYBOX lines (on, busy=<n> tag=<what> at each change of work in flight, lift) to the device log: on iOS os_log subsystem dev.mobium.graybox, on Android logcat tag MobiumGrayBox. ⟦dev.mobium.graybox ; MobiumGrayBox⟧", "Write them only when launched with the gray box on: the argument -MobiumGrayBox YES on iOS, the intent extra MobiumGrayBox=true on Android. ⟦-MobiumGrayBox YES⟧", "In the test file set \"grayBox\": true beside \"app\", so each test's launch turns it on. ⟦\"grayBox\": true⟧"], "concern": "", "check": "Claude's reading: the log prefix, iOS argument and subsystem, Android extra and tag all match device/graybox.go and grayboxstream.go; the test-file key is in tutorial section 4, the native lines in section 5. Verified in: internal/device/graybox.go:69, internal/device/graybox.go:74, internal/device/graybox.go:77, internal/device/grayboxstream.go:77, internal/device/grayboxstream.go:80, internal/testrun/file.go:32."}, {"id": "g059", "kind": "unanswerable", "question": "How do I split my mobium test suite across four CI machines so that each one runs a quarter of the test files?", "tags": ["ci-engineer"], "gold": [], "retrieved": [{"id": "docs/guides/test-runner.md#10-a-page-to-run-tests-from---ui", "heading": "10. A page to run tests from: `--ui`", "path": "docs/guides/test-runner.md", "excerpt": "```sh mobium test --ui --open ``` serves a page on this machine that lists the suite by file, with each test's result on each project. ▶ runs one test, a file, or everything; each step appears with the screen after it as it runs, and **Re-run failed** runs exactly what failed. The files are read again for every run, so a test you just saved is the test that runs. A run from the page is the run `mobium test` makes fro…", "gold": false}, {"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": false}, {"id": "docs/guides/test-runner.md#6-more-than-one-device", "heading": "6. More than one device", "path": "docs/guides/test-runner.md", "excerpt": "Add a project per device. An iOS simulator's id is one Mac's, and a phone's is somebody's, so a project can take its device from the environment, and an unset variable is refused by name before any test runs: ```json { \"testDir\": \"tests\", \"projects\": [ {\"name\": \"android\", \"device\": \"emulator-5554\"}, {\"name\": \"ios\", \"device\": \"${MOBIUM_IOS_DEVICE}\", \"driver\": \"wda\"} ] } ``` ```sh MOBIUM_IOS_DEVICE=<simulator-udid> mob…", "gold": false}, {"id": "tests/README.md#tests", "heading": "Tests", "path": "tests/README.md", "excerpt": "Mobium's own tests of MobiumApp, run by `mobium test` — and the suite that holds the runner to its word. The format is in the [test runner guide](../docs/guides/test-runner.md). ```sh cd tests mobium test --project android # emulator-5554 MOBIUM_IOS_DEVICE=<simulator-udid> mobium test # and an iOS simulator mobium test --reporter list,junit,html && mobium show-report mobium test --ui --open # pick, run and watch on a…", "gold": false}], "missed": false, "facts": [], "concern": "", "check": "Claude's reading: no shard option exists; `grep -ri shard` finds nothing in the code or the docs, and the test command's flags (test.go:234-250) parallelize only across devices on one machine (--workers, one worker per device) or lease grid devices. A retriever will return the multi-device and CI sections. Nearest sections: docs/guides/test-runner.md#6-more-than-one-device, docs/guides/test-runner.md#7-in-ci, docs/guides/test-runner.md#the-commands. Verified in: cmd/mobium/test.go:234."}, {"id": "g060", "kind": "unanswerable", "question": "If I don't pass --timeout to mobium test and the config sets no timeout, how long does each test get before it is stopped?", "tags": ["test-author"], "gold": [], "retrieved": [{"id": "docs/guides/test-runner.md#2-run-it", "heading": "2. Run it", "path": "docs/guides/test-runner.md", "excerpt": "From the directory with the config: ``` $ mobium test ok [android] login.test.json › a wrong password is refused (7.7s) ok [android] login.test.json › the demo account signs in (7.8s) 2 passed (15.5s) ``` Exit status 0. Nothing in the test sleeps: every action waits for its own target ([auto-wait](autowait.md)), and every assertion retries until it holds or its timeout — ten seconds unless the step says otherwise.", "gold": false}, {"id": "CHALLENGES#157", "heading": "157. An iOS background of a minute or more timed out", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** `docs/checks/otp.sh`, sending MobiumApp away for 62 seconds to let its code expire, on the iPhone 17 Pro simulator. `app_background` takes up to 180 seconds, and on iOS it failed at any length past about one minute with \"context deadline exceeded\". WebDriverAgent's `deactivateApp` answers only once the app is back, and every request to it has a sixty-second client timeout. Android backgrounds by pressin…", "gold": false}, {"id": "docs/guides/graybox-tutorial.md#2-it-fails", "heading": "2. It fails", "path": "docs/guides/graybox-tutorial.md", "excerpt": "``` $ mobium test FAIL [android · emulator-5554] busy.test.json › a row tapped after a quiet refresh is current (1) (6.9s) step 3 (app_wait_for): [timeout] step 3 of 3 (app_wait_for) failed: timed out after 3.003s waiting for testid=busyOutcome to contain \": current\" — its text is \"row B, generation 1: stale\"; steps 1-2 ran before it, and nothing after FAIL [android · emulator-5554] busy.test.json › a row tapped afte…", "gold": false}, {"id": "docs/guides/test-runner.md#the-commands", "heading": "The commands", "path": "docs/guides/test-runner.md", "excerpt": "| Command | What it does | | --- | --- | | `mobium test` | runs every `*.test.json` under the config's `testDir`, on every project | | `mobium test tests/login.test.json` | runs one file, or every file under a directory | | `mobium test -g login` | runs the tests whose title — \"file › name\" — matches a regular expression | | `mobium test --last-failed` | runs only the tests that failed last time | | `mobium test --pr…", "gold": false}, {"id": "docs/guides/graybox-tutorial.md#1-the-test", "heading": "1. The test", "path": "docs/guides/graybox-tutorial.md", "excerpt": "The Busy Demo's **Refresh quietly** starts 0.4 to 1.6 seconds of work and leaves the old rows up while it runs; then a new generation of rows replaces them. Tapping a row says whether it was `current` or `stale`. The test taps the refresh, then Row B, and expects the row to be current — five times, each from a fresh app: ``` busy-tests/ mobium.config.json tests/ busy.test.json ``` ```json { \"testDir\": \"tests\", \"proje…", "gold": false}], "missed": false, "facts": [], "concern": "Docs gap: the 60 s default per-test timeout (cmd/mobium/test.go:84, 239) is not stated anywhere in the docs; test-runner.md's commands table could say it.", "check": "Claude's reading: the code's default is 60 s per test (test.go:84 and the flag default at 239), but no corpus section states it: the commands table gives `--timeout 30s` as an example and says the config's timeout is milliseconds, and section 2's \"ten seconds\" is each assertion's timeout, the likely wrong answer. Nearest sections: docs/guides/test-runner.md#the-commands, docs/guides/test-runner.md#2-run-it. Verified in: cmd/mobium/test.go:84, cmd/mobium/test.go:239."}, {"id": "g061", "kind": "fact", "question": "My Charles proxy listens on port 8888 on my Mac. How do I send an Android emulator's app traffic through it with Mobium without looking up the Mac's LAN address?", "tags": ["how-to", "test-author", "new since 7b590a4"], "gold": [{"id": "docs/guides/network.md#5-through-a-proxy", "heading": "5. Through a proxy", "path": "docs/guides/network.md", "excerpt": "`--proxy host:port` points the device's HTTP proxy at a debugging proxy — Charles, Fiddler, mitmproxy, anything that listens on a port — so it sees what the app sends and receives. A proxy on `127.0.0.1` or `localhost` is this machine's: Mobium reverses its port with `adb reverse` before pointing the device at it, so there is no address on the network to find and no firewall in the way. Measured on the emulator on 20…"}], "retrieved": [{"id": "docs/guides/network.md#5-through-a-proxy", "heading": "5. Through a proxy", "path": "docs/guides/network.md", "excerpt": "`--proxy host:port` points the device's HTTP proxy at a debugging proxy — Charles, Fiddler, mitmproxy, anything that listens on a port — so it sees what the app sends and receives. A proxy on `127.0.0.1` or `localhost` is this machine's: Mobium reverses its port with `adb reverse` before pointing the device at it, so there is no address on the network to find and no firewall in the way. Measured on the emulator on 20…", "gold": true}, {"id": "docs/PROXY.md#a-proxy-between-the-app-and-its-servers", "heading": "A proxy between the app and its servers", "path": "docs/PROXY.md", "excerpt": "What it would take for Mobium to route a device's traffic through a debugging proxy, so a test can see, shape and change what an app sends and receives — and to drive Charles, as an opt-in, the way a tester drives it by hand: record a session, throttle, switch Map Local and Rewrite rules on and off. What was measured, and the plan, in the order it should be built. **Status on 2026-10-22.** Step 1 is measured (below),…", "gold": false}, {"id": "docs/PROXY.md#the-shape", "heading": "The shape", "path": "docs/PROXY.md", "excerpt": "Two layers, the second opt-in. - **A proxy, any proxy.** `mobium network --proxy <host:port>` points the device at a proxy and reads it back; `--no-proxy` takes it off; the end of the session puts back what was there, as every network setting is put back. A proxy's root certificate is installed where the device allows it, so HTTPS can be decrypted. This works with Charles, Fiddler, mitmproxy or anything else that lis…", "gold": false}, {"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": false}, {"id": "docs/PROXY.md#what-was-measured-2026-10-20", "heading": "What was measured — 2026-10-20", "path": "docs/PROXY.md", "excerpt": "Charles 5.2.1 headless on the Mac, with a configuration of its own, and the Android 15 emulator. - **The configuration file can be written, not clicked.** Charles writes only what differs from its defaults, so its element names were read from its classes: `proxyConfiguration` holds `port`, `decryptSSL`, `sslLocations` (`locationPatterns` of `locationMatch`, each a `location` and `enabled`) and `macOSXConfiguration` w…", "gold": false}], "missed": false, "facts": ["Run `mobium network --proxy 127.0.0.1:8888` (host:port) to set the device's HTTP proxy. ⟦--proxy⟧", "A proxy on 127.0.0.1 or localhost is the host machine's: Mobium reverses its port with adb reverse before pointing the device at it, so no LAN address or firewall is involved. ⟦adb reverse⟧"], "concern": "", "check": "Claude's reading: network.md section 5 gives the command and the adb reverse behavior; code reverses the port only for a loopback host (IsLoopback) and ParseProxy takes host:port only. PROXY.md describes a planned `--proxy charles` that is not built (ParseProxy would refuse it), so an answer offering it is wrong. Verified in: cmd/mobium/network.go:76, internal/agent/network.go:192, internal/device/proxy.go:134, internal/mobiumdriver/network.go:78."}, {"id": "g062", "kind": "fact", "question": "I removed the emulator's proxy with `adb shell settings delete global http_proxy`, it reads back null, yet my app still tries to connect to 127.0.0.1:8888. Why, and how do I clear it for real?", "tags": ["troubleshooting", "test-author", "new since 7b590a4"], "gold": [{"id": "docs/guides/network.md#5-through-a-proxy", "heading": "5. Through a proxy", "path": "docs/guides/network.md", "excerpt": "`--proxy host:port` points the device's HTTP proxy at a debugging proxy — Charles, Fiddler, mitmproxy, anything that listens on a port — so it sees what the app sends and receives. A proxy on `127.0.0.1` or `localhost` is this machine's: Mobium reverses its port with `adb reverse` before pointing the device at it, so there is no address on the network to find and no firewall in the way. Measured on the emulator on 20…"}], "retrieved": [{"id": "docs/PROXY.md#pointing-each-device-at-it", "heading": "Pointing each device at it", "path": "docs/PROXY.md", "excerpt": "| Device | Proxy | Its certificate | | --- | --- | --- | | Android emulator | `settings put global http_proxy`, read back, and `adb reverse tcp:<port> tcp:<port>` so `127.0.0.1` on the device is the Mac | the user store, trusted only by apps that opt in; the system store needs a writable system image | | Android phone, TV | the same, over USB or Wi-Fi adb, no root | the user store only | | iOS simulator | the Mac's o…", "gold": false}, {"id": "docs/guides/network.md#5-through-a-proxy", "heading": "5. Through a proxy", "path": "docs/guides/network.md", "excerpt": "`--proxy host:port` points the device's HTTP proxy at a debugging proxy — Charles, Fiddler, mitmproxy, anything that listens on a port — so it sees what the app sends and receives. A proxy on `127.0.0.1` or `localhost` is this machine's: Mobium reverses its port with `adb reverse` before pointing the device at it, so there is no address on the network to find and no firewall in the way. Measured on the emulator on 20…", "gold": true}, {"id": "docs/PROXY.md#2---proxy-on-android", "heading": "2. `--proxy` on Android", "path": "docs/PROXY.md", "excerpt": "**The setting, done 2026-10-22** (`docs/guides/network.md`, section 5): set, read back from the keys in force, taken off with `:0` and every key deleted, put back at the session's end; a loopback proxy's port reversed before the device points at it, and only Mobium's reverses removed. A reverse that was there before is left — a test caught the first version taking it as its own. `proxy.sh` fetches a port nothing on t…", "gold": false}, {"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": false}, {"id": "docs/ROADMAP.md#under-consideration", "heading": "Under consideration", "path": "docs/ROADMAP.md", "excerpt": "- **Locators for when there is no ref** (written down 2026-10-12). A ref from `map` lasts one map, so an agent has one and a `mobium test` file does not: a hand-written test has the flat `kind=value` locators — text, label, testid, role, class, path, narrowed by `,role=` — which match one element or are refused. That is right on a form and leaves nothing durable on a list. Every Ice Cubes post has a \"…\" (CHALLENGES 2…", "gold": false}], "missed": false, "facts": ["Android derives global_http_proxy_host and _port from http_proxy, and deleting http_proxy leaves them, and the proxy, in force. ⟦global_http_proxy_host⟧", "`mobium network --no-proxy` takes it off the way that sticks: http_proxy set to :0, then every proxy key deleted. ⟦--no-proxy ; :0⟧"], "concern": "", "check": "Claude's reading: network.md section 5 states both facts; proxy.go writes `:0` then deletes the host, port, exclusion list and PAC keys and reads the proxy in force back. PROXY.md#what-was-measured-2026-10-20 has the same finding at length but no Mobium command. Verified in: internal/device/proxy.go:16, internal/device/proxy.go:69, cmd/mobium/network.go:77."}, {"id": "g063", "kind": "fact", "question": "Can Mobium point my real Pixel's network traffic at a debugging proxy, and can it do the same for an iPhone?", "tags": ["support", "new-user", "new since 7b590a4"], "gold": [{"id": "docs/guides/network.md#what-each-device-can-do", "heading": "What each device can do", "path": "docs/guides/network.md", "excerpt": "| | Offline | Latency and bandwidth | A proxy | | --- | --- | --- | --- | | **Android emulator** | yes | yes | yes | | **Android phone** | yes | no — shaping traffic needs root, which a phone does not give | yes — the same setting, no root (Pixel 8 Pro, Android 17) | | **iOS simulator or iPhone** | no | no — nothing outside iOS controls its network | no | Offline is airplane mode, which any Android device takes. Late…"}], "retrieved": [{"id": "docs/PROXY.md#a-proxy-between-the-app-and-its-servers", "heading": "A proxy between the app and its servers", "path": "docs/PROXY.md", "excerpt": "What it would take for Mobium to route a device's traffic through a debugging proxy, so a test can see, shape and change what an app sends and receives — and to drive Charles, as an opt-in, the way a tester drives it by hand: record a session, throttle, switch Map Local and Rewrite rules on and off. What was measured, and the plan, in the order it should be built. **Status on 2026-10-22.** Step 1 is measured (below),…", "gold": false}, {"id": "docs/guides/network.md#5-through-a-proxy", "heading": "5. Through a proxy", "path": "docs/guides/network.md", "excerpt": "`--proxy host:port` points the device's HTTP proxy at a debugging proxy — Charles, Fiddler, mitmproxy, anything that listens on a port — so it sees what the app sends and receives. A proxy on `127.0.0.1` or `localhost` is this machine's: Mobium reverses its port with `adb reverse` before pointing the device at it, so there is no address on the network to find and no firewall in the way. Measured on the emulator on 20…", "gold": false}, {"id": "docs/PROXY.md#2---proxy-on-android", "heading": "2. `--proxy` on Android", "path": "docs/PROXY.md", "excerpt": "**The setting, done 2026-10-22** (`docs/guides/network.md`, section 5): set, read back from the keys in force, taken off with `:0` and every key deleted, put back at the session's end; a loopback proxy's port reversed before the device points at it, and only Mobium's reverses removed. A reverse that was there before is left — a test caught the first version taking it as its own. `proxy.sh` fetches a port nothing on t…", "gold": false}, {"id": "docs/PROXY.md#what-was-measured-2026-10-20", "heading": "What was measured — 2026-10-20", "path": "docs/PROXY.md", "excerpt": "Charles 5.2.1 headless on the Mac, with a configuration of its own, and the Android 15 emulator. - **The configuration file can be written, not clicked.** Charles writes only what differs from its defaults, so its element names were read from its classes: `proxyConfiguration` holds `port`, `decryptSSL`, `sslLocations` (`locationPatterns` of `locationMatch`, each a `location` and `enabled`) and `macOSXConfiguration` w…", "gold": false}, {"id": "docs/guides/network.md#what-each-device-can-do", "heading": "What each device can do", "path": "docs/guides/network.md", "excerpt": "| | Offline | Latency and bandwidth | A proxy | | --- | --- | --- | --- | | **Android emulator** | yes | yes | yes | | **Android phone** | yes | no — shaping traffic needs root, which a phone does not give | yes — the same setting, no root (Pixel 8 Pro, Android 17) | | **iOS simulator or iPhone** | no | no — nothing outside iOS controls its network | no | Offline is airplane mode, which any Android device takes. Late…", "gold": true}], "missed": false, "facts": ["On an Android phone the proxy works: the same setting as the emulator, with no root needed (measured on a Pixel 8 Pro, Android 17). ⟦no root⟧", "On an iOS simulator or iPhone, Mobium cannot set a proxy (nor offline or shaping); iOS refuses."], "concern": "", "check": "Claude's reading: the table in network.md has a proxy column added after the pin; app_network on an iOS driver has no Networker capability and is refused (network.go:71). PROXY.md plans a Wi-Fi proxy on a real iPhone through Settings (step 5), not built — a right answer says no today. Verified in: internal/device/proxy.go:69, internal/agent/network.go:71, internal/agent/schema.go:2135."}, {"id": "g064", "kind": "fact", "question": "Will Mobium's device proxy capture the HTTP requests of an app written in Flutter?", "tags": ["support", "test-author", "new since 7b590a4"], "gold": [{"id": "docs/PROXY.md#what-a-proxy-cannot-see", "heading": "What a proxy cannot see", "path": "docs/PROXY.md", "excerpt": "Every result names which of these applies rather than reporting an empty session as a quiet app. - **Flutter ignores the system proxy.** Dart's HTTP client reads no proxy setting unless the app gives it one, so a Flutter app's traffic goes around the proxy. - **Android apps trust only system certificates since Android 7**, unless their network security configuration opts in to user ones — debug builds usually, releas…"}], "retrieved": [{"id": "docs/guides/network.md#5-through-a-proxy", "heading": "5. Through a proxy", "path": "docs/guides/network.md", "excerpt": "`--proxy host:port` points the device's HTTP proxy at a debugging proxy — Charles, Fiddler, mitmproxy, anything that listens on a port — so it sees what the app sends and receives. A proxy on `127.0.0.1` or `localhost` is this machine's: Mobium reverses its port with `adb reverse` before pointing the device at it, so there is no address on the network to find and no firewall in the way. Measured on the emulator on 20…", "gold": false}, {"id": "docs/PROXY.md#what-was-measured-2026-10-20", "heading": "What was measured — 2026-10-20", "path": "docs/PROXY.md", "excerpt": "Charles 5.2.1 headless on the Mac, with a configuration of its own, and the Android 15 emulator. - **The configuration file can be written, not clicked.** Charles writes only what differs from its defaults, so its element names were read from its classes: `proxyConfiguration` holds `port`, `decryptSSL`, `sslLocations` (`locationPatterns` of `locationMatch`, each a `location` and `enabled`) and `macOSXConfiguration` w…", "gold": false}, {"id": "docs/PROXY.md#what-a-proxy-cannot-see", "heading": "What a proxy cannot see", "path": "docs/PROXY.md", "excerpt": "Every result names which of these applies rather than reporting an empty session as a quiet app. - **Flutter ignores the system proxy.** Dart's HTTP client reads no proxy setting unless the app gives it one, so a Flutter app's traffic goes around the proxy. - **Android apps trust only system certificates since Android 7**, unless their network security configuration opts in to user ones — debug builds usually, releas…", "gold": true}, {"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": false}], "missed": false, "facts": ["No: Flutter ignores the system proxy — Dart's HTTP client reads no proxy setting unless the app gives it one, so its traffic goes around the proxy. ⟦Dart ; system proxy⟧"], "concern": "", "check": "Claude's reading: Mobium only sets Android's global http_proxy (proxy.go SetProxy), so an app that ignores the system proxy is not covered; the Flutter behavior itself is a platform fact, not in Mobium code. network.md#5-through-a-proxy also says \"Flutter does not\" in one line — reviewer may want it as a second acceptable gold. Verified in: internal/device/proxy.go:69."}, {"id": "g065", "kind": "fact", "question": "Why does Mobium shape the emulator's traffic itself instead of using the emulator console's `network speed` and `network delay` commands?", "tags": ["rationale", "contributor"], "gold": [{"id": "docs/guides/network.md#why-not-the-emulators-own-throttling", "heading": "Why not the emulator's own throttling", "path": "docs/guides/network.md", "excerpt": "The Android emulator's console has `network speed` and `network delay`, and they look made for this. They accept a setting and read it back — and change nothing: on emulator 37.1.11, 2MB at a 1000 kbit/s limit still arrived in 1.1 seconds where 16 were due, and a 500ms delay left a ping at 1ms. So Mobium does not use them; it shapes the traffic itself, and every figure above was measured from the traffic, not the set…"}], "retrieved": [{"id": "docs/guides/network.md#why-not-the-emulators-own-throttling", "heading": "Why not the emulator's own throttling", "path": "docs/guides/network.md", "excerpt": "The Android emulator's console has `network speed` and `network delay`, and they look made for this. They accept a setting and read it back — and change nothing: on emulator 37.1.11, 2MB at a 1000 kbit/s limit still arrived in 1.1 seconds where 16 were due, and a 500ms delay left a ping at 1ms. So Mobium does not use them; it shapes the traffic itself, and every figure above was measured from the traffic, not the set…", "gold": true}, {"id": "skills/mobile-check/SKILL.md#network", "heading": "Network", "path": "skills/mobile-check/SKILL.md", "excerpt": "- `mobium network` — what is in place: online or offline, and any shaping - `mobium network --offline` / `--online` — airplane mode, waited for until the network is really gone or back; an emulator or a real Android phone - `mobium network --latency 300 --download 1600 --upload 750` — shape the traffic, replacing any shaping before; an emulator only (it needs root) - `mobium network --reset` — no shaping, airplane mo…", "gold": false}, {"id": "CHALLENGES#findings-that-were-not-defects", "heading": "Findings that were not defects", "path": "docs/CHALLENGES.md", "excerpt": "Worth recording because each one closed off an approach that looked obvious. - **Predictive back on Android 15 closes a React Native app.** MobiumApp built with predictive back turned on went back to closing on every back from a demo on the Android 15 AVD, `BackHandler` never called, while on Android 17 — the AVD and the Pixel 8 Pro — it went back to its home screen. React Native 0.86 registers the callback that repl…", "gold": false}, {"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": false}, {"id": "docs/guides/network.md#the-commands", "heading": "The commands", "path": "docs/guides/network.md", "excerpt": "| Command | What it does | | --- | --- | | `mobium network` | reads what the device has: online or offline, and any shaping | | `mobium network --offline` | airplane mode on, and waits for the network to go | | `mobium network --online` | airplane mode off, and waits for the network to come back | | `mobium network --latency 300` | adds 300ms to every round trip (emulator) | | `mobium network --download 1600 --upload…", "gold": false}], "missed": false, "facts": ["The console commands accept and read back a setting but change nothing: 2MB at a 1000 kbit/s limit still arrived in 1.1 seconds where 16 were due, and a 500ms delay left a ping at 1ms. ⟦1.1 seconds⟧", "So Mobium shapes the traffic itself (Linux traffic control) and measures from the traffic, not the setting."], "concern": "", "check": "Claude's reading: network.md's section and the comment at device/network.go:18 agree on the measurement (emulator 37.1.11); the code uses `tc` under su. Verified in: internal/device/network.go:18, internal/device/network.go:111."}, {"id": "g066", "kind": "fact", "question": "On iOS the location permission prompt shows Allow Once, Allow While Using App and Don't Allow. What happens if my script runs `mobium alert accept` on it, and how do I choose one of them?", "tags": ["behavior", "test-author"], "gold": [{"id": "skills/mobile-check/SKILL.md#dialogs", "heading": "Dialogs", "path": "skills/mobile-check/SKILL.md", "excerpt": "- `mobium alert` — is a system or app dialog up, what does it say, and what are its buttons - `mobium alert accept` / `dismiss` — yes and no, on a dialog of one or two buttons: a two-button permission prompt is granted by accept and denied by dismiss, in any language. **A dialog of three or more is refused**, naming its buttons — the location prompt has two that grant — and every answer says which button it pressed. …"}], "retrieved": [{"id": "CHALLENGES#305", "heading": "305. `accept` on iOS's location prompt pressed Don't Allow, and said only \"accepted\"", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** reviewing a golden-set question for the docs evaluation — \"which button does `alert accept` press on an iOS permission prompt?\" — whose right answer, Don't Allow, read as a defect rather than an answer. Measured on an iPhone 17 Pro simulator, iOS 26.5, on MobiumApp's Dialog Demo, and on the Android 15 emulator. CHALLENGES 63 and 106 found that accept and dismiss press a button the platform picks, and se…", "gold": false}, {"id": "CHALLENGES#76", "heading": "76. The fix for 71 hid system dialogs from `map`", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** MobiumApp on the iPhone, the same day. The app's location prompt was on screen and `alert` reported it word for word — and `map` listed only the app underneath: Back, the two drafts, \"Ask for location\". Tapping \"Allow While Using App\" answered \"no element matches\". `current` said `dev.mobium.mobiumapp`. It was 71's hint, still in force. `defaultActiveApplication` had been set to MobiumApp by the launch …", "gold": false}, {"id": "CHALLENGES#63", "heading": "63. `accept` denied the permission and `dismiss` granted it", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** checking what the new alert tool actually did, rather than what it was called. On iOS 26.5, from a fresh permission reset each time: | | outcome | | --- | --- | | `app_alert accept` | permission **denied** | | `app_alert dismiss` | permission **granted** | Backwards, and reproducibly so. **The first explanation written here was a guess, and it was wrong in a way worth keeping.** It said accept presses t…", "gold": false}], "missed": true, "facts": ["accept and dismiss only answer a dialog of one or two buttons; a dialog of three or more is refused, naming its buttons, because more than one may mean yes. ⟦three or more⟧", "Press one by caption or position from 1 with `mobium alert --button \"Allow While Using App\"`; captions match in any case with straight or curly quotes. ⟦--button⟧"], "concern": "", "check": "Claude's reading: SKILL.md#dialogs states both; alert.go refuses len(buttons) > 2 with the remedy to use button, and normalizes curly quotes for captions. CHALLENGES#305 is the history (accept pressed Don't Allow) but is not needed for the answer. Verified in: internal/agent/alert.go:201, internal/agent/alert.go:262, internal/agent/alert.go:409, cmd/mobium/alert.go:52."}, {"id": "g067", "kind": "fact", "question": "In a mobium test file, how do I make iOS's offer to save a password after login get answered automatically in every test, and what does that do when the same file runs on Android?", "tags": ["how-to", "test-author"], "gold": [{"id": "docs/guides/test-runner.md#writing-tests", "heading": "Writing tests", "path": "docs/guides/test-runner.md", "excerpt": "- **Find targets with `map` first.** `mobium map` on the screen you are testing gives each element's locator; `testid=` is the one that survives a translation and a redesign. - **Assert with `app_wait_for`**, never a sleep. `--for` in the CLI is `condition` in a step: `visible`, `hidden`, `text` (with `exact`), `value`, `enabled`, `disabled`, `checked`, `unchecked`, `selected`, `unselected`, `focused`, `count`, and `…"}], "retrieved": [{"id": "docs/guides/test-runner.md#writing-tests", "heading": "Writing tests", "path": "docs/guides/test-runner.md", "excerpt": "- **Find targets with `map` first.** `mobium map` on the screen you are testing gives each element's locator; `testid=` is the one that survives a translation and a redesign. - **Assert with `app_wait_for`**, never a sleep. `--for` in the CLI is `condition` in a step: `visible`, `hidden`, `text` (with `exact`), `value`, `enabled`, `disabled`, `checked`, `unchecked`, `selected`, `unselected`, `focused`, `count`, and `…", "gold": true}, {"id": "CHALLENGES#170", "heading": "170. A dialog rule answered in front of an action, not in front of a wait", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** `tests/mobiumapp` run by `mobium test` on the iPhone 15 Plus. \"the demo account signs in, and out\" failed at its wait for the welcome screen, with the failure itself saying that screen was under \"Save Password?\" — the dialog `login.test.json` declares a rule for. A rule (`app_dialogs`) answered a dialog only when an action resolved its target and found the dialog over it. Sign-in is a tap, and iOS raise…", "gold": false}, {"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": false}, {"id": "docs/guides/cli.md#7-several-steps-in-one-call-batch", "heading": "7. Several steps in one call: `batch`", "path": "docs/guides/cli.md", "excerpt": "A known sequence can go as one call — from a file, or `-` for stdin. Every step is checked before the first runs, and it stops at the first failure, with that step's own error: ```json [ {\"name\": \"app_tap\", \"arguments\": {\"target\": \"label=Login Demo\"}}, {\"name\": \"app_fill\", \"arguments\": {\"target\": \"testid=username\", \"text\": \"mobium\"}}, {\"name\": \"app_fill\", \"arguments\": {\"target\": \"testid=password\", \"text\": \"hunter2\"}}…", "gold": false}, {"id": "docs/guides/autowait.md#2-waiting-for-a-control-to-be-enabled", "heading": "2. Waiting for a control to be enabled", "path": "docs/guides/autowait.md", "excerpt": "The Login Demo disables Log In while it signs in. Tap it, and tap it again at once: ``` $ mobium fill testid=username mobium typed \"mobium\" into testid=username $ mobium fill testid=password wrongpass1 typed 10 characters into testid=password, a password field — not echoed $ mobium tap testid=loginBtn tapped testid=loginBtn at (540, 1457) $ mobium wait testid=loginBtn --for disabled testid=loginBtn is disabled after …", "gold": false}], "missed": false, "facts": ["Add an app_dialogs rule in beforeEach: {\"name\": \"app_dialogs\", \"arguments\": {\"when\": \"Save Password\", \"press\": \"Not Now\"}}. ⟦app_dialogs ; beforeEach ; Not Now⟧", "On Android the rule never fires, since that dialog never comes there."], "concern": "", "check": "Claude's reading: test-runner.md 'Writing tests' gives the exact step; dialogs.go matches a rule when the dialog text contains `when`, ignoring case, and presses the captioned button. SKILL.md#dialogs shows the CLI form (`mobium dialogs --when ... --press ...`) but not the test-file form. Verified in: internal/agent/dialogs.go:56, internal/agent/dialogs.go:105, internal/agent/dialogs.go:116."}, {"id": "g068", "kind": "fact", "question": "My Android app posts a notification and I need my test to tap it. `mobium map` doesn't show it — what do I do?", "tags": ["how-to", "test-author"], "gold": [{"id": "skills/mobile-check/SKILL.md#interruptions-and-hardware-buttons", "heading": "Interruptions and hardware buttons", "path": "skills/mobile-check/SKILL.md", "excerpt": "```sh mobium press back # primary navigation on Android; says where it went mobium press back --gesture # the swipe in from the edge; the only back on iOS mobium press home # says the launcher came forward mobium lock lock # a state, not a toggle mobium call ring # then accept, or hang mobium sms \"your code is 123456\" mobium timezone Asia/Tokyo mobium notifications # what is in the shade? mobium notifications --post …"}], "retrieved": [{"id": "CHALLENGES#155", "heading": "155. A notification banner hid the app under it on iOS", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** MobiumApp's OTP Demo on the iPhone 17 Pro simulator, iOS 26.5, reading the outcome right after the app posted its code as a notification. While the banner was up — about five seconds — every read answered with SpringBoard: `current` named it, `text testid=otpOutcome` found nothing, and `map` listed the banner and nothing of the app behind it, which was still in front and still taking touches. WebDriverA…", "gold": false}, {"id": "docs/guides/test-runner.md#writing-tests", "heading": "Writing tests", "path": "docs/guides/test-runner.md", "excerpt": "- **Find targets with `map` first.** `mobium map` on the screen you are testing gives each element's locator; `testid=` is the one that survives a translation and a redesign. - **Assert with `app_wait_for`**, never a sleep. `--for` in the CLI is `condition` in a step: `visible`, `hidden`, `text` (with `exact`), `value`, `enabled`, `disabled`, `checked`, `unchecked`, `selected`, `unselected`, `focused`, `count`, and `…", "gold": false}, {"id": "skills/mobile-check/SKILL.md#when-things-fail", "heading": "When things fail", "path": "skills/mobile-check/SKILL.md", "excerpt": "Mobium's errors say what to do; read them rather than retrying blindly. Every failure also carries a **code**, so you can act on the kind without parsing the sentence: `--json` prints it (`\"code\": \"no_such_element\"`, with a `remedy` and `details`), and the exit status groups it: | Exit | Codes | What to do | | --- | --- | --- | | 2 | `invalid_argument` | fix the command; retrying it unchanged cannot help | | 3 | `no_…", "gold": false}, {"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": false}, {"id": "docs/ROADMAP.md#under-consideration", "heading": "Under consideration", "path": "docs/ROADMAP.md", "excerpt": "- **Locators for when there is no ref** (written down 2026-10-12). A ref from `map` lasts one map, so an agent has one and a `mobium test` file does not: a hand-written test has the flat `kind=value` locators — text, label, testid, role, class, path, narrowed by `,role=` — which match one element or are refused. That is right on a form and leaves nothing durable on a list. Every Ice Cubes post has a \"…\" (CHALLENGES 2…", "gold": false}], "missed": true, "facts": ["A notification cannot be tapped until the shade is open: run `mobium notifications --shade open`, then `map`, then tap it. ⟦--shade open⟧", "Close the shade when finished, or every later locator fails against the panel covering the app."], "concern": "", "check": "Claude's reading: SKILL.md states it; adb.go runs `cmd statusbar expand-notifications` for open, and the tool description says opening or closing the shade discards the last map's refs. Verified in: cmd/mobium/notifications.go:42, internal/device/adb.go:1548, internal/agent/schema.go:983."}, {"id": "g069", "kind": "fact", "question": "I want one test to run with VoiceOver on, on a real iPhone, without leaving the phone with VoiceOver on afterward. How do I do that with Mobium?", "tags": ["how-to", "test-author", "new since 7b590a4"], "gold": [{"id": "docs/ACCESSIBILITY.md#5-a-screen-reader-as-a-setting-built", "heading": "5. A screen reader as a setting — built", "path": "docs/ACCESSIBILITY.md", "excerpt": "`mobium accessibility screen_reader on` — TalkBack on Android and VoiceOver on an iPhone on iOS 27 — confirmed by reading back, and put back when the session ends, as the other settings are. It makes \"run this test with the screen reader on\" a line in a test file. As built: - **Android:** TalkBack's service added to the enabled ones, the others kept, and `accessibility_enabled` on. Confirmed by Android binding TalkBa…"}], "retrieved": [{"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": false}, {"id": "docs/ACCESSIBILITY.md#5-a-screen-reader-as-a-setting-built", "heading": "5. A screen reader as a setting — built", "path": "docs/ACCESSIBILITY.md", "excerpt": "`mobium accessibility screen_reader on` — TalkBack on Android and VoiceOver on an iPhone on iOS 27 — confirmed by reading back, and put back when the session ends, as the other settings are. It makes \"run this test with the screen reader on\" a line in a test file. As built: - **Android:** TalkBack's service added to the enabled ones, the others kept, and `accessibility_enabled` on. Confirmed by Android binding TalkBa…", "gold": true}, {"id": "docs/ACCESSIBILITY.md#voiceover-on-a-real-iphone-2026-10-20", "heading": "VoiceOver on a real iPhone — 2026-10-20", "path": "docs/ACCESSIBILITY.md", "excerpt": "On the iPhone 15 Plus, iOS 27.0.1, through WebDriverAgent 16.12.8 rebuilt with Xcode 27.1, called directly over HTTP. VoiceOver was off before, and read back off after every run. - **The runner has to be built with Xcode 27.** WebDriverAgent's `/wda/voiceOver/enable`, `/disable`, `/enabled`, `/move` and `/currentSpeech` reach XCUIAutomation's VoiceOver service, which Xcode 27's has and 26.6's does not. The phone's ru…", "gold": false}, {"id": "docs/SETUP.md#with-a-screen-reader-on", "heading": "With a screen reader on", "path": "docs/SETUP.md", "excerpt": "Android's test-automation connection silences every other accessibility service while it is open, unless it is opened not to. So on a device with TalkBack — or VoiceView, on a Fire TV — on, a read of the screen takes the screen reader away for as long as it runs, and an app that publishes its contents only to a screen reader stops publishing them (CHALLENGES 208). Both drivers leave the screen reader running. The def…", "gold": false}], "missed": false, "facts": ["`mobium accessibility screen_reader on` (app_accessibility, setting screen_reader) turns VoiceOver on an iPhone on iOS 27, confirmed by reading back. ⟦screen_reader on ; iOS 27⟧", "It is put back as found when the session ends; on a phone the session's restore is the only safe way to turn it on. ⟦put back when the session ends⟧"], "concern": "", "check": "Claude's reading: ACCESSIBILITY.md step 5 and the code agree: VoiceOver via WebDriverAgent's enable/disable, undo run at session end; simulators and Apple TV are refused (axsettings.go:93). Verified in: internal/agent/schema.go:1624, internal/mobiumdriver/axsettings.go:89, internal/agent/accessibility.go:18, internal/agent/accessibility.go:134."}, {"id": "g070", "kind": "fact", "question": "With VoiceOver turned on on an iPhone, what does `mobium tap` actually do, and what happens if my test tries to swipe?", "tags": ["behavior", "test-author", "new since 7b590a4"], "gold": [{"id": "docs/ACCESSIBILITY.md#1-a-tap-with-voiceover-on-lands-or-is-refused-built-243", "heading": "1. A tap with VoiceOver on lands, or is refused — built, #243", "path": "docs/ACCESSIBILITY.md", "excerpt": "The defect above, fixed before anything is built on VoiceOver, since every later step drives a screen with it on. As built: VoiceOver is asked about before every touch, since it costs milliseconds and a person can turn it on mid-session; tap, `check`, an alert's button and a dialog rule touch, read the cursor back, and double-tap; typing focuses the field that way; every other touch is refused naming VoiceOver; a pho…"}], "retrieved": [{"id": "CHALLENGES#348", "heading": "348. With VoiceOver on, a tap moved its cursor and was reported done", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** measuring what WebDriverAgent's VoiceOver routes give, on the iPhone 15 Plus on iOS 27.0.1, for a plan of what Mobium could do for people who use a screen reader. With VoiceOver on, a touch is not a tap: it moves VoiceOver's cursor to what it touches, as a person's single tap does, and a double tap anywhere activates what the cursor is on. So on MobiumApp `tap \"label=Pro\"` answered `tapped label=Pro` an…", "gold": false}, {"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": false}, {"id": "docs/ACCESSIBILITY.md#voiceover-on-a-real-iphone-2026-10-20", "heading": "VoiceOver on a real iPhone — 2026-10-20", "path": "docs/ACCESSIBILITY.md", "excerpt": "On the iPhone 15 Plus, iOS 27.0.1, through WebDriverAgent 16.12.8 rebuilt with Xcode 27.1, called directly over HTTP. VoiceOver was off before, and read back off after every run. - **The runner has to be built with Xcode 27.** WebDriverAgent's `/wda/voiceOver/enable`, `/disable`, `/enabled`, `/move` and `/currentSpeech` reach XCUIAutomation's VoiceOver service, which Xcode 27's has and 26.6's does not. The phone's ru…", "gold": false}, {"id": "docs/ACCESSIBILITY.md#5-a-screen-reader-as-a-setting-built", "heading": "5. A screen reader as a setting — built", "path": "docs/ACCESSIBILITY.md", "excerpt": "`mobium accessibility screen_reader on` — TalkBack on Android and VoiceOver on an iPhone on iOS 27 — confirmed by reading back, and put back when the session ends, as the other settings are. It makes \"run this test with the screen reader on\" a line in a test file. As built: - **Android:** TalkBack's service added to the enabled ones, the others kept, and `accessibility_enabled` on. Confirmed by Android binding TalkBa…", "gold": false}, {"id": "docs/ACCESSIBILITY.md#1-a-tap-with-voiceover-on-lands-or-is-refused-built-243", "heading": "1. A tap with VoiceOver on lands, or is refused — built, #243", "path": "docs/ACCESSIBILITY.md", "excerpt": "The defect above, fixed before anything is built on VoiceOver, since every later step drives a screen with it on. As built: VoiceOver is asked about before every touch, since it costs milliseconds and a person can turn it on mid-session; tap, `check`, an alert's button and a dialog rule touch, read the cursor back, and double-tap; typing focuses the field that way; every other touch is refused naming VoiceOver; a pho…", "gold": true}], "missed": false, "facts": ["A tap touches the target to move VoiceOver's cursor, reads the cursor back, and double-taps to activate it (also for check, an alert's button and a dialog rule). ⟦double-tap⟧", "Every other touch, such as a swipe, is refused naming VoiceOver. ⟦refused naming VoiceOver⟧"], "concern": "", "check": "Claude's reading: ACCESSIBILITY.md step 1 matches screenreader.go touch() (FocusAt, compare spoken name, ActivateFocused) and voiceOverGuard refusing other touches. A cursor landing elsewhere is refused (screenreader.go:35); SETUP.md#with-a-screen-reader-on says the same in brief. Verified in: internal/agent/screenreader.go:23, internal/mobiumdriver/voiceover.go:111, internal/mobiumdriver/voiceover.go:120."}, {"id": "g071", "kind": "fact", "question": "`mobium speech` on my Android emulator with TalkBack on refuses and says nothing is logged. What do I have to change?", "tags": ["troubleshooting", "test-author", "new since 7b590a4"], "gold": [{"id": "docs/ACCESSIBILITY.md#2-hear-the-screen-reader-appspeech-built", "heading": "2. Hear the screen reader: `app_speech` — built", "path": "docs/ACCESSIBILITY.md", "excerpt": "`mobium speech` and `app_speech` in all five clients: what the screen reader says about the element its cursor is on; with a target, the cursor put on it first; with `walk`, a move forward at a time in the screen reader's own order until it goes no further, comes back round, or `limit` moves are made. Each sentence is beside the element it was said about, its locator, and whether `map` lists it — a heading, a caption…"}], "retrieved": [{"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": false}, {"id": "CHALLENGES#348", "heading": "348. With VoiceOver on, a tap moved its cursor and was reported done", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** measuring what WebDriverAgent's VoiceOver routes give, on the iPhone 15 Plus on iOS 27.0.1, for a plan of what Mobium could do for people who use a screen reader. With VoiceOver on, a touch is not a tap: it moves VoiceOver's cursor to what it touches, as a person's single tap does, and a double tap anywhere activates what the cursor is on. So on MobiumApp `tap \"label=Pro\"` answered `tapped label=Pro` an…", "gold": false}, {"id": "docs/ACCESSIBILITY.md#2-hear-the-screen-reader-appspeech-built", "heading": "2. Hear the screen reader: `app_speech` — built", "path": "docs/ACCESSIBILITY.md", "excerpt": "`mobium speech` and `app_speech` in all five clients: what the screen reader says about the element its cursor is on; with a target, the cursor put on it first; with `walk`, a move forward at a time in the screen reader's own order until it goes no further, comes back round, or `limit` moves are made. Each sentence is beside the element it was said about, its locator, and whether `map` lists it — a heading, a caption…", "gold": true}, {"id": "CHALLENGES#284", "heading": "284. Two audio remedies said to restart with a command that restarts nothing", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** making the emulator's control port refuse, on purpose — the token in its discovery file changed. The refusal was clear, and its remedy was \"restart the emulator with `mobium boot`\"; so was the remedy for an emulator with no control port at all. `mobium boot` on an emulator that is running answers \"mobium-test was already running, as emulator-5554\" and changes nothing, so the remedy, followed, left the e…", "gold": false}], "missed": false, "facts": ["TalkBack's sentence is read from its log, which holds it only with TalkBack's Developer settings' Log output level at VERBOSE. ⟦VERBOSE ; Log output level⟧", "Mobium does not set that level itself — it is TalkBack's own preference — and refuses, naming it, while nothing is logged."], "concern": "", "check": "Claude's reading: ACCESSIBILITY.md step 2 and talkback.go's ErrTalkBackQuiet agree (remedy: Advanced settings > Developer settings > Log output level VERBOSE). The doc also warns verbose logging puts everything TalkBack says in the device log. Verified in: internal/device/talkback.go:31, internal/device/talkback.go:250."}, {"id": "g072", "kind": "fact", "question": "How can I check what TalkBack announces right after my test taps an 'Add to cart' button that updates a live region?", "tags": ["how-to", "test-author", "new since 7b590a4"], "gold": [{"id": "docs/ACCESSIBILITY.md#2-hear-the-screen-reader-appspeech-built", "heading": "2. Hear the screen reader: `app_speech` — built", "path": "docs/ACCESSIBILITY.md", "excerpt": "`mobium speech` and `app_speech` in all five clients: what the screen reader says about the element its cursor is on; with a target, the cursor put on it first; with `walk`, a move forward at a time in the screen reader's own order until it goes no further, comes back round, or `limit` moves are made. Each sentence is beside the element it was said about, its locator, and whether `map` lists it — a heading, a caption…"}], "retrieved": [{"id": "docs/ACCESSIBILITY.md#2-hear-the-screen-reader-appspeech-built", "heading": "2. Hear the screen reader: `app_speech` — built", "path": "docs/ACCESSIBILITY.md", "excerpt": "`mobium speech` and `app_speech` in all five clients: what the screen reader says about the element its cursor is on; with a target, the cursor put on it first; with `walk`, a move forward at a time in the screen reader's own order until it goes no further, comes back round, or `limit` moves are made. Each sentence is beside the element it was said about, its locator, and whether `map` lists it — a heading, a caption…", "gold": true}, {"id": "docs/ACCESSIBILITY.md#talkback-2026-10-05", "heading": "TalkBack — 2026-10-05", "path": "docs/ACCESSIBILITY.md", "excerpt": "Android's test-automation connection silenced every other accessibility service while it was open, so a read of the screen turned TalkBack off for as long as it ran. Both drivers now leave it running (CHALLENGES 208), and with TalkBack on, taps, scrolls and typing land, because Mobium's touches are injected rather than explored — the opposite of VoiceOver above. `docs/checks/screen-reader.sh` holds it. What TalkBack …", "gold": false}, {"id": "CHALLENGES#352", "heading": "352. A check's restore that failed stopped every restore after it, and TalkBack stayed on a phone", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** `speech.sh` on the Pixel 8 Pro (ACCESSIBILITY.md, step 2). TalkBack 17.1 answered the keyboard `app_speech` connects with a dialog, \"New keymap available\", which the emulator's TalkBack never raised. It sat over TalkBack's own settings, so the exit handler putting TalkBack's log output level back could not find the row, and called the check's `fail` — which exits. `lib.sh` ran each handler with `eval`, …", "gold": false}], "missed": false, "facts": ["Run `mobium speech --listen start` before the action and `mobium speech --listen stop` after it; the stop answers with every sentence said in between. ⟦--listen start ; --listen stop⟧", "It must start before the action because a live region's change was said about 0.4 seconds after the tap, before a later call could arrive. ⟦0.4 seconds⟧"], "concern": "", "check": "Claude's reading: ACCESSIBILITY.md step 2 'Listening' describes it; speech.go refuses listen together with a target or walk. On Android each sentence carries a cause (focus, announcement, change); on an iPhone VoiceOver is polled and has none. Verified in: cmd/mobium/speech.go:53, internal/agent/speech.go:39, internal/agent/speech.go:742."}, {"id": "g073", "kind": "fact", "question": "Why does `mobium assistant \"Send a message to Alex saying I'm late\"` get refused when `mobium assistant \"Open Calculator\"` works?", "tags": ["behavior", "agent-builder", "new since 7b590a4"], "gold": [{"id": "docs/ACCESSIBILITY.md#6-voice-assistants-appassistant-built-for-android-and-the-iphone", "heading": "6. Voice assistants: `app_assistant` — built for Android and the iPhone", "path": "docs/ACCESSIBILITY.md", "excerpt": "A tool that asks the platform's assistant in text and answers with what came back and what is in front afterward, for the task-based test above. Its result always says the request was typed, not spoken (`typed`). As built (`mobium assistant \"Open Calculator\" --app com.google.android.calculator`): - **Gemini and Google Assistant**: the assist key opens them; Google Assistant's Keyboard button, or Gemini's field, takes…"}], "retrieved": [{"id": "docs/ACCESSIBILITY.md#6-voice-assistants-appassistant-built-for-android-and-the-iphone", "heading": "6. Voice assistants: `app_assistant` — built for Android and the iPhone", "path": "docs/ACCESSIBILITY.md", "excerpt": "A tool that asks the platform's assistant in text and answers with what came back and what is in front afterward, for the task-based test above. Its result always says the request was typed, not spoken (`typed`). As built (`mobium assistant \"Open Calculator\" --app com.google.android.calculator`): - **Gemini and Google Assistant**: the assist key opens them; Google Assistant's Keyboard button, or Gemini's field, takes…", "gold": true}, {"id": "CHALLENGES#354", "heading": "354. Siri opened the app, and a read during the hand-off said it had not", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** `assistant.sh` on the iPhone 15 Plus (ACCESSIBILITY.md, step 6), which once in four runs reported \"Open MobiumApp did not reach dev.mobium.mobiumapp: com.apple.springboard in front\", while a request by hand and two whole runs after it reached the app. It looked like a cold Siri — a first request failing was what the simulator (351) and the emulator's Google Assistant had done — and it was not: timed by …", "gold": false}, {"id": "skills/mobile-check/SKILL.md#dialogs", "heading": "Dialogs", "path": "skills/mobile-check/SKILL.md", "excerpt": "- `mobium alert` — is a system or app dialog up, what does it say, and what are its buttons - `mobium alert accept` / `dismiss` — yes and no, on a dialog of one or two buttons: a two-button permission prompt is granted by accept and denied by dismiss, in any language. **A dialog of three or more is refused**, naming its buttons — the location prompt has two that grant — and every answer says which button it pressed. …", "gold": false}, {"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": false}], "missed": false, "facts": ["A request that acts for the device owner (call, text, message, send, email, pay, buy, order, book, post, share, delete, transfer) is refused unless the app it is for is named with --app. ⟦names the app / --app⟧"], "concern": "", "check": "Claude's reading: the doc's verb list and the code's sideEffects regex agree (code also has dial, mail, purchase, tweet, venmo, matched as the first verb after an optional greeting). With --app, Mobium reports whether that app came forward (`reached`). Verified in: internal/agent/assistant.go:41, internal/agent/assistant.go:112, cmd/mobium/assistant.go:43."}, {"id": "g074", "kind": "fact", "question": "What do I need on my Mac to record and assert the sounds my app plays on an iOS simulator in a mobium test?", "tags": ["how-to", "test-author", "new since 7b590a4"], "gold": [{"id": "docs/guides/test-runner.md#11-what-the-app-played-audio", "heading": "11. What the app played: `audio`", "path": "docs/guides/test-runner.md", "excerpt": "A capture starts as a step and is asserted at its stop: `expect` is the sounds to hear, in order, each a pitch with an optional length, and `[]` is silence. ```json {\"name\": \"the sequence is heard in order\", \"steps\": [ {\"audio\": {\"action\": \"start\"}}, {\"tap\": \"testid=audioSequence\"}, {\"wait_for\": {\"target\": \"text=finished:\", \"timeout_ms\": 10000}}, {\"audio\": {\"action\": \"stop\", \"path\": \"mobium-report/sequence.wav\", \"exp…"}], "retrieved": [{"id": "docs/guides/test-runner.md#11-what-the-app-played-audio", "heading": "11. What the app played: `audio`", "path": "docs/guides/test-runner.md", "excerpt": "A capture starts as a step and is asserted at its stop: `expect` is the sounds to hear, in order, each a pitch with an optional length, and `[]` is silence. ```json {\"name\": \"the sequence is heard in order\", \"steps\": [ {\"audio\": {\"action\": \"start\"}}, {\"tap\": \"testid=audioSequence\"}, {\"wait_for\": {\"target\": \"text=finished:\", \"timeout_ms\": 10000}}, {\"audio\": {\"action\": \"stop\", \"path\": \"mobium-report/sequence.wav\", \"exp…", "gold": true}, {"id": "docs/ROADMAP.md#under-consideration", "heading": "Under consideration", "path": "docs/ROADMAP.md", "excerpt": "- **Locators for when there is no ref** (written down 2026-10-12). A ref from `map` lasts one map, so an agent has one and a `mobium test` file does not: a hand-written test has the flat `kind=value` locators — text, label, testid, role, class, path, narrowed by `,role=` — which match one element or are refused. That is right on a form and leaves nothing durable on a list. Every Ice Cubes post has a \"…\" (CHALLENGES 2…", "gold": false}, {"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": false}], "missed": false, "facts": ["macOS's System Audio Recording must be allowed for the terminal or app that runs mobium (System Settings › Privacy & Security › Screen & System Audio Recording); without it the stop is refused, naming it. ⟦System Audio Recording⟧", "The capture is of the app alone through a process tap on the Mac, whose helper is built with Xcode's swiftc the first time (about two seconds) and kept. ⟦process tap ; swiftc⟧"], "concern": "", "check": "Claude's reading: section 11 of test-runner.md (part 2) and simaudio.go agree on the permission refusal and swiftc helper. Simulator audio is #263, after the pin. Verified in: internal/device/simaudio.go:28, internal/device/simaudio.go:54, internal/device/simaudio.go:75, internal/device/simaudio.go:246."}, {"id": "g075", "kind": "multi", "question": "I set `mobium network --proxy` to Charles on an Android emulator; plain HTTP shows up in Charles but my app's HTTPS calls don't appear decrypted. What is going on?", "tags": ["troubleshooting", "test-author", "new since 7b590a4"], "gold": [{"id": "docs/guides/network.md#5-through-a-proxy", "heading": "5. Through a proxy", "path": "docs/guides/network.md", "excerpt": "`--proxy host:port` points the device's HTTP proxy at a debugging proxy — Charles, Fiddler, mitmproxy, anything that listens on a port — so it sees what the app sends and receives. A proxy on `127.0.0.1` or `localhost` is this machine's: Mobium reverses its port with `adb reverse` before pointing the device at it, so there is no address on the network to find and no firewall in the way. Measured on the emulator on 20…"}, {"id": "docs/PROXY.md#what-a-proxy-cannot-see", "heading": "What a proxy cannot see", "path": "docs/PROXY.md", "excerpt": "Every result names which of these applies rather than reporting an empty session as a quiet app. - **Flutter ignores the system proxy.** Dart's HTTP client reads no proxy setting unless the app gives it one, so a Flutter app's traffic goes around the proxy. - **Android apps trust only system certificates since Android 7**, unless their network security configuration opts in to user ones — debug builds usually, releas…"}], "retrieved": [{"id": "docs/guides/network.md#5-through-a-proxy", "heading": "5. Through a proxy", "path": "docs/guides/network.md", "excerpt": "`--proxy host:port` points the device's HTTP proxy at a debugging proxy — Charles, Fiddler, mitmproxy, anything that listens on a port — so it sees what the app sends and receives. A proxy on `127.0.0.1` or `localhost` is this machine's: Mobium reverses its port with `adb reverse` before pointing the device at it, so there is no address on the network to find and no firewall in the way. Measured on the emulator on 20…", "gold": true}, {"id": "docs/PROXY.md#the-shape", "heading": "The shape", "path": "docs/PROXY.md", "excerpt": "Two layers, the second opt-in. - **A proxy, any proxy.** `mobium network --proxy <host:port>` points the device at a proxy and reads it back; `--no-proxy` takes it off; the end of the session puts back what was there, as every network setting is put back. A proxy's root certificate is installed where the device allows it, so HTTPS can be decrypted. This works with Charles, Fiddler, mitmproxy or anything else that lis…", "gold": false}, {"id": "docs/PROXY.md#a-proxy-between-the-app-and-its-servers", "heading": "A proxy between the app and its servers", "path": "docs/PROXY.md", "excerpt": "What it would take for Mobium to route a device's traffic through a debugging proxy, so a test can see, shape and change what an app sends and receives — and to drive Charles, as an opt-in, the way a tester drives it by hand: record a session, throttle, switch Map Local and Rewrite rules on and off. What was measured, and the plan, in the order it should be built. **Status on 2026-10-22.** Step 1 is measured (below),…", "gold": false}, {"id": "docs/PROXY.md#what-was-measured-2026-10-20", "heading": "What was measured — 2026-10-20", "path": "docs/PROXY.md", "excerpt": "Charles 5.2.1 headless on the Mac, with a configuration of its own, and the Android 15 emulator. - **The configuration file can be written, not clicked.** Charles writes only what differs from its defaults, so its element names were read from its classes: `proxyConfiguration` holds `port`, `decryptSSL`, `sslLocations` (`locationPatterns` of `locationMatch`, each a `location` and `enabled`) and `macOSXConfiguration` w…", "gold": false}], "missed": false, "facts": ["HTTPS also needs the proxy's certificate trusted on the device; the proxy setting alone does not do it. ⟦certificate trusted⟧", "Since Android 7 apps trust only system certificates unless their network security configuration opts in to user ones (debug builds usually, release builds rarely), so their HTTPS stays encrypted. ⟦Android 7 ; network security configuration⟧", "An app with certificate pinning refuses the proxy's certificate whatever store it is in. ⟦pinning⟧"], "concern": "", "check": "Claude's reading: network.md#5 says HTTPS needs the certificate and points to PROXY.md, whose 'cannot see' section gives the trust and pinning reasons. Mobium does not install the certificate yet (PROXY.md status: 'Left of step 2: the certificate'); no code installs one, so an answer claiming Mobium installs it is wrong. Verified in: internal/device/proxy.go:69, internal/agent/network.go:112."}, {"id": "g076", "kind": "multi", "question": "My test taps a button right after a voice assistant was triggered. On an iPhone the tap just takes a few seconds longer, but on Android it fails straight away with device_not_ready. Why the difference, and how do I get past it on Android?", "tags": ["behavior", "test-author", "new since 7b590a4"], "gold": [{"id": "CHALLENGES#349", "heading": "349. A tap behind Siri's panel found nothing, and said to map again", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** measuring Siri on the iPhone 15 Plus, iOS 27.0.1, for the assistive-technology plan (`docs/ACCESSIBILITY.md`), asking only \"What time is it\" and sums. Siri's panel over MobiumApp's Form Demo stayed 8.2 to 8.3 seconds, three times in three, and while it was up `current` said SpringBoard and `map` listed neither the app nor Siri's answer: WebDriverAgent reads SpringBoard then, and the app under the panel …"}, {"id": "CHALLENGES#350", "heading": "350. A tap behind Gemini's overlay found nothing, and said to map again", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** measuring Gemini for the assistive-technology plan, after Siri's panel (349). On the Pixel 8 Pro, Android 17, signed in, the assist key opens Gemini's floating overlay from the Google app (17.66; there is no Gemini app of its own); on the Android 15 emulator, signed out, the same key opens Google Assistant's panel. While either is up, UiAutomator2 reads its window alone, the app under it absent: a tap o…"}], "retrieved": [{"id": "docs/ACCESSIBILITY.md#voiceover-on-a-real-iphone-2026-10-20", "heading": "VoiceOver on a real iPhone — 2026-10-20", "path": "docs/ACCESSIBILITY.md", "excerpt": "On the iPhone 15 Plus, iOS 27.0.1, through WebDriverAgent 16.12.8 rebuilt with Xcode 27.1, called directly over HTTP. VoiceOver was off before, and read back off after every run. - **The runner has to be built with Xcode 27.** WebDriverAgent's `/wda/voiceOver/enable`, `/disable`, `/enabled`, `/move` and `/currentSpeech` reach XCUIAutomation's VoiceOver service, which Xcode 27's has and 26.6's does not. The phone's ru…", "gold": false}, {"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": false}, {"id": "CHALLENGES#348", "heading": "348. With VoiceOver on, a tap moved its cursor and was reported done", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** measuring what WebDriverAgent's VoiceOver routes give, on the iPhone 15 Plus on iOS 27.0.1, for a plan of what Mobium could do for people who use a screen reader. With VoiceOver on, a touch is not a tap: it moves VoiceOver's cursor to what it touches, as a person's single tap does, and a double tap anywhere activates what the cursor is on. So on MobiumApp `tap \"label=Pro\"` answered `tapped label=Pro` an…", "gold": false}, {"id": "CHALLENGES#112", "heading": "112. A tap on a target sliding in gave up as it arrived", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** `docs/checks/autowait.sh`, written to test auto-wait on purpose, on its first run: on the Pixel 7 AVD, a tap on the Motion Demo's honoring target straight after Replay failed with `is still moving after 2s`. The target slides in over two seconds with an ease-out, so its last pixels creep into place right up to the end, and the settle budget was two seconds. It had never failed because it never saw the m…", "gold": false}], "missed": true, "facts": ["On iOS a target behind Siri's panel waits up to twelve seconds for the panel to go, since it closes by itself about eight seconds after Siri answers; a panel that stays is refused as device_not_ready naming Siri.", "On Android, Gemini's or Google Assistant's overlay does not go by itself, so a target behind it is refused at once, naming the assistant. ⟦refused at once⟧", "Back closes the overlay with the app intact, after which the tap lands. ⟦back closes⟧"], "concern": "", "check": "Claude's reading: CHALLENGES 349 and 350 each give one platform; handlers.go siriPanelTimeout is 12s and the assistant refusal follows at 1758. Gold is CHALLENGES-only; ACCESSIBILITY.md's Gemini section mentions back closing it but not Siri's wait. Verified in: internal/agent/handlers.go:1714, internal/agent/handlers.go:1738, internal/uitree/cover.go:430."}, {"id": "g077", "kind": "multi", "question": "If a mobium test turns TalkBack on through the accessibility screen_reader setting and takes the Android emulator offline, is the emulator left that way after the run?", "tags": ["behavior", "ci-engineer", "new since 7b590a4"], "gold": [{"id": "docs/guides/network.md#4-in-a-test", "heading": "4. In a test", "path": "docs/guides/network.md", "excerpt": "`app_network` is a step like any other in a [`mobium test`](test-runner.md) file, and its answer can be expected on: ```json { \"app\": \"dev.mobium.mobiumapp\", \"beforeEach\": [ {\"name\": \"app_network\", \"arguments\": {\"reset\": true}, \"description\": \"every test starts online and unshaped, whatever the last one left\"} ], \"tests\": [ { \"name\": \"the device goes offline, and comes back\", \"steps\": [ {\"name\": \"app_network\", \"argum…"}, {"id": "docs/ACCESSIBILITY.md#5-a-screen-reader-as-a-setting-built", "heading": "5. A screen reader as a setting — built", "path": "docs/ACCESSIBILITY.md", "excerpt": "`mobium accessibility screen_reader on` — TalkBack on Android and VoiceOver on an iPhone on iOS 27 — confirmed by reading back, and put back when the session ends, as the other settings are. It makes \"run this test with the screen reader on\" a line in a test file. As built: - **Android:** TalkBack's service added to the enabled ones, the others kept, and `accessibility_enabled` on. Confirmed by Android binding TalkBa…"}], "retrieved": [{"id": "docs/ACCESSIBILITY.md#5-a-screen-reader-as-a-setting-built", "heading": "5. A screen reader as a setting — built", "path": "docs/ACCESSIBILITY.md", "excerpt": "`mobium accessibility screen_reader on` — TalkBack on Android and VoiceOver on an iPhone on iOS 27 — confirmed by reading back, and put back when the session ends, as the other settings are. It makes \"run this test with the screen reader on\" a line in a test file. As built: - **Android:** TalkBack's service added to the enabled ones, the others kept, and `accessibility_enabled` on. Confirmed by Android binding TalkBa…", "gold": true}, {"id": "docs/ACCESSIBILITY.md#talkback-2026-10-05", "heading": "TalkBack — 2026-10-05", "path": "docs/ACCESSIBILITY.md", "excerpt": "Android's test-automation connection silenced every other accessibility service while it was open, so a read of the screen turned TalkBack off for as long as it ran. Both drivers now leave it running (CHALLENGES 208), and with TalkBack on, taps, scrolls and typing land, because Mobium's touches are injected rather than explored — the opposite of VoiceOver above. `docs/checks/screen-reader.sh` holds it. What TalkBack …", "gold": false}, {"id": "docs/SETUP.md#with-a-screen-reader-on", "heading": "With a screen reader on", "path": "docs/SETUP.md", "excerpt": "Android's test-automation connection silences every other accessibility service while it is open, unless it is opened not to. So on a device with TalkBack — or VoiceView, on a Fire TV — on, a read of the screen takes the screen reader away for as long as it runs, and an app that publishes its contents only to a screen reader stops publishing them (CHALLENGES 208). Both drivers leave the screen reader running. The def…", "gold": false}, {"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": false}, {"id": "CHALLENGES#208", "heading": "208. Every read silenced the device's screen reader", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** reading Prime Video on a Fire TV, which publishes nothing but one surface to `map`, to see whether it publishes more while Amazon's screen reader, VoiceView, is on. Every read of the screen — `uiautomator dump` and the UiAutomator2 server alike — unbound VoiceView for as long as it ran: `dumpsys accessibility` listed it before the read and not during it, and touch exploration went off. Android's test-au…", "gold": false}], "missed": false, "facts": ["No for the network: a test run ends each project's session, and the end of a session puts the network back as the session found it (airplane mode off, no shaping). ⟦as the session found it⟧", "No for TalkBack: the screen_reader setting is put back when the session ends, both keys restored exactly, and accessibility_enabled put back again once TalkBack has gone. ⟦put back when the session ends ; accessibility_enabled⟧"], "concern": "", "check": "Claude's reading: network.md section 4 covers the network restore and ACCESSIBILITY.md step 5 the TalkBack undo; code restores both at session end (restoreNetwork, restoreAccessibility). network.md still recommends a beforeEach reset to keep one test's network from reaching the next within a run. Verified in: internal/agent/network.go:295, internal/agent/accessibility.go:134, internal/device/axsettings.go:716, internal/device/axsettings.go:736."}, {"id": "g078", "kind": "multi", "question": "On Android I want every run to see my app's notification permission prompt again — even after someone tapped Don't allow twice — and have the test answer it with Allow. Which Mobium commands do that?", "tags": ["how-to", "test-author"], "gold": [{"id": "skills/mobile-check/SKILL.md#permissions", "heading": "Permissions", "path": "skills/mobile-check/SKILL.md", "excerpt": "A first-launch permission dialog will stop a flow dead. Grant before you start rather than trying to tap through it: - `mobium grant com.example.shop all` — everything the app declares - `mobium grant com.example.shop camera location` — just these - `mobium revoke com.example.shop location` — test the app without it - `mobium reset-permissions com.example.shop` — that app back to prompting, \"don't ask again\" included…"}, {"id": "skills/mobile-check/SKILL.md#dialogs", "heading": "Dialogs", "path": "skills/mobile-check/SKILL.md", "excerpt": "- `mobium alert` — is a system or app dialog up, what does it say, and what are its buttons - `mobium alert accept` / `dismiss` — yes and no, on a dialog of one or two buttons: a two-button permission prompt is granted by accept and denied by dismiss, in any language. **A dialog of three or more is refused**, naming its buttons — the location prompt has two that grant — and every answer says which button it pressed. …"}], "retrieved": [{"id": "skills/mobile-check/SKILL.md#permissions", "heading": "Permissions", "path": "skills/mobile-check/SKILL.md", "excerpt": "A first-launch permission dialog will stop a flow dead. Grant before you start rather than trying to tap through it: - `mobium grant com.example.shop all` — everything the app declares - `mobium grant com.example.shop camera location` — just these - `mobium revoke com.example.shop location` — test the app without it - `mobium reset-permissions com.example.shop` — that app back to prompting, \"don't ask again\" included…", "gold": true}, {"id": "CHALLENGES#findings-that-were-not-defects", "heading": "Findings that were not defects", "path": "docs/CHALLENGES.md", "excerpt": "Worth recording because each one closed off an approach that looked obvious. - **Predictive back on Android 15 closes a React Native app.** MobiumApp built with predictive back turned on went back to closing on every back from a demo on the Android 15 AVD, `BackHandler` never called, while on Android 17 — the AVD and the Pixel 8 Pro — it went back to its home screen. React Native 0.86 registers the callback that repl…", "gold": false}, {"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": false}, {"id": "CHALLENGES#151", "heading": "151. A per-app permission reset that could not see what it failed to clear", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** running `mobium-app.sh` after `dialogs.sh` on the Pixel 7 AVD, the first time both reset MobiumApp's permissions alone. The location check failed: the app had approximate location only, and the reset had said it put every permission back to asking. Android prints a permission flag it has no name for as a number, and after a person chooses approximate location the line ends `|524288]`. The pattern read t…", "gold": false}, {"id": "CHALLENGES#328", "heading": "328. A dialog that came up mid-scroll was blamed on the list", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** turning a client script's trace back into a test (the round-trip probe, mobiumdev/mobium-roundtrip), on the Android 15 emulator. MobiumApp's Dialog Demo asks for the camera; Android's prompt comes a moment after the tap, and only while the permission is undecided. A test that declared a rule for the prompt — `when` \"take pictures\", `press` \"While using the app\" — then scrolled up to the outcome line fai…", "gold": false}], "missed": false, "facts": ["`mobium reset-permissions <app>` puts that app back to prompting, \"don't ask again\" included. ⟦reset-permissions ; ask again⟧", "`mobium alert accept` answers a two-button permission prompt with yes, granting it, in any language. ⟦alert accept⟧"], "concern": "", "check": "Claude's reading: SKILL.md's Permissions and Dialogs sections each give one half; permreset.go revokes and clears USER_SET/USER_FIXED, and alert accept presses the yes button on a dialog of two. The tool description adds that revoking a granted permission on Android stops the app — not in the gold, not needed. Verified in: internal/agent/permissions.go:350, internal/device/permreset.go:112, internal/agent/alert.go:212, internal/agent/alert.go:429."}, {"id": "g079", "kind": "unanswerable", "question": "How much does a Charles license cost if I want to use it with Mobium's proxy support?", "tags": ["test-author", "new since 7b590a4"], "gold": [], "retrieved": [{"id": "docs/PROXY.md#4-charles-as-an-opt-in", "heading": "4. Charles as an opt-in", "path": "docs/PROXY.md", "excerpt": "`--proxy charles`: headless start with a configuration Mobium writes — the macOS proxy off, the Web Interface on, Auto Save into the test's report folder — or an existing Charles found; recording, throttling and tool switches through the Web Interface, each read back from its status line; the session converted to HAR beside the test's report. Listening on every interface is said, or bound where Charles allows.", "gold": false}, {"id": "docs/PROXY.md#the-shape", "heading": "The shape", "path": "docs/PROXY.md", "excerpt": "Two layers, the second opt-in. - **A proxy, any proxy.** `mobium network --proxy <host:port>` points the device at a proxy and reads it back; `--no-proxy` takes it off; the end of the session puts back what was there, as every network setting is put back. A proxy's root certificate is installed where the device allows it, so HTTPS can be decrypted. This works with Charles, Fiddler, mitmproxy or anything else that lis…", "gold": false}, {"id": "docs/PROXY.md#a-proxy-between-the-app-and-its-servers", "heading": "A proxy between the app and its servers", "path": "docs/PROXY.md", "excerpt": "What it would take for Mobium to route a device's traffic through a debugging proxy, so a test can see, shape and change what an app sends and receives — and to drive Charles, as an opt-in, the way a tester drives it by hand: record a session, throttle, switch Map Local and Rewrite rules on and off. What was measured, and the plan, in the order it should be built. **Status on 2026-10-22.** Step 1 is measured (below),…", "gold": false}, {"id": "docs/PROXY.md#what-was-measured-2026-10-20", "heading": "What was measured — 2026-10-20", "path": "docs/PROXY.md", "excerpt": "Charles 5.2.1 headless on the Mac, with a configuration of its own, and the Android 15 emulator. - **The configuration file can be written, not clicked.** Charles writes only what differs from its defaults, so its element names were read from its classes: `proxyConfiguration` holds `port`, `decryptSSL`, `sslLocations` (`locationPatterns` of `locationMatch`, each a `location` and `enabled`) and `macOSXConfiguration` w…", "gold": false}, {"id": "docs/PROXY.md#2---proxy-on-android", "heading": "2. `--proxy` on Android", "path": "docs/PROXY.md", "excerpt": "**The setting, done 2026-10-22** (`docs/guides/network.md`, section 5): set, read back from the keys in force, taken off with `:0` and every key deleted, put back at the session's end; a loopback proxy's port reversed before the device points at it, and only Mobium's reverses removed. A reverse that was there before is left — a test caught the first version taking it as its own. `proxy.sh` fetches a port nothing on t…", "gold": false}], "missed": false, "facts": [], "concern": "", "check": "Claude's reading: searched the corpus and code for license, price and subscription: PROXY.md only says Charles is never installed or required, mitmproxy needs no license and Fiddler Everywhere is by subscription; no price is stated anywhere. Nearest sections: docs/PROXY.md#4-charles-as-an-opt-in, docs/PROXY.md#6-fiddler-and-mitmproxy."}, {"id": "g080", "kind": "unanswerable", "question": "How do I make the Android emulator drop 5% of packets with `mobium network`, to test a flaky connection?", "tags": ["test-author"], "gold": [], "retrieved": [{"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": false}, {"id": "docs/guides/network.md#4-in-a-test", "heading": "4. In a test", "path": "docs/guides/network.md", "excerpt": "`app_network` is a step like any other in a [`mobium test`](test-runner.md) file, and its answer can be expected on: ```json { \"app\": \"dev.mobium.mobiumapp\", \"beforeEach\": [ {\"name\": \"app_network\", \"arguments\": {\"reset\": true}, \"description\": \"every test starts online and unshaped, whatever the last one left\"} ], \"tests\": [ { \"name\": \"the device goes offline, and comes back\", \"steps\": [ {\"name\": \"app_network\", \"argum…", "gold": false}, {"id": "docs/guides/graybox-tutorial.md#2-it-fails", "heading": "2. It fails", "path": "docs/guides/graybox-tutorial.md", "excerpt": "``` $ mobium test FAIL [android · emulator-5554] busy.test.json › a row tapped after a quiet refresh is current (1) (6.9s) step 3 (app_wait_for): [timeout] step 3 of 3 (app_wait_for) failed: timed out after 3.003s waiting for testid=busyOutcome to contain \": current\" — its text is \"row B, generation 1: stale\"; steps 1-2 ran before it, and nothing after FAIL [android · emulator-5554] busy.test.json › a row tapped afte…", "gold": false}, {"id": "docs/guides/network.md#why-not-the-emulators-own-throttling", "heading": "Why not the emulator's own throttling", "path": "docs/guides/network.md", "excerpt": "The Android emulator's console has `network speed` and `network delay`, and they look made for this. They accept a setting and read it back — and change nothing: on emulator 37.1.11, 2MB at a 1000 kbit/s limit still arrived in 1.1 seconds where 16 were due, and a 500ms delay left a ping at 1ms. So Mobium does not use them; it shapes the traffic itself, and every figure above was measured from the traffic, not the set…", "gold": false}, {"id": "docs/guides/graybox-tutorial.md#4-turning-the-gray-box-on", "heading": "4. Turning the gray box on", "path": "docs/guides/graybox-tutorial.md", "excerpt": "One key in the test file, beside `app`: ```json { \"app\": \"dev.mobium.mobiumapp\", \"grayBox\": true, \"beforeEach\": [ ``` Each test's launch now turns the library on, and every step waits for the app to say it is idle before finding its target: ``` $ mobium test ok [android · emulator-5554] busy.test.json › a row tapped after a quiet refresh is current (1) (7s) ok [android · emulator-5554] busy.test.json › a row tapped a…", "gold": false}], "missed": false, "facts": [], "concern": "", "check": "Claude's reading: mobium network has offline/online, latency, download, upload, proxy, no-proxy and reset (cmd/mobium/network.go:71-78) and the tc shaping in device/network.go uses netem delay and token buckets only; no doc or code mentions packet loss. A retriever will bring back the slow-network and commands sections. Nearest sections: docs/guides/network.md#3-a-slow-network, docs/guides/network.md#the-commands."}, {"id": "g081", "kind": "fact", "question": "I use Claude Code. How do I give my agent Mobium's tools, and make iOS the platform it drives by default?", "tags": ["how-to", "agent-builder"], "gold": [{"id": "docs/guides/mcp.md#1-connect-it", "heading": "1. Connect it", "path": "docs/guides/mcp.md", "excerpt": "In Claude Code: ```sh claude mcp add mobium -- mobium mcp ``` With more than one device, pin one — `mobium mcp --device emulator-5554` — or let the agent pass `device` to each call. `--driver wda` makes iOS the default. Other MCP clients take the same server in their JSON configuration, under `mcpServers`: ```json { \"mcpServers\": { \"mobium\": { \"command\": \"mobium\", \"args\": [\"mcp\", \"--device\", \"emulator-5554\"] } } } ``…"}], "retrieved": [{"id": "docs/guides/mcp.md#1-connect-it", "heading": "1. Connect it", "path": "docs/guides/mcp.md", "excerpt": "In Claude Code: ```sh claude mcp add mobium -- mobium mcp ``` With more than one device, pin one — `mobium mcp --device emulator-5554` — or let the agent pass `device` to each call. `--driver wda` makes iOS the default. Other MCP clients take the same server in their JSON configuration, under `mcpServers`: ```json { \"mcpServers\": { \"mobium\": { \"command\": \"mobium\", \"args\": [\"mcp\", \"--device\", \"emulator-5554\"] } } } ``…", "gold": true}, {"id": "docs/guides/mcp.md#2-an-agent-at-work", "heading": "2. An agent at work", "path": "docs/guides/mcp.md", "excerpt": "Claude Code, non-interactively, with Mobium's server and nothing else allowed: ```sh claude -p \"Use the mobium tools. On the Android emulator, open the app dev.mobium.mobiumapp, go to its Login Demo, sign in with username mobium and password wrongpass1, and tell me exactly what the app says. Keep it short.\" \\ --mcp-config mobium.json --strict-mcp-config --allowedTools mcp__mobium ``` The calls it made, in order, each…", "gold": false}, {"id": "docs/guides/mcp.md#mcp-mobium-as-an-agents-tools", "heading": "MCP: Mobium as an agent's tools", "path": "docs/guides/mcp.md", "excerpt": "`mobium mcp` serves every one of Mobium's tools over the Model Context Protocol, on stdio, so an agent — Claude Code, or any MCP client — drives devices with the same tools the command line and the language clients use. This guide is how to connect one, what it sees, and how its answers and failures come back. Everything below is what ran on 2026-09-28 against [MobiumApp](https://github.com/mobiumdev/mobium-app) on a…", "gold": false}, {"id": "docs/quickstart/mcp.md#1-what-you-need", "heading": "1. What you need", "path": "docs/quickstart/mcp.md", "excerpt": "An agent that speaks MCP — Claude Code, or any MCP client — to drive devices with Mobium's tools. The program on this page plays the client's part by hand, to show exactly what goes over the wire; it needs Python 3.9 or later and nothing beyond its standard library.", "gold": false}, {"id": "CLAUDE.md#rules", "heading": "Rules", "path": "CLAUDE.md", "excerpt": "- Run `make ci` before committing. After adding a tool, a flag or a schema property, run `make api flags` and add it everywhere — CLI, MCP schema, all five clients (CONTRIBUTING.md, \"Adding a tool, a flag or an error\") - Every error has a code: `mobiumerr.New(mobiumerr.<Code>, ...)`, never a bare `fmt.Errorf` - The CLI implements no behavior; it calls a tool. Behavior lives in `internal/agent` - After rebuilding, `mo…", "gold": false}], "missed": false, "facts": ["Register the server with `claude mcp add mobium -- mobium mcp`. ⟦claude mcp add mobium⟧", "Passing `--driver wda` to `mobium mcp` makes iOS the default. ⟦--driver wda⟧"], "concern": "", "check": "Claude's reading: the command and the --driver flag are in the MCP guide's section 1; mcp_cmd.go's help text names the same registration, and it passes the global --driver to SetBackend, so `mobium mcp --driver wda` sets the server's default backend. Verified in: cmd/mobium/mcp_cmd.go:17, cmd/mobium/mcp_cmd.go:29."}, {"id": "g082", "kind": "fact", "question": "I put Mobium into my desktop MCP client's mcpServers config with \"command\": \"mobium\", but the server never starts, even though mobium runs fine in my terminal. What is wrong?", "tags": ["troubleshooting", "agent-builder"], "gold": [{"id": "docs/guides/mcp.md#1-connect-it", "heading": "1. Connect it", "path": "docs/guides/mcp.md", "excerpt": "In Claude Code: ```sh claude mcp add mobium -- mobium mcp ``` With more than one device, pin one — `mobium mcp --device emulator-5554` — or let the agent pass `device` to each call. `--driver wda` makes iOS the default. Other MCP clients take the same server in their JSON configuration, under `mcpServers`: ```json { \"mcpServers\": { \"mobium\": { \"command\": \"mobium\", \"args\": [\"mcp\", \"--device\", \"emulator-5554\"] } } } ``…"}], "retrieved": [{"id": "docs/guides/mcp.md#1-connect-it", "heading": "1. Connect it", "path": "docs/guides/mcp.md", "excerpt": "In Claude Code: ```sh claude mcp add mobium -- mobium mcp ``` With more than one device, pin one — `mobium mcp --device emulator-5554` — or let the agent pass `device` to each call. `--driver wda` makes iOS the default. Other MCP clients take the same server in their JSON configuration, under `mcpServers`: ```json { \"mcpServers\": { \"mobium\": { \"command\": \"mobium\", \"args\": [\"mcp\", \"--device\", \"emulator-5554\"] } } } ``…", "gold": true}, {"id": "docs/quickstart/mcp.md#2-connect-an-agent", "heading": "2. Connect an agent", "path": "docs/quickstart/mcp.md", "excerpt": "`mobium mcp` is an MCP server on stdio, so there is nothing to install beyond `mobium` itself. Register it with your agent — in Claude Code: ```sh claude mcp add mobium -- mobium mcp ``` Other clients take the same command in their `mcpServers` configuration; [the MCP guide](../guides/mcp.md#1-connect-it) has the JSON. From then on, ask the agent for what you want done on the device, and it calls the tools below itse…", "gold": false}, {"id": "packaging/mcp/README.md#mcp-packaging", "heading": "MCP packaging", "path": "packaging/mcp/README.md", "excerpt": "What puts Mobium's MCP server — `mobium mcp` — into the [MCP Registry](https://registry.modelcontextprotocol.io) and into clients that install MCP bundles, such as Claude Desktop. | File | What it is | | --- | --- | | [manifest.json](manifest.json) | The MCPB manifest, a template: the version and the tool list are filled in at build time | | [launcher.sh](launcher.sh) | The bundle's entry point, `server/mobium`: a bu…", "gold": false}, {"id": "docs/guides/mcp.md#6-sessions-and-sharing-a-device", "heading": "6. Sessions, and sharing a device", "path": "docs/guides/mcp.md", "excerpt": "`mobium mcp` runs the tools in its own process: the editor's MCP connection is the long-lived thing, and it holds its own device sessions, with the agent's refs. The command line and the language clients share a daemon instead. A device's automation server holds one session at a time, so an agent's MCP server and a `mobium` command driving **the same device at the same time** take it from each other — each recovers, …", "gold": false}, {"id": "docs/guides/mcp.md#mcp-mobium-as-an-agents-tools", "heading": "MCP: Mobium as an agent's tools", "path": "docs/guides/mcp.md", "excerpt": "`mobium mcp` serves every one of Mobium's tools over the Model Context Protocol, on stdio, so an agent — Claude Code, or any MCP client — drives devices with the same tools the command line and the language clients use. This guide is how to connect one, what it sees, and how its answers and failures come back. Everything below is what ran on 2026-09-28 against [MobiumApp](https://github.com/mobiumdev/mobium-app) on a…", "gold": false}], "missed": false, "facts": ["The client starts the server with its own PATH, so `command` needs mobium's full path when mobium is not on the PATH the client starts with. ⟦full path⟧"], "concern": "", "check": "Claude's reading: the guide's section 1 says `command` needs mobium's full path if it is not on the PATH the client starts with; nothing in Mobium's code is involved, since the client launches the process, so verified_in only points at the command being launched. Verified in: cmd/mobium/mcp_cmd.go:11."}, {"id": "g083", "kind": "fact", "question": "When one of Mobium's tools fails over MCP, does my client get a JSON-RPC error, and what in the reply should my agent decide on?", "tags": ["behavior", "agent-builder"], "gold": [{"id": "docs/guides/mcp.md#5-failures", "heading": "5. Failures", "path": "docs/guides/mcp.md", "excerpt": "A tool that fails answers with `isError: true` — never a protocol error, which is kept for a malformed request — and the failure as data: a code, the message, a remedy that works, and whether retrying could help: ``` >>> {\"jsonrpc\": \"2.0\", \"id\": 5, \"method\": \"tools/call\", \"params\": {\"name\": \"app_tap\", \"arguments\": {\"target\": \"testid=noSuchButton\"}}} <<< { \"jsonrpc\": \"2.0\", \"id\": 5, \"result\": { \"content\": [ { \"type\": …"}], "retrieved": [{"id": "CHALLENGES#121", "heading": "121. The clients hung, crashed and leaked on an ordinary bad day", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** driving each client's real connection against a stand-in `mobium pipe` on a real subprocess, before the .NET, Java, Python and JavaScript clients went public, and then checking the one case that mattered most against the real pipe. Nothing here needed a device; all of it would have reached users. Five clients, written against one protocol, each had its own subset:", "gold": false}, {"id": "docs/quickstart/mcp.md#notes", "heading": "Notes", "path": "docs/quickstart/mcp.md", "excerpt": "- The server holds one session per device for as long as it runs. An agent's client ends it by closing the server's stdin when the agent exits, which also puts back anything the session changed. - A tool that fails answers with `isError` and a code in `structuredContent`, never a JSON-RPC error: the agent reads the explanation and decides what to do. [The MCP guide](../guides/mcp.md) shows an agent at work, the hands…", "gold": false}, {"id": "docs/guides/mcp.md#mcp-mobium-as-an-agents-tools", "heading": "MCP: Mobium as an agent's tools", "path": "docs/guides/mcp.md", "excerpt": "`mobium mcp` serves every one of Mobium's tools over the Model Context Protocol, on stdio, so an agent — Claude Code, or any MCP client — drives devices with the same tools the command line and the language clients use. This guide is how to connect one, what it sees, and how its answers and failures come back. Everything below is what ran on 2026-09-28 against [MobiumApp](https://github.com/mobiumdev/mobium-app) on a…", "gold": false}, {"id": "CHALLENGES#91", "heading": "91. Every client raised its base exception for every failure", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** `docs/checks/clients.sh`, the first end-to-end run of all five clients against a device, written for the release checklist on 2026-09-25. Its one deliberate failure — a tap on a locator that matches nothing — came back as `MobiumError`, `MobiumException` and a bare Go error in all five, never as the `no_such_element` type each client maps that code to. The code never reached them. Clients spawn `mobium …", "gold": false}, {"id": "CONTRIBUTING.md#adding-a-tool-a-flag-or-an-error", "heading": "Adding a tool, a flag or an error", "path": "CONTRIBUTING.md", "excerpt": "- **A tool** goes everywhere at once: the CLI, the MCP schema and all five clients. `internal/apisurface` fails the build otherwise; a deliberate gap is declared there with a reason. Run `make api` to regenerate [docs/API.md](docs/API.md). - **A flag or schema property** is the same rule one level down: every argument a tool declares must be settable from the CLI, and every key a command sends must be one the tool de…", "gold": false}], "missed": true, "facts": ["A failed tool answers with a normal result marked `isError: true`, never a protocol error, which is kept for a malformed request. ⟦isError⟧", "The structured half carries a code, the message, a remedy and whether retrying could help; the agent should decide by the code and read the remedy. ⟦retryable⟧"], "concern": "", "check": "Claude's reading: server.go's CallTool returns ErrorResult (isError true, structuredContent from mobiumerr.PayloadOf) for any tool failure and a JSON-RPC error only for unparseable params, as the guide's section 5 says. Verified in: internal/agent/server.go:163, internal/agent/server.go:188, internal/mobiumerr/mobiumerr.go:183."}, {"id": "g084", "kind": "fact", "question": "Why does `mobium mcp` run the tools inside its own process instead of going through the daemon the way the language clients do?", "tags": ["rationale", "contributor"], "gold": [{"id": "docs/ARCHITECTURE.md#the-whole-system", "heading": "The whole system", "path": "docs/ARCHITECTURE.md", "excerpt": "```mermaid flowchart TB subgraph doors[\"Front doors\"] cli[\"CLI<br/>mobium map, mobium tap @e5\"] clients[\"Language clients<br/>Python · JavaScript · Go · Java · .NET\"] mcp[\"MCP client<br/>an agent\"] test[\"mobium test<br/>JSON test files · --ui page\"] inspect[\"mobium inspect<br/>a page showing the screen\"] end pipe[\"mobium pipe<br/>JSON-RPC on stdio\"] mcpcmd[\"mobium mcp<br/>MCP on stdio, in-process\"] daemon[\"Daemon<br/…"}], "retrieved": [{"id": "docs/guides/mcp.md#6-sessions-and-sharing-a-device", "heading": "6. Sessions, and sharing a device", "path": "docs/guides/mcp.md", "excerpt": "`mobium mcp` runs the tools in its own process: the editor's MCP connection is the long-lived thing, and it holds its own device sessions, with the agent's refs. The command line and the language clients share a daemon instead. A device's automation server holds one session at a time, so an agent's MCP server and a `mobium` command driving **the same device at the same time** take it from each other — each recovers, …", "gold": false}, {"id": "docs/guides/mcp.md#which-front-door", "heading": "Which front door", "path": "docs/guides/mcp.md", "excerpt": "| | Command line | MCP | Language clients | | --- | --- | --- | --- | | For | a person, a shell script, CI | an agent | a program or a test suite | | Runs as | `mobium <command>` through the daemon | `mobium mcp`, in its own process | `mobium pipe`, spawned by the client, through the daemon | | Answers | text, or `--json` | `content` and `structuredContent` | typed results and exceptions | The same 71 tools behind ea…", "gold": false}, {"id": "CHALLENGES#7", "heading": "7. Client sessions collided with the CLI's", "path": "docs/CHALLENGES.md", "excerpt": "**Step 6. Found by:** running the first Python client against a live device. The client spawned `mobium mcp`, which runs handlers in-process. That started a second UiAutomator2 instrumentation on the same device, took over the device-side server, and left the daemon holding a session id the server no longer knew. Both UiAutomator2 and WebDriverAgent hold exactly **one session per device**. Fixed by adding `mobium pip…", "gold": false}, {"id": "docs/guides/cli.md#the-command-line", "heading": "The command line", "path": "docs/guides/cli.md", "excerpt": "`mobium` is one binary, and every command is one call to one of Mobium's tools — the same tools an MCP client and the five language clients call, so the command line cannot do something they cannot. This guide is how the commands fit together: the loop, sessions and the daemon, the flags every command takes, reading answers from a script, and exit statuses. Every command and every line of output below is what `mobium…", "gold": false}, {"id": "docs/guides/mcp.md#mcp-mobium-as-an-agents-tools", "heading": "MCP: Mobium as an agent's tools", "path": "docs/guides/mcp.md", "excerpt": "`mobium mcp` serves every one of Mobium's tools over the Model Context Protocol, on stdio, so an agent — Claude Code, or any MCP client — drives devices with the same tools the command line and the language clients use. This guide is how to connect one, what it sees, and how its answers and failures come back. Everything below is what ran on 2026-09-28 against [MobiumApp](https://github.com/mobiumdev/mobium-app) on a…", "gold": false}], "missed": true, "facts": ["The MCP server runs the tool layer in-process because an MCP client already holds a long-lived connection of its own. ⟦long-lived connection⟧", "The clients go through the daemon (via `mobium pipe`) because a device-side server holds one session at a time, so a client with its own session would invalidate the CLI's. ⟦one session at a time ; mobium pipe⟧"], "concern": "", "check": "Claude's reading: both reasons are the bullets under ARCHITECTURE's diagram (part ~2 of the section); mcp_cmd.go's comment gives the same reason for running agent.NewServer in-process. Verified in: cmd/mobium/mcp_cmd.go:22, cmd/mobium/pipe.go."}, {"id": "g085", "kind": "fact", "question": "What happens if my agent's MCP server and a `mobium` command in my terminal drive the same phone at the same time?", "tags": ["behavior", "agent-builder"], "gold": [{"id": "docs/guides/mcp.md#6-sessions-and-sharing-a-device", "heading": "6. Sessions, and sharing a device", "path": "docs/guides/mcp.md", "excerpt": "`mobium mcp` runs the tools in its own process: the editor's MCP connection is the long-lived thing, and it holds its own device sessions, with the agent's refs. The command line and the language clients share a daemon instead. A device's automation server holds one session at a time, so an agent's MCP server and a `mobium` command driving **the same device at the same time** take it from each other — each recovers, …"}], "retrieved": [{"id": "docs/guides/mcp.md#6-sessions-and-sharing-a-device", "heading": "6. Sessions, and sharing a device", "path": "docs/guides/mcp.md", "excerpt": "`mobium mcp` runs the tools in its own process: the editor's MCP connection is the long-lived thing, and it holds its own device sessions, with the agent's refs. The command line and the language clients share a daemon instead. A device's automation server holds one session at a time, so an agent's MCP server and a `mobium` command driving **the same device at the same time** take it from each other — each recovers, …", "gold": true}, {"id": "docs/quickstart/mcp.md#2-connect-an-agent", "heading": "2. Connect an agent", "path": "docs/quickstart/mcp.md", "excerpt": "`mobium mcp` is an MCP server on stdio, so there is nothing to install beyond `mobium` itself. Register it with your agent — in Claude Code: ```sh claude mcp add mobium -- mobium mcp ``` Other clients take the same command in their `mcpServers` configuration; [the MCP guide](../guides/mcp.md#1-connect-it) has the JSON. From then on, ask the agent for what you want done on the device, and it calls the tools below itse…", "gold": false}, {"id": "docs/guides/mcp.md#1-connect-it", "heading": "1. Connect it", "path": "docs/guides/mcp.md", "excerpt": "In Claude Code: ```sh claude mcp add mobium -- mobium mcp ``` With more than one device, pin one — `mobium mcp --device emulator-5554` — or let the agent pass `device` to each call. `--driver wda` makes iOS the default. Other MCP clients take the same server in their JSON configuration, under `mcpServers`: ```json { \"mcpServers\": { \"mobium\": { \"command\": \"mobium\", \"args\": [\"mcp\", \"--device\", \"emulator-5554\"] } } } ``…", "gold": false}, {"id": "docs/guides/mcp.md#mcp-mobium-as-an-agents-tools", "heading": "MCP: Mobium as an agent's tools", "path": "docs/guides/mcp.md", "excerpt": "`mobium mcp` serves every one of Mobium's tools over the Model Context Protocol, on stdio, so an agent — Claude Code, or any MCP client — drives devices with the same tools the command line and the language clients use. This guide is how to connect one, what it sees, and how its answers and failures come back. Everything below is what ran on 2026-09-28 against [MobiumApp](https://github.com/mobiumdev/mobium-app) on a…", "gold": false}, {"id": "README.md#front-doors", "heading": "Front doors", "path": "README.md", "excerpt": "The CLI does not implement behavior. It calls the same tools an MCP client calls, so the surfaces cannot drift: ```mermaid flowchart LR cli[\"CLI\"] --> daemon clients[\"Python · JS · Go · Java · .NET\"] --> pipe[\"mobium pipe\"] --> daemon mcp[\"MCP client\"] --> mcpcmd[\"mobium mcp\"] daemon[\"daemon<br/>sessions, @refs\"] --> agent mcpcmd --> agent[\"internal/agent<br/>every tool, written once\"] agent --> driver[\"internal/mobi…", "gold": false}], "missed": false, "facts": ["A device's automation server holds one session at a time, so the two take it from each other; each recovers, but neither is reliable. ⟦one session at a time⟧", "Give each its own device, or take turns. ⟦take turns⟧"], "concern": "", "check": "Claude's reading: section 6 of the MCP guide states this; the code confirms the MCP server keeps its own sessions in-process (mcp_cmd.go) while the CLI's are in the daemon, so nothing arbitrates between them. The collision itself is a device-side fact I did not reproduce. Verified in: cmd/mobium/mcp_cmd.go:22, internal/agent/session.go."}, {"id": "g086", "kind": "fact", "question": "I wrote a driver script, and `mobium map --driver mything` answers that there is no built-in backend by that name. How does Mobium look for third-party drivers?", "tags": ["troubleshooting", "driver-author"], "gold": [{"id": "examples/drivers/PROTOCOL.md#discovery", "heading": "Discovery", "path": "examples/drivers/PROTOCOL.md", "excerpt": "`--driver roku` looks for a built-in backend of that name first, then for an executable named **`mobium-driver-roku`** on `PATH`. Git and kubectl both do this, it needs no registry, no config file and no install step beyond putting a file somewhere, and it makes the failure legible: \"no built-in backend named roku, and no `mobium-driver-roku` on your PATH\". `MOBIUM_DRIVER_<NAME>` overrides the path for one backend, w…"}], "retrieved": [{"id": "examples/drivers/README.md#the-smallest-driver-that-works", "heading": "The smallest driver that works", "path": "examples/drivers/README.md", "excerpt": "Three methods are mandatory: `snapshot`, `screenshot` and `tap`. Plus `initialize`, which says who you are. ```python #!/usr/bin/env python3 import json, sys def handle(method, params): if method == \"initialize\": return {\"protocolVersion\": \"1\", \"name\": \"my-thing\", \"capabilities\": []} if method == \"snapshot\": return {\"class\": \"Screen\", \"bounds\": [0, 0, 400, 800], \"children\": [ {\"class\": \"Button\", \"text\": \"Go\", \"bounds…", "gold": false}, {"id": "examples/drivers/PROTOCOL.md#discovery", "heading": "Discovery", "path": "examples/drivers/PROTOCOL.md", "excerpt": "`--driver roku` looks for a built-in backend of that name first, then for an executable named **`mobium-driver-roku`** on `PATH`. Git and kubectl both do this, it needs no registry, no config file and no install step beyond putting a file somewhere, and it makes the failure legible: \"no built-in backend named roku, and no `mobium-driver-roku` on your PATH\". `MOBIUM_DRIVER_<NAME>` overrides the path for one backend, w…", "gold": true}, {"id": "examples/drivers/README.md#developing-without-installing", "heading": "Developing without installing", "path": "examples/drivers/README.md", "excerpt": "``` MOBIUM_DRIVER_MYTHING=./mobium-driver-mything mobium map --driver mything ``` `mobium doctor` lists every `mobium-driver-*` it can find on your `PATH`, so \"did it install\" has an answer that is not \"run it and see\".", "gold": false}, {"id": "examples/drivers/README.md#the-reference-driver", "heading": "The reference driver", "path": "examples/drivers/README.md", "excerpt": "[`mobium-driver-adb`](mobium-driver-adb) is a complete, working driver in ~350 lines of Python with no dependencies. It drives Android through plain `adb` — deliberately the same ground Mobium's own `--driver uiautomator` covers, so its output can be diffed against a known-good implementation on the same screen. That diff is how you tell a driver that works from one that returns something plausible, and it is exactly…", "gold": false}, {"id": "README.md#drivers-for-other-platforms", "heading": "Drivers for other platforms", "path": "README.md", "excerpt": "Anything Mobium does not drive itself — a TV, a desktop app, a platform nobody has written yet — is a **driver**: an executable named `mobium-driver-<name>` on your `PATH`, in any language, speaking JSON-RPC on stdio. ```sh mobium map --driver roku ``` A driver needs three methods to be useful — `snapshot`, `screenshot` and `tap` — and inherits locators, `@ref`s, waiting, scrolling, the CLI, MCP and all five clients.…", "gold": false}], "missed": false, "facts": ["`--driver mything` looks for a built-in backend first, then for an executable named `mobium-driver-mything` on PATH. ⟦mobium-driver-⟧", "`MOBIUM_DRIVER_<NAME>` overrides the path for one backend, for developing a driver without installing it. ⟦MOBIUM_DRIVER_⟧", "`mobium doctor` lists the drivers it can find. ⟦mobium doctor⟧"], "concern": "internal/mobiumdriver/external.go:116-121: the refusal says that after setting MOBIUM_DRIVER_<NAME> you must run `mobium daemon stop`, because the daemon is what looks for drivers and a running one keeps the environment it started with. Neither PROTOCOL.md#discovery nor README.md#developing-without-installing says so, so following the docs with a daemon already running still fails.", "check": "Claude's reading: FindDriver checks MOBIUM_DRIVER_<NAME> (dashes and dots become underscores), then exec.LookPath(\"mobium-driver-\"+name), and refuses with the message the docs quote. See the concern: the code's refusal adds a step the docs leave out. Verified in: internal/mobiumdriver/external.go:102, internal/mobiumdriver/external.go:106, internal/mobiumdriver/external.go:114."}, {"id": "g087", "kind": "fact", "question": "My third-party driver leaves `text` out of its capabilities. What happens when someone runs `mobium type` against it?", "tags": ["behavior", "driver-author"], "gold": [{"id": "examples/drivers/PROTOCOL.md#handshake", "heading": "Handshake", "path": "examples/drivers/PROTOCOL.md", "excerpt": "Mobium calls `initialize` first and sends nothing else until it answers: ```json {\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\", \"params\":{\"protocolVersion\":\"1\",\"device\":\"<the --device string, verbatim>\"}} ``` The driver replies with its name and what it can do: ```json {\"jsonrpc\":\"2.0\",\"id\":1,\"result\":{ \"protocolVersion\":\"1\", \"name\":\"roku/ecp\", \"capabilities\":[\"gestures\",\"text\",\"apps\",\"appearance\",\"inventory\", \"permi…"}], "retrieved": [{"id": "skills/mobile-check/SKILL.md#choosing-a-device-or-backend", "heading": "Choosing a device or backend", "path": "skills/mobile-check/SKILL.md", "excerpt": "- `--device <serial>` — when more than one device is running - `--driver uiautomator` — Android without installing anything (slower, and it cannot type) - `--driver wda` — iOS simulators and iPhones - `--driver <anything else>` — a third-party driver the user installed, as an executable named `mobium-driver-<name>`. `mobium doctor` lists the ones it can find. Such a driver may not support everything: if it refuses so…", "gold": false}, {"id": "docs/RELEASE-CHECKLIST.md#third-party-drivers", "heading": "Third-party drivers", "path": "docs/RELEASE-CHECKLIST.md", "excerpt": "The extension point is a published protocol, so a break here is a break in somebody else's code that we cannot see. - [ ] `examples/drivers/mobium-driver-adb` still imports nothing but the Python standard library. If a reference driver needs anything from this repository, the extension point is not open - [ ] `examples/drivers/PROTOCOL.md`'s method table matches what `internal/mobiumdriver` actually sends, field for …", "gold": false}, {"id": "examples/drivers/README.md#the-reference-driver", "heading": "The reference driver", "path": "examples/drivers/README.md", "excerpt": "[`mobium-driver-adb`](mobium-driver-adb) is a complete, working driver in ~350 lines of Python with no dependencies. It drives Android through plain `adb` — deliberately the same ground Mobium's own `--driver uiautomator` covers, so its output can be diffed against a known-good implementation on the same screen. That diff is how you tell a driver that works from one that returns something plausible, and it is exactly…", "gold": false}, {"id": "examples/drivers/PROTOCOL.md#handshake", "heading": "Handshake", "path": "examples/drivers/PROTOCOL.md", "excerpt": "Mobium calls `initialize` first and sends nothing else until it answers: ```json {\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\", \"params\":{\"protocolVersion\":\"1\",\"device\":\"<the --device string, verbatim>\"}} ``` The driver replies with its name and what it can do: ```json {\"jsonrpc\":\"2.0\",\"id\":1,\"result\":{ \"protocolVersion\":\"1\", \"name\":\"roku/ecp\", \"capabilities\":[\"gestures\",\"text\",\"apps\",\"appearance\",\"inventory\", \"permi…", "gold": true}, {"id": "CHALLENGES#92", "heading": "92. The advice for a missing driver could not work with a daemon running", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** `docs/checks/external-driver.sh` in the release batch, which failed at once with \"no mobium-driver-adb on your PATH\" — while exporting `MOBIUM_DRIVER_ADB` three lines earlier. The daemon looks a driver up, in the environment it started with; one left running by an earlier command never sees a variable set afterwards. The check had always been run first, on a fresh daemon. And the product's error gave th…", "gold": false}], "missed": false, "facts": ["Mobium wires up only the capabilities a driver names, so it never asks the driver to type. ⟦only the capabilities named⟧", "The command is refused and the user is told to use a different backend, rather than the driver being asked and failing. ⟦different backend⟧"], "concern": "internal/agent/handlers.go:2214: the refusal for any backend without text entry says \"use the uiautomator2 backend (`--driver uiautomator2`, the default)\" — a remedy that cannot work for a non-Android driver such as a TV, against CONTRIBUTING's rule that a remedy must be one that can work.", "check": "Claude's reading: external.go keeps only known advertised capabilities, AsTextEntry requires CapText, and handlers.go refuses with code unsupported. The refusal's wording is worth a look (concern). Verified in: internal/mobiumdriver/external.go:202, internal/mobiumdriver/capability.go:106, internal/agent/handlers.go:2214."}, {"id": "g088", "kind": "fact", "question": "My driver for a TV with a D-pad marks the node holding input focus as `focused` in its snapshot. What does Mobium do with it?", "tags": ["behavior", "driver-author", "new since 7b590a4"], "gold": [{"id": "examples/drivers/PROTOCOL.md#the-hierarchy", "heading": "The hierarchy", "path": "examples/drivers/PROTOCOL.md", "excerpt": "`snapshot` returns one node, recursively, in the shape of `uitree.WireNode` ([../../internal/uitree/wire.go](../../internal/uitree/wire.go)): ```json {\"class\":\"Button\",\"text\":\"7\",\"testid\":\"com.example:id/digit_7\", \"bounds\":[0,0,100,50],\"clickable\":true, \"children\":[]} ``` Every field is optional except `bounds`, which is `[x1,y1,x2,y2]`. The driver sends **only what the platform told it**. `depth`, `index`, `path` an…"}], "retrieved": [{"id": "CHALLENGES#355", "heading": "355. A TV's map did not say which tile select would press", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** the Fire TV and Apple TV entries in ROADMAP, then MobiumTV's home screen on the Android TV emulator and the Apple TV simulator. A TV is driven by focus: the D-pad moves it and select presses what has it. Both platforms report it on the node — Android's `focused`, and iOS's since 297 — and a D-pad press already read it back (\"focus moved to Focus or Select\"). But `map` built its entries without it, so af…", "gold": false}, {"id": "examples/drivers/PROTOCOL.md#the-hierarchy", "heading": "The hierarchy", "path": "examples/drivers/PROTOCOL.md", "excerpt": "`snapshot` returns one node, recursively, in the shape of `uitree.WireNode` ([../../internal/uitree/wire.go](../../internal/uitree/wire.go)): ```json {\"class\":\"Button\",\"text\":\"7\",\"testid\":\"com.example:id/digit_7\", \"bounds\":[0,0,100,50],\"clickable\":true, \"children\":[]} ``` Every field is optional except `bounds`, which is `[x1,y1,x2,y2]`. The driver sends **only what the platform told it**. `depth`, `index`, `path` an…", "gold": true}, {"id": "docs/ROADMAP.md#under-consideration", "heading": "Under consideration", "path": "docs/ROADMAP.md", "excerpt": "- **Locators for when there is no ref** (written down 2026-10-12). A ref from `map` lasts one map, so an agent has one and a `mobium test` file does not: a hand-written test has the flat `kind=value` locators — text, label, testid, role, class, path, narrowed by `,role=` — which match one element or are refused. That is right on a form and leaves nothing durable on a list. Every Ice Cubes post has a \"…\" (CHALLENGES 2…", "gold": false}, {"id": "CHALLENGES#297", "heading": "297. An Apple TV's focus was in the tree and never read", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** the same session. WebDriverAgent marks the element with focus `focused=\"true\"` on tvOS, and the iOS parser read every attribute but that one, so every D-pad press answered \"nothing on screen reports focus, so where it went cannot be read\" while the app's own line said `Focused: Tile 1`. The parser now reads it, and a press reports where focus went, as on a Fire TV. The other readers of `Focused` ask And…", "gold": false}], "missed": false, "facts": ["`map` shows the node's state as `(button, focused)`. ⟦(button, focused)⟧", "On a device with a D-pad it is what select will press and how a D-pad press is read back, so a TV driver should send it. ⟦D-pad⟧"], "concern": "", "check": "Claude's reading: WireNode.Focused is carried into the node (wire.go) and map appends the \"focused\" state (snapshot.go). The paragraph was added to PROTOCOL.md after 7b590a4 (#259, CHALLENGES 355). Verified in: internal/uitree/wire.go:43, internal/uitree/wire.go:133, internal/uitree/snapshot.go:80, internal/agent/mapdiff.go:184."}, {"id": "g089", "kind": "fact", "question": "How do I make Mobium find my Python driver script on Windows, where there is no shebang line or execute bit?", "tags": ["how-to", "driver-author", "new since 7b590a4"], "gold": [{"id": "examples/drivers/README.md#the-smallest-driver-that-works", "heading": "The smallest driver that works", "path": "examples/drivers/README.md", "excerpt": "Three methods are mandatory: `snapshot`, `screenshot` and `tap`. Plus `initialize`, which says who you are. ```python #!/usr/bin/env python3 import json, sys def handle(method, params): if method == \"initialize\": return {\"protocolVersion\": \"1\", \"name\": \"my-thing\", \"capabilities\": []} if method == \"snapshot\": return {\"class\": \"Screen\", \"bounds\": [0, 0, 400, 800], \"children\": [ {\"class\": \"Button\", \"text\": \"Go\", \"bounds…"}], "retrieved": [{"id": "examples/drivers/README.md#the-smallest-driver-that-works", "heading": "The smallest driver that works", "path": "examples/drivers/README.md", "excerpt": "Three methods are mandatory: `snapshot`, `screenshot` and `tap`. Plus `initialize`, which says who you are. ```python #!/usr/bin/env python3 import json, sys def handle(method, params): if method == \"initialize\": return {\"protocolVersion\": \"1\", \"name\": \"my-thing\", \"capabilities\": []} if method == \"snapshot\": return {\"class\": \"Screen\", \"bounds\": [0, 0, 400, 800], \"children\": [ {\"class\": \"Button\", \"text\": \"Go\", \"bounds…", "gold": true}, {"id": "docs/WINDOWS.md#the-execcommand-audit-2026-09-25", "heading": "The `exec.Command` audit — 2026-09-25", "path": "docs/WINDOWS.md", "excerpt": "Every `exec.Command`, `exec.CommandContext` and `exec.LookPath` outside the clients was read for `.exe` resolution and for paths with spaces. Unverified, like everything else here. - **Spaces and backslashes in arguments are fine.** Go builds the Windows command line with `syscall.EscapeArg`, which quotes for the parsing `adb.exe` does, and nothing is run through `cmd.exe`, so `%` and `^` mean nothing. `adb shell` ar…", "gold": false}, {"id": "examples/drivers/README.md#the-reference-driver", "heading": "The reference driver", "path": "examples/drivers/README.md", "excerpt": "[`mobium-driver-adb`](mobium-driver-adb) is a complete, working driver in ~350 lines of Python with no dependencies. It drives Android through plain `adb` — deliberately the same ground Mobium's own `--driver uiautomator` covers, so its output can be diffed against a known-good implementation on the same screen. That diff is how you tell a driver that works from one that returns something plausible, and it is exactly…", "gold": false}, {"id": "README.md#drivers-for-other-platforms", "heading": "Drivers for other platforms", "path": "README.md", "excerpt": "Anything Mobium does not drive itself — a TV, a desktop app, a platform nobody has written yet — is a **driver**: an executable named `mobium-driver-<name>` on your `PATH`, in any language, speaking JSON-RPC on stdio. ```sh mobium map --driver roku ``` A driver needs three methods to be useful — `snapshot`, `screenshot` and `tap` — and inherits locators, `@ref`s, waiting, scrolling, the CLI, MCP and all five clients.…", "gold": false}], "missed": false, "facts": ["Name it `mobium-driver-mything.exe`, or give the script a wrapper named `mobium-driver-mything.cmd` containing `@python \"%~dp0mobium-driver-mything.py\"`. ⟦mobium-driver-mything.cmd⟧", "Anything listed in PATHEXT is found the same way, and `mobium doctor` reports the driver as `mything` either way. ⟦PATHEXT⟧", "It was run on Windows 11 on 2026-10-22: the reference driver through such a wrapper mapped the same 11 elements as the built-in backend. ⟦Windows 11⟧"], "concern": "", "check": "Claude's reading: the lookup is exec.LookPath(\"mobium-driver-\"+name), which honors PATHEXT on Windows; the Windows 11 run sentence replaced \"not yet run there\" after 7b590a4 (#270). Verified in: internal/mobiumdriver/external.go:114."}, {"id": "g090", "kind": "fact", "question": "How do I install Mobium's agent skill into my coding agent?", "tags": ["how-to", "agent-builder"], "gold": [{"id": "README.md#front-doors", "heading": "Front doors", "path": "README.md", "excerpt": "The CLI does not implement behavior. It calls the same tools an MCP client calls, so the surfaces cannot drift: ```mermaid flowchart LR cli[\"CLI\"] --> daemon clients[\"Python · JS · Go · Java · .NET\"] --> pipe[\"mobium pipe\"] --> daemon mcp[\"MCP client\"] --> mcpcmd[\"mobium mcp\"] daemon[\"daemon<br/>sessions, @refs\"] --> agent mcpcmd --> agent[\"internal/agent<br/>every tool, written once\"] agent --> driver[\"internal/mobi…"}], "retrieved": [{"id": "docs/quickstart/mcp.md#2-connect-an-agent", "heading": "2. Connect an agent", "path": "docs/quickstart/mcp.md", "excerpt": "`mobium mcp` is an MCP server on stdio, so there is nothing to install beyond `mobium` itself. Register it with your agent — in Claude Code: ```sh claude mcp add mobium -- mobium mcp ``` Other clients take the same command in their `mcpServers` configuration; [the MCP guide](../guides/mcp.md#1-connect-it) has the JSON. From then on, ask the agent for what you want done on the device, and it calls the tools below itse…", "gold": false}, {"id": "README.md#front-doors", "heading": "Front doors", "path": "README.md", "excerpt": "The CLI does not implement behavior. It calls the same tools an MCP client calls, so the surfaces cannot drift: ```mermaid flowchart LR cli[\"CLI\"] --> daemon clients[\"Python · JS · Go · Java · .NET\"] --> pipe[\"mobium pipe\"] --> daemon mcp[\"MCP client\"] --> mcpcmd[\"mobium mcp\"] daemon[\"daemon<br/>sessions, @refs\"] --> agent mcpcmd --> agent[\"internal/agent<br/>every tool, written once\"] agent --> driver[\"internal/mobi…", "gold": true}, {"id": "docs/guides/mcp.md#2-an-agent-at-work", "heading": "2. An agent at work", "path": "docs/guides/mcp.md", "excerpt": "Claude Code, non-interactively, with Mobium's server and nothing else allowed: ```sh claude -p \"Use the mobium tools. On the Android emulator, open the app dev.mobium.mobiumapp, go to its Login Demo, sign in with username mobium and password wrongpass1, and tell me exactly what the app says. Keep it short.\" \\ --mcp-config mobium.json --strict-mcp-config --allowedTools mcp__mobium ``` The calls it made, in order, each…", "gold": false}, {"id": "docs/guides/mcp.md#mcp-mobium-as-an-agents-tools", "heading": "MCP: Mobium as an agent's tools", "path": "docs/guides/mcp.md", "excerpt": "`mobium mcp` serves every one of Mobium's tools over the Model Context Protocol, on stdio, so an agent — Claude Code, or any MCP client — drives devices with the same tools the command line and the language clients use. This guide is how to connect one, what it sees, and how its answers and failures come back. Everything below is what ran on 2026-09-28 against [MobiumApp](https://github.com/mobiumdev/mobium-app) on a…", "gold": false}, {"id": "docs/quickstart/README.md#1-install-mobium", "heading": "1. Install mobium", "path": "docs/quickstart/README.md", "excerpt": "Until the first release there are no prebuilt binaries: mobium installs with **Go 1.24 or later** ([go.dev/dl](https://go.dev/dl/)), and needs nothing else. ```sh go install github.com/mobiumdev/mobium/cmd/mobium@latest mobium --version ``` It lands in `$(go env GOPATH)/bin`; make sure that is on your `PATH`. Each client page says how to install that client. Python (with `git`) and Go install straight from GitHub tod…", "gold": false}], "missed": false, "facts": ["Run `npx skills add mobiumdev/mobium --skill mobile-check`. ⟦npx skills add mobiumdev/mobium ; mobile-check⟧"], "concern": "", "check": "Claude's reading: the command is in README's Front doors (part ~2); the skill it installs is skills/mobile-check/SKILL.md with name mobile-check. The npx installer is outside the repo and was not run. Verified in: skills/mobile-check/SKILL.md:2."}, {"id": "g091", "kind": "fact", "question": "With Mobium's Python client, how do I make sure the device session is ended even when my script raises an exception partway?", "tags": ["how-to", "test-author"], "gold": [{"id": "docs/quickstart/python.md#notes", "heading": "Notes", "path": "docs/quickstart/python.md", "excerpt": "- `with start(...) as device:` quits when the block ends, even on an exception. Without `with`, call `device.quit()` yourself — in a `finally`. - `connect()` still exists: it opens a connection without touching the device, and its `close()` leaves the session open for whoever started it. - With more than one device of the session's platform running — two Android devices, or two among the booted simulators and attache…"}], "retrieved": [{"id": "docs/quickstart/python.md#notes", "heading": "Notes", "path": "docs/quickstart/python.md", "excerpt": "- `with start(...) as device:` quits when the block ends, even on an exception. Without `with`, call `device.quit()` yourself — in a `finally`. - `connect()` still exists: it opens a connection without touching the device, and its `close()` leaves the session open for whoever started it. - With more than one device of the session's platform running — two Android devices, or two among the booted simulators and attache…", "gold": true}, {"id": "docs/SHUTDOWN.md#a-clients-sessions-end-with-it", "heading": "A client's sessions end with it", "path": "docs/SHUTDOWN.md", "excerpt": "A session a client opened with `start()` ends when the client goes, whether it called `quit()`, returned without it, crashed or was killed: `mobium pipe` ends the sessions its client started, and only those. `close()` is the way to leave one open on purpose. So a test run that dies half-way no longer leaves a device session behind for the next one to trip over (defect 130). A pipe still running after its client is re…", "gold": false}, {"id": "CHALLENGES#130", "heading": "130. A client that went away left its session open", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** reading what happens to a session when its client exits, then measuring it on the iPhone 17 Pro simulator. Nothing tied a session to the client that started it. A script that returned without `quit()`, or crashed, closed its pipe exactly as `close()` does, and the pipe returned with the session still open on the device until the daemon went idle for 30 minutes. Ctrl-C was worse: it reaches the whole pro…", "gold": false}, {"id": "docs/quickstart/dotnet.md#notes", "heading": "Notes", "path": "docs/quickstart/dotnet.md", "excerpt": "- A `using` block around `Start()` quits when it ends, even on an exception. Around `Connect()` it only closes the connection. - With more than one device of the session's platform running — two Android devices, or two among the booted simulators and attached iPhones — `start` refuses to guess and lists them. One Android device and one iOS device are not ambiguous: the platform picks. Name one with `MOBIUM_DEVICE=<se…", "gold": false}, {"id": "docs/quickstart/javascript.md#notes", "heading": "Notes", "path": "docs/quickstart/javascript.md", "excerpt": "- Put `quit()` in a `finally`, as the example does, so an error part-way still ends the session. A second `quit()` does nothing. - `connect()` still exists: it opens a connection without touching the device, and its `close()` leaves the session open. - With more than one device of the session's platform running — two Android devices, or two among the booted simulators and attached iPhones — `start` refuses to guess a…", "gold": false}], "missed": false, "facts": ["Use `with start(...) as device:`, which quits when the block ends, even on an exception. ⟦with start⟧", "Without `with`, call `device.quit()` yourself in a `finally`. ⟦finally⟧"], "concern": "", "check": "Claude's reading: Device.__exit__ calls quit() for a device from start() and only close() for one from connect(); quit() is idempotent, so an explicit quit plus a with block is fine. Verified in: clients/python/mobium/_device.py:182, clients/python/mobium/_device.py:211."}, {"id": "g092", "kind": "fact", "question": "The .NET client is not on NuGet yet. How do I add it to my project?", "tags": ["how-to", "test-author"], "gold": [{"id": "docs/quickstart/dotnet.md#2-install-the-client", "heading": "2. Install the client", "path": "docs/quickstart/dotnet.md", "excerpt": "Not on NuGet yet. Until the first release it installs from a local package built from a clone; after it, `dotnet add package Mobium` needs nothing else. ```sh git clone https://github.com/mobiumdev/mobium.git ~/mobium dotnet pack ~/mobium/clients/dotnet/Mobium -o ~/mobium-packages dotnet new console -o quickstart && cd quickstart dotnet add package Mobium --version 0.1.0 --source ~/mobium-packages ```"}], "retrieved": [{"id": "docs/quickstart/dotnet.md#2-install-the-client", "heading": "2. Install the client", "path": "docs/quickstart/dotnet.md", "excerpt": "Not on NuGet yet. Until the first release it installs from a local package built from a clone; after it, `dotnet add package Mobium` needs nothing else. ```sh git clone https://github.com/mobiumdev/mobium.git ~/mobium dotnet pack ~/mobium/clients/dotnet/Mobium -o ~/mobium-packages dotnet new console -o quickstart && cd quickstart dotnet add package Mobium --version 0.1.0 --source ~/mobium-packages ```", "gold": true}, {"id": "CHALLENGES#150", "heading": "150. The .NET package could not be built from a clone", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** following the quick start on a fresh Linux machine, which clones the repository as the .NET page says to: `dotnet pack` failed with `NU5019: File not found: .../Mobium/icon.png`. The package's icon was added with the package metadata (#11), and `.gitignore` ignores every `*.png`, because screenshots land in the tree constantly during device work — so the icon was never committed. Every check that packed…", "gold": false}, {"id": "docs/quickstart/javascript.md#2-install-the-client", "heading": "2. Install the client", "path": "docs/quickstart/javascript.md", "excerpt": "Not on npm yet, and npm cannot install a package from a folder inside a repository, so until the first release it installs from a clone. After the release this becomes `npm install mobium`. ```sh git clone https://github.com/mobiumdev/mobium.git ~/mobium mkdir quickstart && cd quickstart npm init -y npm install ~/mobium/clients/javascript ```", "gold": false}, {"id": "docs/quickstart/java.md#2-install-the-client", "heading": "2. Install the client", "path": "docs/quickstart/java.md", "excerpt": "Not on Maven Central yet. Until the first release it installs into your local Maven repository from a clone; after it, the dependency below resolves from Central with no clone at all. ```sh git clone https://github.com/mobiumdev/mobium.git ~/mobium cd ~/mobium/clients/java && ./mvnw install -DskipTests && cd - mkdir quickstart && cd quickstart ```", "gold": false}, {"id": "docs/quickstart/README.md#1-install-mobium", "heading": "1. Install mobium", "path": "docs/quickstart/README.md", "excerpt": "Until the first release there are no prebuilt binaries: mobium installs with **Go 1.24 or later** ([go.dev/dl](https://go.dev/dl/)), and needs nothing else. ```sh go install github.com/mobiumdev/mobium/cmd/mobium@latest mobium --version ``` It lands in `$(go env GOPATH)/bin`; make sure that is on your `PATH`. Each client page says how to install that client. Python (with `git`) and Go install straight from GitHub tod…", "gold": false}], "missed": false, "facts": ["Clone the repository and build a local package with `dotnet pack` from clients/dotnet/Mobium into a folder. ⟦dotnet pack⟧", "Add it with `dotnet add package Mobium --version 0.1.0 --source <that folder>`. ⟦--source⟧"], "concern": "", "check": "Claude's reading: the csproj's PackageId is Mobium and Version 0.1.0, matching the quickstart's `--version 0.1.0`. Verified in: clients/dotnet/Mobium/Mobium.csproj:29, clients/dotnet/Mobium/Mobium.csproj:30."}, {"id": "g093", "kind": "fact", "question": "Why would a pull request that adds a separate implementation of some behavior just for the MCP server be pushed back on in Mobium?", "tags": ["rationale", "contributor"], "gold": [{"id": "CONTRIBUTING.md#the-design-rule", "heading": "The design rule", "path": "CONTRIBUTING.md", "excerpt": "***Mutatis mutandis*** — the same argument carried into a new domain, changing only what must change. When something needs to work on a second platform, through a second front door or via a third-party backend, the answer is the existing thing with the necessary changes, not a parallel implementation. A change that duplicates a layer is almost always the wrong one. [docs/PHILOSOPHY.md](docs/PHILOSOPHY.md) has where t…"}], "retrieved": [{"id": "README.md#front-doors", "heading": "Front doors", "path": "README.md", "excerpt": "The CLI does not implement behavior. It calls the same tools an MCP client calls, so the surfaces cannot drift: ```mermaid flowchart LR cli[\"CLI\"] --> daemon clients[\"Python · JS · Go · Java · .NET\"] --> pipe[\"mobium pipe\"] --> daemon mcp[\"MCP client\"] --> mcpcmd[\"mobium mcp\"] daemon[\"daemon<br/>sessions, @refs\"] --> agent mcpcmd --> agent[\"internal/agent<br/>every tool, written once\"] agent --> driver[\"internal/mobi…", "gold": false}, {"id": "packaging/mcp/README.md#mcp-packaging", "heading": "MCP packaging", "path": "packaging/mcp/README.md", "excerpt": "What puts Mobium's MCP server — `mobium mcp` — into the [MCP Registry](https://registry.modelcontextprotocol.io) and into clients that install MCP bundles, such as Claude Desktop. | File | What it is | | --- | --- | | [manifest.json](manifest.json) | The MCPB manifest, a template: the version and the tool list are filled in at build time | | [launcher.sh](launcher.sh) | The bundle's entry point, `server/mobium`: a bu…", "gold": false}, {"id": "docs/DEVELOPMENT.md#7-send-a-pull-request", "heading": "7. Send a pull request", "path": "docs/DEVELOPMENT.md", "excerpt": "`main` is protected. A change reaches it through a pull request that has been reviewed and whose **Build, vet and test** check passes. Two more jobs run on Windows: one runs the .NET client's tests, and `go-windows` runs both Go modules' tests, the named-pipe daemon transport's, and a smoke test of the built `mobium.exe`. History stays linear: pull requests are squash-merged, merge commits are off, force-pushes to `m…", "gold": false}, {"id": "docs/ARCHITECTURE.md#the-whole-system", "heading": "The whole system", "path": "docs/ARCHITECTURE.md", "excerpt": "```mermaid flowchart TB subgraph doors[\"Front doors\"] cli[\"CLI<br/>mobium map, mobium tap @e5\"] clients[\"Language clients<br/>Python · JavaScript · Go · Java · .NET\"] mcp[\"MCP client<br/>an agent\"] test[\"mobium test<br/>JSON test files · --ui page\"] inspect[\"mobium inspect<br/>a page showing the screen\"] end pipe[\"mobium pipe<br/>JSON-RPC on stdio\"] mcpcmd[\"mobium mcp<br/>MCP on stdio, in-process\"] daemon[\"Daemon<br/…", "gold": false}, {"id": "CLAUDE.md#rules", "heading": "Rules", "path": "CLAUDE.md", "excerpt": "- Run `make ci` before committing. After adding a tool, a flag or a schema property, run `make api flags` and add it everywhere — CLI, MCP schema, all five clients (CONTRIBUTING.md, \"Adding a tool, a flag or an error\") - Every error has a code: `mobiumerr.New(mobiumerr.<Code>, ...)`, never a bare `fmt.Errorf` - The CLI implements no behavior; it calls a tool. Behavior lives in `internal/agent` - After rebuilding, `mo…", "gold": false}], "missed": true, "facts": ["Mobium's design rule, mutatis mutandis, is to carry the existing thing with only the necessary changes, not a parallel implementation; a change that duplicates a layer is almost always the wrong one. ⟦Mutatis mutandis ; duplicates a layer⟧", "Behavior lives in internal/agent and the CLI only parses flags and calls a tool by name, so the MCP surface and every client get it too. ⟦internal/agent⟧"], "concern": "", "check": "Claude's reading: CONTRIBUTING's design rule says both; the code matches — `mobium mcp` serves agent.NewServer, the same tool layer the daemon dispatches to, and apisurface fails the build on drift between front doors. Verified in: cmd/mobium/mcp_cmd.go:25, internal/apisurface/surface_test.go:50."}, {"id": "g094", "kind": "fact", "question": "I'm driving a real Android phone on the office Wi-Fi with Mobium's default driver. Can others on that network get at the phone while my session is open, and what does Mobium offer instead?", "tags": ["behavior", "test-author"], "gold": [{"id": "docs/upstream/uiautomator2-server-binds-every-interface.md#what-mobium-does-meanwhile", "heading": "What Mobium does meanwhile", "path": "docs/upstream/uiautomator2-server-binds-every-interface.md", "excerpt": "Mobium installs the release APK, pinned by checksum, and cannot bind it. When a session opens on a real Android phone with this server, its answer says so — the server answers on the phone's network until the session ends — and names `--driver uiautomator`, which drives the phone through `uiautomator dump` over adb and listens on nothing: measured on the Pixel 8 Pro, a dump session added no listening socket where thi…"}], "retrieved": [{"id": "CHALLENGES#154", "heading": "154. A real Android phone's UiAutomator2 server answered anyone on its Wi-Fi", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** the threat model's open item, measured on the Pixel 8 Pro, Android 17, on the same Wi-Fi as the Mac. The UiAutomator2 server listens on every interface of the phone — `*:6790`, and its MJPEG stream on `*:7810` — and from the Mac, over Wi-Fi rather than adb, `/status` answered \"ready to accept commands\" and the stream answered too: while a session ran, anything on the network could read the screen and dr…", "gold": false}, {"id": "docs/upstream/uiautomator2-server-binds-every-interface.md#what-mobium-does-meanwhile", "heading": "What Mobium does meanwhile", "path": "docs/upstream/uiautomator2-server-binds-every-interface.md", "excerpt": "Mobium installs the release APK, pinned by checksum, and cannot bind it. When a session opens on a real Android phone with this server, its answer says so — the server answers on the phone's network until the session ends — and names `--driver uiautomator`, which drives the phone through `uiautomator dump` over adb and listens on nothing: measured on the Pixel 8 Pro, a dump session added no listening socket where thi…", "gold": true}, {"id": "docs/upstream/uiautomator2-server-binds-every-interface.md#summary", "heading": "Summary", "path": "docs/upstream/uiautomator2-server-binds-every-interface.md", "excerpt": "The UiAutomator2 server and its MJPEG stream listen on every interface of the device, and nothing chooses otherwise. On a real phone on Wi-Fi, anyone on the same network can read the screen and drive the phone while the server runs — tap, type, open apps — with no credential, since the protocol has none. A client that reaches the server through `adb forward` does not need that, since adb connects to the device's loop…", "gold": false}, {"id": "examples/drivers/README.md#the-reference-driver", "heading": "The reference driver", "path": "examples/drivers/README.md", "excerpt": "[`mobium-driver-adb`](mobium-driver-adb) is a complete, working driver in ~350 lines of Python with no dependencies. It drives Android through plain `adb` — deliberately the same ground Mobium's own `--driver uiautomator` covers, so its output can be diffed against a known-good implementation on the same screen. That diff is how you tell a driver that works from one that returns something plausible, and it is exactly…", "gold": false}, {"id": "CHALLENGES#153", "heading": "153. A real iPhone's WebDriverAgent answered anyone on its Wi-Fi", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** the threat model's open item, measured on the iPhone 15 Plus: the runner's `/status`, which reports the phone's Wi-Fi address, was asked again at that address from the Mac, over the network rather than the cable.", "gold": false}], "missed": false, "facts": ["Yes: the session's answer says the UiAutomator2 server answers on the phone's network until the session ends. ⟦phone's network⟧", "It names `--driver uiautomator`, which drives the phone through `uiautomator dump` over adb and listens on nothing. ⟦--driver uiautomator ; listens on nothing⟧"], "concern": "", "check": "Claude's reading: sessionExposure returns the warning only for the uiautomator2 backend on a non-emulator device; its text also says the uiautomator driver reads at about 2 s a screen and cannot type, which this section does not mention. Verified in: internal/agent/session.go:31, internal/agent/session.go:373."}, {"id": "g095", "kind": "multi", "question": "The MCP guide shows `tools/list` answering 71 tools, but `mobium mcp` lists 75 for me. Is my install wrong?", "tags": ["troubleshooting", "agent-builder", "new since 7b590a4"], "gold": [{"id": "docs/API.md#the-numbers", "heading": "The numbers", "path": "docs/API.md", "excerpt": "| | | | --- | --- | | Tools | **75** | | CLI commands registered | 84 | | …visible in `mobium --help` | 83 | | …hidden | 1 (pipe) | | Command constructors in source | 90 (includes `daemon start`, `stop`, `status`) | | Client libraries | 5 | Those three command counts differ on purpose, and the arithmetic is asserted by a test: registered = visible + hidden, and the constructor count is higher again because `daemon` h…"}, {"id": "docs/guides/mcp.md#mcp-mobium-as-an-agents-tools", "heading": "MCP: Mobium as an agent's tools", "path": "docs/guides/mcp.md", "excerpt": "`mobium mcp` serves every one of Mobium's tools over the Model Context Protocol, on stdio, so an agent — Claude Code, or any MCP client — drives devices with the same tools the command line and the language clients use. This guide is how to connect one, what it sees, and how its answers and failures come back. Everything below is what ran on 2026-09-28 against [MobiumApp](https://github.com/mobiumdev/mobium-app) on a…"}], "retrieved": [{"id": "docs/guides/mcp.md#which-front-door", "heading": "Which front door", "path": "docs/guides/mcp.md", "excerpt": "| | Command line | MCP | Language clients | | --- | --- | --- | --- | | For | a person, a shell script, CI | an agent | a program or a test suite | | Runs as | `mobium <command>` through the daemon | `mobium mcp`, in its own process | `mobium pipe`, spawned by the client, through the daemon | | Answers | text, or `--json` | `content` and `structuredContent` | typed results and exceptions | The same 71 tools behind ea…", "gold": false}, {"id": "docs/guides/mcp.md#mcp-mobium-as-an-agents-tools", "heading": "MCP: Mobium as an agent's tools", "path": "docs/guides/mcp.md", "excerpt": "`mobium mcp` serves every one of Mobium's tools over the Model Context Protocol, on stdio, so an agent — Claude Code, or any MCP client — drives devices with the same tools the command line and the language clients use. This guide is how to connect one, what it sees, and how its answers and failures come back. Everything below is what ran on 2026-09-28 against [MobiumApp](https://github.com/mobiumdev/mobium-app) on a…", "gold": true}, {"id": "docs/WINDOWS.md#what-is-expected-to-work-already", "heading": "What is expected to work already", "path": "docs/WINDOWS.md", "excerpt": "Never run against a device on Windows — that is the point of this exercise — but these have no platform-specific code: - the tool layer, the driver interface, the tree parser, locators and refs - `adb` discovery and every Android command, including port forwarding - the UiAutomator2 backend, its APK download and checksum verification - WebView contexts over CDP - **`mobium mcp`**, which runs the tool layer in-process…", "gold": false}, {"id": "docs/quickstart/mcp.md#2-connect-an-agent", "heading": "2. Connect an agent", "path": "docs/quickstart/mcp.md", "excerpt": "`mobium mcp` is an MCP server on stdio, so there is nothing to install beyond `mobium` itself. Register it with your agent — in Claude Code: ```sh claude mcp add mobium -- mobium mcp ``` Other clients take the same command in their `mcpServers` configuration; [the MCP guide](../guides/mcp.md#1-connect-it) has the JSON. From then on, ask the agent for what you want done on the device, and it calls the tools below itse…", "gold": false}, {"id": "docs/guides/cli.md#the-command-line", "heading": "The command line", "path": "docs/guides/cli.md", "excerpt": "`mobium` is one binary, and every command is one call to one of Mobium's tools — the same tools an MCP client and the five language clients call, so the command line cannot do something they cannot. This guide is how the commands fit together: the loop, sessions and the daemon, the flags every command takes, reading answers from a script, and exit statuses. Every command and every line of output below is what `mobium…", "gold": false}], "missed": false, "facts": ["No: the generated tool surface in API.md counts 75 tools today. ⟦75⟧", "The guide's transcripts are from a run on 2026-09-28, and its full tool list is the generated API.md."], "concern": "docs/guides/mcp.md:126 and :296 and docs/quickstart/mcp.md:134 and :166 still say 71 tools; the code (internal/agent/schema.go) has 75, and API.md said 73 at the pin. The guide and quickstart are stale.", "check": "Claude's reading: schema.go defines 75 app_ tools; app_speech and app_assistant were added after 7b590a4 (73 at the pin). A right answer needs API.md for the count and the guide's intro for why its number is older. Verified in: internal/agent/schema.go:1966, internal/agent/schema.go:2007, docs/api/surface.json."}, {"id": "g096", "kind": "multi", "question": "My driver should let Mobium scroll and use scroll-to. What do I have to advertise and implement?", "tags": ["how-to", "driver-author"], "gold": [{"id": "examples/drivers/README.md#capabilities", "heading": "Capabilities", "path": "examples/drivers/README.md", "excerpt": "`snapshot`, `screenshot` and `tap` are mandatory. Everything else is opt-in: | Capability | Methods | What you unlock | |---|---|---| | `gestures` | `swipe`, `longPress` | scrolling, `scroll-to`, long press | | `text` | `setText`, `clear` | typing into a named element | | `apps` | `launch`, `terminate`, `install`, `openUrl` | app lifecycle and deep links | | `appearance` | `appearance`, `setAppearance` | light/dark |…"}, {"id": "examples/drivers/PROTOCOL.md#methods", "heading": "Methods", "path": "examples/drivers/PROTOCOL.md", "excerpt": "| Method | Params | Result | Capability | |---|---|---|---| | `initialize` | `protocolVersion`, `device` | `protocolVersion`, `name`, `capabilities` | — | | `snapshot` | — | a wire node (see below) | — | | `screenshot` | — | `{\"png\":\"<base64>\"}` | — | | `tap` | `x`, `y` | `{}` | — | | `swipe` | `x1`,`y1`,`x2`,`y2`,`durationMs` | `{}` | `gestures` | | `longPress` | `x`,`y`,`durationMs` | `{}` | `gestures` | | `setText…"}], "retrieved": [{"id": "skills/mobile-check/SKILL.md#reaching-things-below-the-fold", "heading": "Reaching things below the fold", "path": "skills/mobile-check/SKILL.md", "excerpt": "`mobium map` only sees what is currently on screen. Tap, type and long-press already scroll to a target that is not, so most of the time nothing extra is needed — reach for `scroll-to` to look without acting, or to go back up: - `mobium scroll-to \"text=Sign out\"` — bring it into view and get a ref - `mobium scroll-to \"text=Network & internet\" --direction up` Vertical lists only. For a horizontal pager or carousel use…", "gold": false}, {"id": "CHALLENGES#if-you-are-seeing-something-odd-start-here", "heading": "If you are seeing something odd, start here", "path": "docs/CHALLENGES.md", "excerpt": "Symptom first, because that is what you have. Every row points at the entry with the evidence. | What you are seeing | What it usually is | | --- | --- | | A command \"succeeded\" and nothing changed | Nothing here reports failure by exit code. `pm grant`, `simctl privacy`, `am start`, `adb uninstall` and `uiautomator dump` each fail differently — 25, 26, 27, 30 | | An element is on screen but a locator says it is not …", "gold": false}, {"id": "examples/drivers/README.md#the-reference-driver", "heading": "The reference driver", "path": "examples/drivers/README.md", "excerpt": "[`mobium-driver-adb`](mobium-driver-adb) is a complete, working driver in ~350 lines of Python with no dependencies. It drives Android through plain `adb` — deliberately the same ground Mobium's own `--driver uiautomator` covers, so its output can be diffed against a known-good implementation on the same screen. That diff is how you tell a driver that works from one that returns something plausible, and it is exactly…", "gold": false}, {"id": "skills/mobile-check/SKILL.md#when-things-fail", "heading": "When things fail", "path": "skills/mobile-check/SKILL.md", "excerpt": "Mobium's errors say what to do; read them rather than retrying blindly. Every failure also carries a **code**, so you can act on the kind without parsing the sentence: `--json` prints it (`\"code\": \"no_such_element\"`, with a `remedy` and `details`), and the exit status groups it: | Exit | Codes | What to do | | --- | --- | --- | | 2 | `invalid_argument` | fix the command; retrying it unchanged cannot help | | 3 | `no_…", "gold": false}, {"id": "CHALLENGES#169", "heading": "169. scroll-to stopped with its target a sliver at the edge", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** the documentation site's picture of `mobium scroll-to \"label=Card 8\" --direction right` on MobiumApp's Pager Demo, on an Android 15 emulator — the answer said Card 8 was on screen, and the picture showed Card 7 with 101 pixels of Card 8 at the edge. `app_scroll_to` stops when its target is wholly inside its scroll container, and on Android that test can never fail once any of the target is in: a child's…", "gold": false}], "missed": true, "facts": ["Advertise the `gestures` capability in the initialize reply; it unlocks scrolling, scroll-to and long press.", "Implement `swipe` taking x1, y1, x2, y2 and durationMs (and `longPress` taking x, y, durationMs), in device pixels. ⟦durationMs⟧"], "concern": "", "check": "Claude's reading: README's capabilities table maps gestures to swipe and longPress and what they unlock; PROTOCOL's methods table has the parameters, which External.Swipe and LongPress send exactly. Verified in: internal/mobiumdriver/external.go:318, internal/mobiumdriver/external.go:324."}, {"id": "g097", "kind": "multi", "question": "I want two agents, each driving its own Android emulator through Mobium's MCP server at the same time. How do I set them up so they don't get in each other's way?", "tags": ["how-to", "agent-builder"], "gold": [{"id": "docs/guides/mcp.md#1-connect-it", "heading": "1. Connect it", "path": "docs/guides/mcp.md", "excerpt": "In Claude Code: ```sh claude mcp add mobium -- mobium mcp ``` With more than one device, pin one — `mobium mcp --device emulator-5554` — or let the agent pass `device` to each call. `--driver wda` makes iOS the default. Other MCP clients take the same server in their JSON configuration, under `mcpServers`: ```json { \"mcpServers\": { \"mobium\": { \"command\": \"mobium\", \"args\": [\"mcp\", \"--device\", \"emulator-5554\"] } } } ``…"}, {"id": "docs/guides/mcp.md#6-sessions-and-sharing-a-device", "heading": "6. Sessions, and sharing a device", "path": "docs/guides/mcp.md", "excerpt": "`mobium mcp` runs the tools in its own process: the editor's MCP connection is the long-lived thing, and it holds its own device sessions, with the agent's refs. The command line and the language clients share a daemon instead. A device's automation server holds one session at a time, so an agent's MCP server and a `mobium` command driving **the same device at the same time** take it from each other — each recovers, …"}], "retrieved": [{"id": "docs/guides/mcp.md#6-sessions-and-sharing-a-device", "heading": "6. Sessions, and sharing a device", "path": "docs/guides/mcp.md", "excerpt": "`mobium mcp` runs the tools in its own process: the editor's MCP connection is the long-lived thing, and it holds its own device sessions, with the agent's refs. The command line and the language clients share a daemon instead. A device's automation server holds one session at a time, so an agent's MCP server and a `mobium` command driving **the same device at the same time** take it from each other — each recovers, …", "gold": true}, {"id": "docs/guides/mcp.md#1-connect-it", "heading": "1. Connect it", "path": "docs/guides/mcp.md", "excerpt": "In Claude Code: ```sh claude mcp add mobium -- mobium mcp ``` With more than one device, pin one — `mobium mcp --device emulator-5554` — or let the agent pass `device` to each call. `--driver wda` makes iOS the default. Other MCP clients take the same server in their JSON configuration, under `mcpServers`: ```json { \"mcpServers\": { \"mobium\": { \"command\": \"mobium\", \"args\": [\"mcp\", \"--device\", \"emulator-5554\"] } } } ``…", "gold": true}, {"id": "docs/SETUP.md#parallel-runs", "heading": "Parallel runs", "path": "docs/SETUP.md", "excerpt": "**Give each run that drives a device at the same time as another its own daemon.** One daemon serves one call at a time, across every device it holds, so two runs sharing one go at the pace of the slower device. Measured on 2026-09-27, 15 `map` calls on each of an Android 15 emulator and an iPhone 17 Pro simulator at once: | | the emulator's 15 calls | | --- | --- | | alone | 0.3s | | sharing a daemon with the simula…", "gold": false}, {"id": "docs/guides/mcp.md#mcp-mobium-as-an-agents-tools", "heading": "MCP: Mobium as an agent's tools", "path": "docs/guides/mcp.md", "excerpt": "`mobium mcp` serves every one of Mobium's tools over the Model Context Protocol, on stdio, so an agent — Claude Code, or any MCP client — drives devices with the same tools the command line and the language clients use. This guide is how to connect one, what it sees, and how its answers and failures come back. Everything below is what ran on 2026-09-28 against [MobiumApp](https://github.com/mobiumdev/mobium-app) on a…", "gold": false}, {"id": "docs/quickstart/mcp.md#2-connect-an-agent", "heading": "2. Connect an agent", "path": "docs/quickstart/mcp.md", "excerpt": "`mobium mcp` is an MCP server on stdio, so there is nothing to install beyond `mobium` itself. Register it with your agent — in Claude Code: ```sh claude mcp add mobium -- mobium mcp ``` Other clients take the same command in their `mcpServers` configuration; [the MCP guide](../guides/mcp.md#1-connect-it) has the JSON. From then on, ask the agent for what you want done on the device, and it calls the tools below itse…", "gold": false}], "missed": false, "facts": ["Pin each server to its own device, e.g. `mobium mcp --device emulator-5554` in each client's configuration. ⟦--device emulator-5554⟧", "Each `mobium mcp` runs the tools in its own process with its own device sessions, and a device's automation server holds one session at a time, so each agent needs its own device. ⟦one session at a time ; its own process⟧"], "concern": "", "check": "Claude's reading: SetDefaultDevice is set from the global --device in mcp_cmd.go; that two servers on two different devices work together is implied by section 6 rather than stated as a run, which a reviewer may want to weigh. Verified in: cmd/mobium/mcp_cmd.go:26, internal/agent/server.go."}, {"id": "g098", "kind": "multi", "question": "Can I put Mobium into a read-only mode so my agent can look at the screen but never act on the device?", "tags": ["support", "agent-builder"], "gold": [{"id": "docs/THREAT-MODEL.md#the-llm-top-10", "heading": "The LLM Top 10", "path": "docs/THREAT-MODEL.md", "excerpt": "| Risk | Here | Done | Open | | --- | --- | --- | --- | | **LLM01 Prompt injection** | Screen text is the classic indirect path: an app or page shows \"ignore your task and uninstall…\", and the agent reads it in `map` or `text` | Labels are bounded and cleaned, so one label cannot carry a page of instructions | Results mark which content came from the device, so an agent or its harness can treat it as data. An agent e…"}, {"id": "docs/guides/mcp.md#3-what-a-client-sees", "heading": "3. What a client sees", "path": "docs/guides/mcp.md", "excerpt": "The handshake, as sent and answered: ``` >>> {\"jsonrpc\": \"2.0\", \"id\": 1, \"method\": \"initialize\", \"params\": {\"protocolVersion\": \"2024-11-05\", \"capabilities\": {}, \"clientInfo\": {\"name\": \"probe\", \"version\": \"1\"}}} <<< { \"jsonrpc\": \"2.0\", \"id\": 1, \"result\": { \"protocolVersion\": \"2024-11-05\", \"capabilities\": { \"tools\": {} }, \"serverInfo\": { \"name\": \"mobium\", \"version\": \"0.1.0-dev\" } } } ``` `tools/list` answered with 71 t…"}], "retrieved": [{"id": "docs/THREAT-MODEL.md#what-it-is-for-this-purpose", "heading": "What it is, for this purpose", "path": "docs/THREAT-MODEL.md", "excerpt": "- **Mobium does not run a model.** It is the hands of one: an agent, or a script, calls tools; Mobium acts on a device and reports what it saw. - **Everything it reports comes from apps it does not control.** `map` labels, `text`, `source`, WebView `eval` results, notifications, device logs, crash reports, the clipboard. Any app or page can put text there, including text written to be read by an agent as an instructi…", "gold": false}, {"id": "docs/SETUP.md#with-a-screen-reader-on", "heading": "With a screen reader on", "path": "docs/SETUP.md", "excerpt": "Android's test-automation connection silences every other accessibility service while it is open, unless it is opened not to. So on a device with TalkBack — or VoiceView, on a Fire TV — on, a read of the screen takes the screen reader away for as long as it runs, and an app that publishes its contents only to a screen reader stops publishing them (CHALLENGES 208). Both drivers leave the screen reader running. The def…", "gold": false}, {"id": "CHALLENGES#109", "heading": "109. On Android, a screen in motion could only be read once it stopped", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** the confetti on MobiumApp's Motion Demo, which exists to put a screen in continuous motion on purpose. The first read during a three-second burst took 3.75s and read the burst as over; a `find` during a slower one took 11s, and the piece it aimed at had fallen off the screen by then. iOS read the same burst in 0.56s, mid-fall. Mobium never set UiAutomator2's `waitForIdleTimeout`, so the server's default…", "gold": false}, {"id": "CHALLENGES#208", "heading": "208. Every read silenced the device's screen reader", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** reading Prime Video on a Fire TV, which publishes nothing but one surface to `map`, to see whether it publishes more while Amazon's screen reader, VoiceView, is on. Every read of the screen — `uiautomator dump` and the UiAutomator2 server alike — unbound VoiceView for as long as it ran: `dumpsys accessibility` listed it before the read and not during it, and touch exploration went off. Android's test-au…", "gold": false}, {"id": "docs/SETUP.md#slower-and-one-stall-to-know-about", "heading": "Slower, and one stall to know about", "path": "docs/SETUP.md", "excerpt": "A phone reads a screen in about 2 seconds for Settings and 6 for the home screen, against a fraction of a second on a simulator; a screenshot takes 0.5s. Prefer `map` to `screenshot` for the same reason as on Android. **The first read after switching apps can stall for a minute and return the app you just left** ([CHALLENGES 71](CHALLENGES.md)). Mobium prevents it for the switches it makes itself — `launch` and `pres…", "gold": false}], "missed": true, "facts": ["Not in Mobium itself: a read-only mode Mobium enforces, and a tool allowlist, are listed as open. ⟦read-only mode⟧", "Every MCP tool carries `readOnlyHint`, true only for the tools that only read (`app_map`, `app_text`, `app_state` and the like), so the agent's harness can allow only reads. ⟦readOnlyHint⟧"], "concern": "", "check": "Claude's reading: readonly.go lists 19 read-only tools and schema.go sets readOnlyHint from it; `mobium mcp` has no read-only flag. Unrelated defect seen while checking: app_network's new `proxy` argument is missing from readUnless in readonly.go, so IsReadCall treats a proxy-setting call as a read for the test runner's expect. Verified in: internal/agent/readonly.go:13, internal/agent/schema.go:2243, cmd/mobium/mcp_cmd.go:11."}, {"id": "g099", "kind": "unanswerable", "question": "How many tool calls per minute will Mobium's MCP server accept before it starts throttling my agent?", "tags": ["agent-builder"], "gold": [], "retrieved": [{"id": "README.md#front-doors", "heading": "Front doors", "path": "README.md", "excerpt": "The CLI does not implement behavior. It calls the same tools an MCP client calls, so the surfaces cannot drift: ```mermaid flowchart LR cli[\"CLI\"] --> daemon clients[\"Python · JS · Go · Java · .NET\"] --> pipe[\"mobium pipe\"] --> daemon mcp[\"MCP client\"] --> mcpcmd[\"mobium mcp\"] daemon[\"daemon<br/>sessions, @refs\"] --> agent mcpcmd --> agent[\"internal/agent<br/>every tool, written once\"] agent --> driver[\"internal/mobi…", "gold": false}, {"id": "docs/quickstart/mcp.md#3-the-code", "heading": "3. The code", "path": "docs/quickstart/mcp.md", "excerpt": "Save this as `quickstart.py` — it is [examples/mcp/quickstart.py](examples/mcp/quickstart.py). The calls an agent makes, made by a script instead: start the server, open with the handshake, then one `tools/call` per step. Every tool is an `app_` name with JSON arguments, and every answer has text to read and, for most, `structuredContent` to use as data. ```python \"\"\"Mobium quick start over MCP: start a session, driv…", "gold": false}, {"id": "docs/guides/mcp.md#6-sessions-and-sharing-a-device", "heading": "6. Sessions, and sharing a device", "path": "docs/guides/mcp.md", "excerpt": "`mobium mcp` runs the tools in its own process: the editor's MCP connection is the long-lived thing, and it holds its own device sessions, with the agent's refs. The command line and the language clients share a daemon instead. A device's automation server holds one session at a time, so an agent's MCP server and a `mobium` command driving **the same device at the same time** take it from each other — each recovers, …", "gold": false}, {"id": "docs/guides/mcp.md#mcp-mobium-as-an-agents-tools", "heading": "MCP: Mobium as an agent's tools", "path": "docs/guides/mcp.md", "excerpt": "`mobium mcp` serves every one of Mobium's tools over the Model Context Protocol, on stdio, so an agent — Claude Code, or any MCP client — drives devices with the same tools the command line and the language clients use. This guide is how to connect one, what it sees, and how its answers and failures come back. Everything below is what ran on 2026-09-28 against [MobiumApp](https://github.com/mobiumdev/mobium-app) on a…", "gold": false}, {"id": "docs/quickstart/mcp.md#2-connect-an-agent", "heading": "2. Connect an agent", "path": "docs/quickstart/mcp.md", "excerpt": "`mobium mcp` is an MCP server on stdio, so there is nothing to install beyond `mobium` itself. Register it with your agent — in Claude Code: ```sh claude mcp add mobium -- mobium mcp ``` Other clients take the same command in their `mcpServers` configuration; [the MCP guide](../guides/mcp.md#1-connect-it) has the JSON. From then on, ask the agent for what you want done on the device, and it calls the tools below itse…", "gold": false}], "missed": false, "facts": [], "concern": "", "check": "Claude's reading: no rate limit is stated anywhere in the corpus, and the code has none (grep for rate limit or throttle in internal/agent and cmd/mobium finds only Android's crash-record limit); the threat model's unbounded-consumption row lists per-call timeouts, batches of at most 100 steps and backgrounding of at most 180 s, which a retriever will bring back. Nearest sections: docs/THREAT-MODEL.md#the-llm-top-10, docs/guides/mcp.md#6-sessions-and-sharing-a-device. Verified in: internal/agent/server.go:43."}, {"id": "g100", "kind": "unanswerable", "question": "When will Mobium's Python client be published on PyPI so I can just run pip install mobium?", "tags": ["test-author"], "gold": [], "retrieved": [{"id": "docs/quickstart/python.md#2-install-the-client", "heading": "2. Install the client", "path": "docs/quickstart/python.md", "excerpt": "Not on PyPI yet — pip installs it straight from GitHub, which needs `git` on your `PATH`. After the first release this becomes `pip install mobium`. ```sh mkdir quickstart && cd quickstart python3 -m venv .venv .venv/bin/pip install \"mobium @ git+https://github.com/mobiumdev/mobium.git#subdirectory=clients/python\" ```", "gold": false}, {"id": "docs/DEVELOPMENT.md#5-work-on-a-client", "heading": "5. Work on a client", "path": "docs/DEVELOPMENT.md", "excerpt": "Each client's tests start a fake `mobium` and need no device: | Client | Its tests | Run a program against it from this clone | | --- | --- | --- | | Python | `make clients` | `pip install ./clients/python` in a virtualenv | | JavaScript | `make clients` | `npm install ./clients/javascript` | | Go | `make test` | `go mod edit -replace=github.com/mobiumdev/mobium/clients/go=<path to this clone>/clients/go` in your mod…", "gold": false}, {"id": "docs/quickstart/README.md#1-install-mobium", "heading": "1. Install mobium", "path": "docs/quickstart/README.md", "excerpt": "Until the first release there are no prebuilt binaries: mobium installs with **Go 1.24 or later** ([go.dev/dl](https://go.dev/dl/)), and needs nothing else. ```sh go install github.com/mobiumdev/mobium/cmd/mobium@latest mobium --version ``` It lands in `$(go env GOPATH)/bin`; make sure that is on your `PATH`. Each client page says how to install that client. Python (with `git`) and Go install straight from GitHub tod…", "gold": false}, {"id": "docs/ROADMAP.md#under-consideration", "heading": "Under consideration", "path": "docs/ROADMAP.md", "excerpt": "- **Locators for when there is no ref** (written down 2026-10-12). A ref from `map` lasts one map, so an agent has one and a `mobium test` file does not: a hand-written test has the flat `kind=value` locators — text, label, testid, role, class, path, narrowed by `,role=` — which match one element or are refused. That is right on a form and leaves nothing durable on a list. Every Ice Cubes post has a \"…\" (CHALLENGES 2…", "gold": false}, {"id": "docs/guides/test-runner.md#quick-start-mobium-test", "heading": "Quick start: `mobium test`", "path": "docs/guides/test-runner.md", "excerpt": "From an empty directory to a test suite that runs on a device, fails with evidence, retries, and leaves a report CI can publish. Every command and every line of output below is what `mobium test` printed on 2026-09-28 — section 8 on 2026-09-29 — against [MobiumApp](https://github.com/mobiumdev/mobium-app) on an Android 15 emulator. Where a path to a report is shortened, it says so. Before this guide: [the quick start…", "gold": false}], "missed": false, "facts": [], "concern": "", "check": "Claude's reading: the quickstart says only that `pip install mobium` works after the first release, and the roadmap lists the registry accounts to set up; no date for the first release or the PyPI publish is given anywhere in the corpus. Nearest sections: docs/quickstart/python.md#2-install-the-client, docs/ROADMAP.md#next. Verified in: clients/python."}], "pins": {}};
+const DATA = {"pin": "f232d54", "questions": [{"id": "g001", "kind": "fact", "question": "There are no Mobium release binaries yet. What do I need on my Mac to install the mobium command, and what is the command?", "tags": ["how-to", "new-user"], "gold": [{"id": "docs/quickstart/README.md#1-install-mobium", "heading": "1. Install mobium", "path": "docs/quickstart/README.md", "excerpt": "Until the first release there are no prebuilt binaries: mobium installs with **Go 1.24 or later** ([go.dev/dl](https://go.dev/dl/)), and needs nothing else. ```sh go install github.com/mobiumdev/mobium/cmd/mobium@latest mobium --version ``` It lands in `$(go env GOPATH)/bin`; make sure that is on your `PATH`. Each client page says how to install that client. Python (with `git`) and Go install straight from GitHub tod…"}], "retrieved": [{"id": "docs/quickstart/README.md#1-install-mobium", "heading": "1. Install mobium", "path": "docs/quickstart/README.md", "excerpt": "Until the first release there are no prebuilt binaries: mobium installs with **Go 1.24 or later** ([go.dev/dl](https://go.dev/dl/)), and needs nothing else. ```sh go install github.com/mobiumdev/mobium/cmd/mobium@latest mobium --version ``` It lands in `$(go env GOPATH)/bin`; make sure that is on your `PATH`. Each client page says how to install that client. Python (with `git`) and Go install straight from GitHub tod…", "gold": true}, {"id": "docs/SETUP.md#installing-a-release", "heading": "Installing a release", "path": "docs/SETUP.md", "excerpt": "From the first tagged release on, each one carries mobium prebuilt for macOS, Linux and Windows, on amd64 and arm64, so installing it needs no Go: `mobium_<version>_<os>_<arch>.tar.gz` (`.zip` for Windows), each holding the binary, the license and its notices, and the README, and `SHA256SUMS` over all of them. The binary is static — nothing else to install with it. ```sh v=0.1.0; os=darwin; arch=arm64 # or linux / wi…", "gold": false}, {"id": "docs/quickstart/python.md#2-install-the-client", "heading": "2. Install the client", "path": "docs/quickstart/python.md", "excerpt": "Not on PyPI yet — pip installs it straight from GitHub, which needs `git` on your `PATH`. After the first release this becomes `pip install mobium`. ```sh mkdir quickstart && cd quickstart python3 -m venv .venv .venv/bin/pip install \"mobium @ git+https://github.com/mobiumdev/mobium.git#subdirectory=clients/python\" ```", "gold": false}, {"id": "README.md#quick-start", "heading": "Quick start", "path": "README.md", "excerpt": "Requirements: - **Go 1.24+**, to install it — prebuilt binaries arrive with the first release ([SETUP.md](docs/SETUP.md#installing-a-release)) - **Android:** platform-tools on `PATH` (or `ANDROID_HOME`, or `MOBIUM_ADB_PATH`), and an emulator or a phone with USB debugging on - **iOS:** full Xcode and a booted simulator — or an iPhone on a cable, with an Apple ID (a free one works) added to Xcode ```sh go install githu…", "gold": false}, {"id": "docs/quickstart/mcp.md#2-connect-an-agent", "heading": "2. Connect an agent", "path": "docs/quickstart/mcp.md", "excerpt": "`mobium mcp` is an MCP server on stdio, so there is nothing to install beyond `mobium` itself. Register it with your agent — in Claude Code: ```sh claude mcp add mobium -- mobium mcp ``` Other clients take the same command in their `mcpServers` configuration; [the MCP guide](../guides/mcp.md#1-connect-it) has the JSON. From then on, ask the agent for what you want done on the device, and it calls the tools below itse…", "gold": false}], "missed": false, "facts": ["Until the first release mobium installs with Go 1.24 or later and needs nothing else. ⟦Go 1.24⟧", "The install command is go install github.com/mobiumdev/mobium/cmd/mobium@latest. ⟦go install github.com/mobiumdev/mobium/cmd/mobium@latest⟧", "The binary lands in $(go env GOPATH)/bin, which must be on PATH. ⟦GOPATH⟧"], "concern": "", "check": "Claude's reading: go.mod declares go 1.24.0, matching the quick start's Go 1.24 or later; cmd/mobium is the main package. SETUP.md#installing-a-release covers the future prebuilt route and is a likely near miss, not gold. Verified in: go.mod:3, cmd/mobium/main.go."}, {"id": "g002", "kind": "fact", "question": "I made an Android virtual device in Android Studio. How do I get Mobium to start it and wait until it is ready, and how do I see its screen while it runs?", "tags": ["how-to", "new-user"], "gold": [{"id": "docs/quickstart/README.md#android-emulator-macos-linux", "heading": "Android emulator (macOS, Linux)", "path": "docs/quickstart/README.md", "excerpt": "Install [Android Studio](https://developer.android.com/studio) or the command-line tools, then create a virtual device (Device Manager in Android Studio, or `avdmanager`) and boot it by name: ```sh mobium boot <avd> ``` It finds the SDK's `emulator` itself, through `ANDROID_HOME` or the SDK's usual place, and answers once Android has finished booting — not merely once `adb` can see it. Add `--window` to watch it; it …"}], "retrieved": [{"id": "docs/quickstart/README.md#android-emulator-macos-linux", "heading": "Android emulator (macOS, Linux)", "path": "docs/quickstart/README.md", "excerpt": "Install [Android Studio](https://developer.android.com/studio) or the command-line tools, then create a virtual device (Device Manager in Android Studio, or `avdmanager`) and boot it by name: ```sh mobium boot <avd> ``` It finds the SDK's `emulator` itself, through `ANDROID_HOME` or the SDK's usual place, and answers once Android has finished booting — not merely once `adb` can see it. Add `--window` to watch it; it …", "gold": true}, {"id": "docs/quickstart/python.md#3-the-code", "heading": "3. The code", "path": "docs/quickstart/python.md", "excerpt": "Save this as `quickstart.py` in the project folder — it is [examples/python/quickstart.py](examples/python/quickstart.py). ```python \"\"\"Mobium quick start: start a session, drive Settings, quit. MOBIUM_PLATFORM=android python3 quickstart.py # or ios \"\"\" import os from mobium import start # Settings is on every emulator, simulator and phone, with nothing to install. PLATFORMS = { \"android\": {\"app\": \"com.android.settin…", "gold": false}, {"id": "docs/quickstart/cli.md#2-the-code", "heading": "2. The code", "path": "docs/quickstart/cli.md", "excerpt": "Save this as `quickstart.sh` — it is [examples/cli/quickstart.sh](examples/cli/quickstart.sh). ```sh #!/bin/sh # Mobium quick start from the command line: start a session, drive Settings, # quit. # # MOBIUM_PLATFORM=android sh quickstart.sh # or ios set -e PLATFORM=\"${MOBIUM_PLATFORM:-android}\" if [ \"$PLATFORM\" = ios ]; then APP=com.apple.Preferences ROW=General NEXT=\"label=About,role=button\" else APP=com.android.set…", "gold": false}, {"id": "docs/quickstart/cli.md#quick-start-command-line", "heading": "Quick start: Command line", "path": "docs/quickstart/cli.md", "excerpt": "<!-- Generated by docs/quickstart/build.py from examples/ and output/. Edit those, then run `make quickstart`. --> Start a session on a device, launch Settings, tap a row, take a screenshot, and quit — from the command line. Starts with `mobium session start --platform android --app com.android.settings`; ends with `mobium session end`. Before this page: [install mobium and prepare a device](README.md).", "gold": false}, {"id": "docs/quickstart/go.md#3-the-code", "heading": "3. The code", "path": "docs/quickstart/go.md", "excerpt": "Save this as `main.go` in the project folder — it is [examples/go/main.go](examples/go/main.go). ```go // Mobium quick start: start a session, drive Settings, quit. // // MOBIUM_PLATFORM=android go run . # or ios package main import ( \"context\" \"fmt\" \"log\" \"os\" \"strings\" \"time\" mobium \"github.com/mobiumdev/mobium/clients/go\" ) // Settings is on every emulator, simulator and phone, with nothing to install. var platfor…", "gold": false}], "missed": false, "facts": ["mobium boot <avd> starts the emulator by its AVD name and answers once Android has finished booting, not merely once adb sees it. ⟦mobium boot⟧", "It runs headless unless --window is added. ⟦--window⟧"], "concern": "", "check": "Claude's reading: BootEmulator passes -no-window -no-audio unless window is set (boot.go:139-141) and waits for sys.boot_completed=1 (boot.go:189). SETUP.md#android-emulator says the same in one sentence and may be returned instead; the quick-start section is the fuller answer. Verified in: internal/device/boot.go:115-141, internal/device/boot.go:189."}, {"id": "g003", "kind": "fact", "question": "My Android emulator won't start and says 'Cannot find valid sdk root path', yet adb works fine from my terminal. What is actually wrong?", "tags": ["troubleshooting", "new-user"], "gold": [{"id": "docs/SETUP.md#two-traps-neither-of-which-names-its-own-cause", "heading": "Two traps, neither of which names its own cause", "path": "docs/SETUP.md", "excerpt": "- **`platform-tools` must be installed *into the SDK root* by `sdkmanager`**, not only as the `android-platform-tools` Homebrew cask. The emulator validates the SDK root by looking for that directory and aborts with `Broken AVD system path` / `Cannot find valid sdk root path` — while `adb` sits on your `PATH` working perfectly, which sends you looking in entirely the wrong place. `mobium doctor` checks this specifica…"}], "retrieved": [{"id": "docs/SETUP.md#two-traps-neither-of-which-names-its-own-cause", "heading": "Two traps, neither of which names its own cause", "path": "docs/SETUP.md", "excerpt": "- **`platform-tools` must be installed *into the SDK root* by `sdkmanager`**, not only as the `android-platform-tools` Homebrew cask. The emulator validates the SDK root by looking for that directory and aborts with `Broken AVD system path` / `Cannot find valid sdk root path` — while `adb` sits on your `PATH` working perfectly, which sends you looking in entirely the wrong place. `mobium doctor` checks this specifica…", "gold": true}, {"id": "CHALLENGES#environment-traps", "heading": "Environment traps", "path": "docs/CHALLENGES.md", "excerpt": "None of these is a Mobium defect; each cost real time and no error named its cause. - **`platform-tools` must be installed into the SDK root** with `sdkmanager`, not only as the Homebrew cask. The emulator validates the SDK root by looking for that directory and dies with `Broken AVD system path` — while `adb` is on `PATH` and working perfectly, which sends you looking in entirely the wrong place. - **`avdmanager` pr…", "gold": false}, {"id": "docs/quickstart/README.md#android-emulator-macos-linux", "heading": "Android emulator (macOS, Linux)", "path": "docs/quickstart/README.md", "excerpt": "Install [Android Studio](https://developer.android.com/studio) or the command-line tools, then create a virtual device (Device Manager in Android Studio, or `avdmanager`) and boot it by name: ```sh mobium boot <avd> ``` It finds the SDK's `emulator` itself, through `ANDROID_HOME` or the SDK's usual place, and answers once Android has finished booting — not merely once `adb` can see it. Add `--window` to watch it; it …", "gold": false}, {"id": "docs/SETUP.md#setting-up-devices", "heading": "Setting up devices", "path": "docs/SETUP.md", "excerpt": "Everything Mobium needs on the machine and on the device, for all four kinds of target. Written from doing it: every trap below cost real time here, and most of them report something that names the wrong cause. **Run `mobium doctor` first.** It checks the whole list without needing a device, and exits non-zero if it found something: ``` ok adb Android Debug Bridge version 1.0.41 at /opt/homebrew/bin/adb note android …", "gold": false}, {"id": "docs/SETUP.md#on-linux", "heading": "On Linux", "path": "docs/SETUP.md", "excerpt": "Google ships the command-line tools as a zip, and the emulator and `platform-tools` for Linux **only for x86_64** — the SDK repository has no Linux arm64 build of either (checked 2026-09-28) — so an arm64 Linux machine cannot run the emulator. The emulator needs KVM: your user must be able to open `/dev/kvm` (usually by being in the `kvm` group). ```sh mkdir -p ~/android-sdk/cmdline-tools && cd ~/android-sdk/cmdline-…", "gold": false}], "missed": false, "facts": ["platform-tools must be installed into the SDK root by sdkmanager, not only as the Homebrew android-platform-tools cask; the emulator validates the SDK root by that directory. ⟦sdkmanager ; platform-tools⟧", "mobium doctor checks for this specifically. ⟦mobium doctor⟧"], "concern": "", "check": "Claude's reading: doctor's android sdk root check fails when the SDK root has no platform-tools directory and says to run sdkmanager platform-tools (doctor.go:115-118). The same trap is named in the doctor command's help text. Verified in: internal/agent/doctor.go:103-121, cmd/mobium/doctor.go:12-16."}, {"id": "g004", "kind": "fact", "question": "I restarted my Android emulator and my app came back as a build from days ago, missing screens I added since. Why, and how do I restart it without that happening?", "tags": ["troubleshooting", "test-author"], "gold": [{"id": "docs/SETUP.md#headed-and-headless-the-procedures-and-what-differs", "heading": "Headed and headless: the procedures, and what differs", "path": "docs/SETUP.md", "excerpt": "Measured 2026-09-26, when a headless emulator was restarted with a window mid-session and three things changed at once. The screen is the same; the **keyboard** and the **snapshot** are not. **Switching an emulator between the two.** It is decided at launch, so it is a restart, in the order `docs/SHUTDOWN.md` gives: ```sh mobium shutdown emulator-5554 && mobium boot mobium-test --window # headed mobium shutdown emula…"}], "retrieved": [{"id": "docs/SETUP.md#headed-and-headless-the-procedures-and-what-differs", "heading": "Headed and headless: the procedures, and what differs", "path": "docs/SETUP.md", "excerpt": "Measured 2026-09-26, when a headless emulator was restarted with a window mid-session and three things changed at once. The screen is the same; the **keyboard** and the **snapshot** are not. **Switching an emulator between the two.** It is decided at launch, so it is a restart, in the order `docs/SHUTDOWN.md` gives: ```sh mobium shutdown emulator-5554 && mobium boot mobium-test --window # headed mobium shutdown emula…", "gold": true}, {"id": "docs/SHUTDOWN.md#on-the-device", "heading": "On the device", "path": "docs/SHUTDOWN.md", "excerpt": "Stopping processes on your machine is not the whole job. **`clean-stop.sh --quit` now runs these**, so they are no longer a checklist nobody gets to. They were manual until a hierarchy dump turned up in `/data/local/tmp` six days after the session that wrote it, on an emulator stopped and rebooted twice in between — it was a hand-run `uiautomator dump` rather than mobium's own file, which is deleted after every read,…", "gold": false}, {"id": "docs/guides/graybox.md#when-the-app-is-not-waited-for", "heading": "When the app is not waited for", "path": "docs/guides/graybox.md", "excerpt": "Three things end a wait early, and the result says which, so a check that did not run never reads as one that passed: - **The app went to the background.** The library says `away` and `back`; while the app is away, an action elsewhere is not held up by it. - **The app stopped saying it is busy.** Busy is a lease: while work is in flight the library restates the count every half second, from a native timer that a busy…", "gold": false}, {"id": "docs/BACK.md#in-mobiumapp", "heading": "In MobiumApp", "path": "docs/BACK.md", "excerpt": "1. **Android back closed the app.** Fixed in mobium-app #12, measured above. Rebuild MobiumApp for any device that still has the old build, and keep `docs/checks/mobium-app.sh` passing. 2. **No swipe back on iOS.** Needs native-stack navigation; unmeasured. 3. **WebView screens.** Android back should go back in the page's history before leaving the screen, as a browser does. Unmeasured. 4. **Predictive back.** Measur…", "gold": false}, {"id": "CHALLENGES#186", "heading": "186. The emulator console answered nothing, and the error said nothing", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** `app_shake` on the Pixel 7 AVD, which had passed its check two days before, failing with \"the emulator did not say where its accelerometer rests:\" — and nothing after the colon. Every `adb emu` command printed nothing and exited 0, while the same commands typed into the console's own port answered at once. Another automation tool had rewritten `~/.emulator_console_auth_token` empty, a documented step of…", "gold": false}], "missed": false, "facts": ["-no-snapshot-save still loads the quick-boot snapshot on the next start, so everything installed since the snapshot is gone. ⟦-no-snapshot-save⟧", "Cold-boot with -no-snapshot-load, which mobium boot passes, or reinstall what you need and confirm its version. ⟦-no-snapshot-load⟧"], "concern": "", "check": "Claude's reading: BootEmulator always passes -no-snapshot-load and its comment cites the old-app snapshot problem (boot.go:116-118, 139). The fact is in part ~1 of the section. Verified in: internal/device/boot.go:115-139."}, {"id": "g005", "kind": "fact", "question": "What do I have to switch on, on the iPhone itself, before Mobium can drive it?", "tags": ["how-to", "test-author"], "gold": [{"id": "docs/SETUP.md#on-the-phone-once", "heading": "On the phone, once", "path": "docs/SETUP.md", "excerpt": "1. **Connect it with a cable, unlock it, tap Trust This Computer** and enter the passcode. 2. **Open Xcode → Window → Devices and Simulators** with the phone connected, and wait while Xcode prepares it. The next step's switch does not exist until this has happened. 3. **Settings → Privacy & Security → Developer Mode → on.** The phone restarts and asks you to confirm. 4. **Settings → Developer → Enable UI Automation →…"}], "retrieved": [{"id": "docs/RELEASE-CHECKLIST.md#ios-a-booted-iphone-simulator", "heading": "iOS — a booted iPhone simulator", "path": "docs/RELEASE-CHECKLIST.md", "excerpt": "- [ ] `mobium --driver wda map` on the home screen returns icons - [ ] Wait for something already on screen, and across a cold app launch - [ ] `mobium scroll-to` reaches a Settings row below the fold, and tapping it opens that screen - [ ] `mobium grant com.apple.Preferences photos` succeeds and says it could not be verified - [ ] `mobium grant <anything> camera` is refused, naming the missing service - [ ] Coordina…", "gold": false}, {"id": "CHALLENGES#153", "heading": "153. A real iPhone's WebDriverAgent answered anyone on its Wi-Fi", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** the threat model's open item, measured on the iPhone 15 Plus: the runner's `/status`, which reports the phone's Wi-Fi address, was asked again at that address from the Mac, over the network rather than the cable.", "gold": false}, {"id": "docs/SETUP.md#what-mobium-installs-and-removing-it", "heading": "What Mobium installs, and removing it", "path": "docs/SETUP.md", "excerpt": "On the machine, under `~/.mobium`: | | | | --- | --- | | `uiautomator2/`, `webdriveragent/` | pinned, checksummed device agents, ~40MB, downloaded on first use | | `webdriveragent-device/` | WebDriverAgent's pinned source and one signed build per team and phone, ~150MB — only once a real iPhone has been driven | | `daemon/` | socket and PID file, removed on shutdown | On an **Android** device, the default backend ins…", "gold": false}, {"id": "docs/THREAT-MODEL.md#the-mobile-side", "heading": "The mobile side", "path": "docs/THREAT-MODEL.md", "excerpt": "The OWASP Mobile Top 10 and MASVS are about the apps under test, not about Mobium, but two points apply to Mobium itself: - It installs a server APK on the device with its permissions granted, and builds and signs WebDriverAgent for a person's iPhone. Both are removable, and [SETUP](SETUP.md#what-mobium-installs-and-removing-it) says how. - It must leave nothing on the device: a hierarchy dump in `/data/local/tmp` is…", "gold": false}], "missed": true, "facts": ["Trust the computer over a cable and let Xcode's Devices and Simulators window prepare the phone, then turn on Developer Mode. ⟦Developer Mode⟧", "Turn on Settings > Developer > Enable UI Automation; without it WebDriverAgent fails with \"Timed out while enabling automation mode\". ⟦Enable UI Automation⟧", "Set Auto-Lock to Never (or long enough) so the phone does not lock mid-run. ⟦Auto-Lock⟧"], "concern": "", "check": "Claude's reading: wdaphone.go recognizes WebDriverAgent's \"Timed out while enabling automation mode\" log and names the switch (lines 653-660). README.md#platforms~1 lists Developer Mode and Enable UI Automation too and is a plausible near miss, but lacks the trust/Xcode/Auto-Lock steps. Verified in: internal/device/wdaphone.go:653-660."}, {"id": "g006", "kind": "fact", "question": "Which simulator features does Mobium refuse on a real iPhone, and how do I reset an app's data on a phone instead?", "tags": ["support", "test-author"], "gold": [{"id": "docs/SETUP.md#what-a-phone-cannot-do", "heading": "What a phone cannot do", "path": "docs/SETUP.md", "excerpt": "These are done by `simctl` on a simulator and `devicectl` has no equivalent, so on a phone they are refused, each with the reason, rather than approximated: **permissions, appearance, the clipboard, simulated location and routes, and notifications** — reading or posting them. **Clearing an app's data takes its bundle on a phone.** Nothing can delete from an app's container there, so `mobium clear-data <app> --bundle …"}], "retrieved": [{"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": false}, {"id": "docs/SETUP.md#what-a-phone-cannot-do", "heading": "What a phone cannot do", "path": "docs/SETUP.md", "excerpt": "These are done by `simctl` on a simulator and `devicectl` has no equivalent, so on a phone they are refused, each with the reason, rather than approximated: **permissions, appearance, the clipboard, simulated location and routes, and notifications** — reading or posting them. **Clearing an app's data takes its bundle on a phone.** Nothing can delete from an app's container there, so `mobium clear-data <app> --bundle …", "gold": true}, {"id": "docs/checks/README.md#results", "heading": "Results", "path": "docs/checks/README.md", "excerpt": "Run 2026-09-13. Both emulators are the same Pixel 7 profile — 1080x2400 at 420dpi — so the only difference between them is the OS. | Device | OS | calculator.sh | clock-timer.sh | external-driver.sh | third-party-app.sh | device-state.sh | | --- | --- | --- | --- | --- | --- | --- | | Pixel 7 AVD | Android 15 (API 35) | PASS 6.4s | PASS 5.5s | PASS | PASS | PASS | | Pixel 7 AVD | Android 17 (API 37) | PASS 6.9s | PAS…", "gold": false}], "missed": false, "facts": ["On a phone Mobium refuses permissions, appearance, the clipboard, simulated location and routes, and notifications, each with the reason, because simctl does them and devicectl has no equivalent. ⟦devicectl⟧", "Clearing an app's data on a phone takes its bundle: mobium clear-data <app> --bundle uninstalls and reinstalls the app. ⟦--bundle⟧"], "concern": "", "check": "Claude's reading: simulatorOnly in wdaphone.go lists exactly permissions, appearance, clipboard read/write, geolocation, routes, clear-data and notifications, and phoneRemedies gives the --bundle reinstall route for clear-data. The code also lists clipboard read separately; the doc says 'the clipboard'. Verified in: internal/mobiumdriver/wdaphone.go:196-230, internal/mobiumdriver/wdaphone.go:263-265."}, {"id": "g007", "kind": "multi", "question": "Can I use Mobium on a Windows PC for my Android and iOS app testing today, and how far does that go?", "tags": ["support", "new-user", "new since 7b590a4"], "gold": [{"id": "docs/WINDOWS.md#windows-support", "heading": "Windows support", "path": "docs/WINDOWS.md", "excerpt": "**Status: devices driven from Windows since 2026-10-22; not yet declared supported.** On a Windows 11 laptop (24H2, i7-8565U, 8 GB), an Android 15 emulator and a Pixel 8 Pro over USB were driven through `mobium mcp`, the CLI over the named pipe, and all five clients, which passed every step on both. A sweep of the checks on the emulator found six things, all fixed: the daemon dying with the SSH session that started i…"}, {"id": "docs/WINDOWS.md#android-only-ios-is-not-possible-on-windows", "heading": "Android only. iOS is not possible on Windows.", "path": "docs/WINDOWS.md", "excerpt": "Said here rather than in a footnote, because it is the first question anyone asks and the answer is structural rather than a gap in the work. Mobium drives iOS through `xcrun simctl` — 41 call sites in `internal/device` alone — and through WebDriverAgent, which it installs as the prebuilt `WebDriverAgentRunner-Build-Sim-arm64.zip`. `simctl` ships inside Xcode and Xcode is macOS-only; the artifact is a *simulator* bui…"}], "retrieved": [{"id": "docs/WINDOWS.md#android-only-ios-is-not-possible-on-windows", "heading": "Android only. iOS is not possible on Windows.", "path": "docs/WINDOWS.md", "excerpt": "Said here rather than in a footnote, because it is the first question anyone asks and the answer is structural rather than a gap in the work. Mobium drives iOS through `xcrun simctl` — 41 call sites in `internal/device` alone — and through WebDriverAgent, which it installs as the prebuilt `WebDriverAgentRunner-Build-Sim-arm64.zip`. `simctl` ships inside Xcode and Xcode is macOS-only; the artifact is a *simulator* bui…", "gold": true}, {"id": "docs/ROADMAP.md#under-consideration", "heading": "Under consideration", "path": "docs/ROADMAP.md", "excerpt": "- **Locators for when there is no ref** (written down 2026-10-12). A ref from `map` lasts one map, so an agent has one and a `mobium test` file does not: a hand-written test has the flat `kind=value` locators — text, label, testid, role, class, path, narrowed by `,role=` — which match one element or are refused. That is right on a form and leaves nothing durable on a list. Every Ice Cubes post has a \"…\" (CHALLENGES 2…", "gold": false}, {"id": "tests/README.md#tests", "heading": "Tests", "path": "tests/README.md", "excerpt": "Mobium's own tests of MobiumApp, run by `mobium test` — and the suite that holds the runner to its word. The format is in the [test runner guide](../docs/guides/test-runner.md). ```sh cd tests mobium test --project android # emulator-5554 MOBIUM_IOS_DEVICE=<simulator-udid> mobium test # and an iOS simulator mobium test --reporter list,junit,html && mobium show-report mobium test --ui --open # pick, run and watch on a…", "gold": false}, {"id": "skills/mobile-check/SKILL.md#mobium-mobile-automation-cli-reference", "heading": "Mobium Mobile Automation — CLI Reference", "path": "skills/mobile-check/SKILL.md", "excerpt": "The `mobium` CLI automates **mobile apps** on Android emulators and phones, and iOS simulators and iPhones. A background daemon keeps the device session alive between commands, so each command is fast after the first. ``` mobium launch com.example.shop && mobium map && mobium tap @e5 && mobium map ``` What the app is built with decides how to reach it: | App type | How | | --- | --- | | Native (Android SDK, Jetpack C…", "gold": false}], "missed": false, "facts": ["Since 2026-10-22 an Android emulator and a phone have been driven from a Windows laptop through mobium mcp, the CLI and all five clients, but Windows is not yet declared supported. ⟦2026-10-22⟧", "iOS is not possible on Windows: Mobium drives iOS through xcrun simctl and WebDriverAgent built with Xcode, which is macOS-only. ⟦macOS-only⟧", "What is left before support is the checks a person at the machine runs and seven checks whose failures are not yet explained. ⟦not yet explained⟧"], "concern": "docs/quickstart/README.md#where-it-runs still says no emulator or phone has been driven from Windows, which README.md and WINDOWS.md contradict since #270/#271; the quick-start table is stale.", "check": "Claude's reading: Windows-specific code (named-pipe daemon, Detach, process path) is in internal/device/*_windows.go and builds for windows/amd64; iOS paths call xcrun throughout internal/device. README.md#platforms~2 restates the status in brief and will likely be retrieved; the stale quick-start table is a hard negative. Verified in: internal/device/detach_windows.go:21-27, internal/device/procpath_windows.go:8, internal/device/simctl.go:282."}, {"id": "g008", "kind": "fact", "question": "In Git Bash on Windows, pushing a file to /data/local/tmp on my Android device fails because Mobium sees the path as 'C:/Program Files/Git/data/local/tmp/x'. How do I fix it?", "tags": ["troubleshooting", "test-author", "new since 7b590a4"], "gold": [{"id": "docs/WINDOWS.md#also-expected-unverified", "heading": "Also expected, unverified", "path": "docs/WINDOWS.md", "excerpt": "- **iOS is macOS-only.** `simctl` does not exist on Windows. `mobium devices` should report that as a note rather than an error — the code path already does this for a missing toolchain, but it has never been exercised with Xcode genuinely absent on a non-Mac. - Paths in `app_install` and `screenshot -o` take Windows separators; nothing obviously assumes `/`, but nothing has tested it either. - **Git Bash rewrites a …"}], "retrieved": [{"id": "CHALLENGES#361", "heading": "361. In Git Bash, a device path was rewritten into a Windows one, and refused as not absolute", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** `device-paths.sh` and `network.sh` on the Windows laptop, run under Git Bash. `mobium shell --upload x /data/local/tmp/x` answered `\"C:/Program Files/Git/data/local/tmp/x\" is not an absolute path`, and its remedy — give an absolute path — was the one the caller had given. Git Bash rewrites any argument that starts with `/` into a path under its own install folder before a Windows program sees it, measur…", "gold": false}, {"id": "docs/SETUP.md#what-mobium-installs-and-removing-it", "heading": "What Mobium installs, and removing it", "path": "docs/SETUP.md", "excerpt": "On the machine, under `~/.mobium`: | | | | --- | --- | | `uiautomator2/`, `webdriveragent/` | pinned, checksummed device agents, ~40MB, downloaded on first use | | `webdriveragent-device/` | WebDriverAgent's pinned source and one signed build per team and phone, ~150MB — only once a real iPhone has been driven | | `daemon/` | socket and PID file, removed on shutdown | On an **Android** device, the default backend ins…", "gold": false}, {"id": "docs/WINDOWS.md#also-expected-unverified", "heading": "Also expected, unverified", "path": "docs/WINDOWS.md", "excerpt": "- **iOS is macOS-only.** `simctl` does not exist on Windows. `mobium devices` should report that as a note rather than an error — the code path already does this for a missing toolchain, but it has never been exercised with Xcode genuinely absent on a non-Mac. - Paths in `app_install` and `screenshot -o` take Windows separators; nothing obviously assumes `/`, but nothing has tested it either. - **Git Bash rewrites a …", "gold": true}, {"id": "docs/RELEASE-CHECKLIST.md#android-a-booted-pixel-7-avd", "heading": "Android — a booted Pixel 7 AVD", "path": "docs/RELEASE-CHECKLIST.md", "excerpt": "Setup is in [SETUP.md](SETUP.md), or [WINDOWS.md](WINDOWS.md) for Windows. Start the emulator, then `mobium daemon stop` so nothing serves a stale build. - [ ] `mobium devices` lists the emulator - [ ] `mobium map` on the launcher returns app icons as `button`, not `link` - [ ] `mobium launch com.android.settings && mobium tap \"text=Network & internet\"` with **no sleep between them** — the implicit wait is what makes…", "gold": false}, {"id": "skills/mobile-check/SKILL.md#files", "heading": "Files", "path": "skills/mobile-check/SKILL.md", "excerpt": "```sh mobium upload invoice.pdf # where a file picker looks mobium download report.csv # what the app saved there mobium upload ./seed --device-path /data/local/tmp/seed # Android, any shell path mobium download --app com.example.shop --device-path databases/shop.db # its private data mobium download --app com.example.Shop --device-path Library/Caches -o caches # iOS container ``` - Without `--device-path` a file goe…", "gold": false}], "missed": false, "facts": ["Git Bash rewrites any argument that starts with / into a path under Git's own folder before mobium sees it, and Mobium refuses such a path naming the rewrite. ⟦Git Bash⟧", "Set MSYS2_ARG_CONV_EXCL=\"/data/;/sdcard/\" to leave device paths alone (MSYS_NO_PATHCONV=1 stops every conversion), or run from PowerShell or cmd, which never rewrite. ⟦MSYS2_ARG_CONV_EXCL ; PowerShell⟧"], "concern": "", "check": "Claude's reading: CheckDevicePath refuses a path starting with a drive letter as a Git Bash rewrite and its remedy names MSYS2_ARG_CONV_EXCL, MSYS_NO_PATHCONV=1 and PowerShell or cmd (paths.go:126-135). CHALLENGES#361 tells the same story and is a near-equal answer. Verified in: internal/device/paths.go:126-135."}, {"id": "g009", "kind": "fact", "question": "On Windows, does a Mobium daemon that started inside an SSH session keep running after I disconnect, and what makes that work?", "tags": ["behavior", "ci-engineer", "new since 7b590a4"], "gold": [{"id": "docs/WINDOWS.md#4-devicedetach-internaldevicedetachwindowsgo-and-detachunixgo", "heading": "4. `device.Detach` — `internal/device/detach_windows.go` (and `detach_unix.go`)", "path": "docs/WINDOWS.md", "excerpt": "`CREATE_NEW_PROCESS_GROUP | DETACHED_PROCESS`: a Ctrl-C does not reach the daemon, and with no console it does not die when the terminal window closes. Neither leaves a job object, and Windows' OpenSSH server kills every process of a session's job when the session ends, so `Detach` also adds `CREATE_BREAKAWAY_FROM_JOB` when the job allows it — measured over SSH on a Windows 11 laptop, where the daemon otherwise died …"}], "retrieved": [{"id": "CHALLENGES#359", "heading": "359. On Windows, the daemon died with the SSH session that started it", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** the first device run from Windows, a Windows 11 laptop driven from a Mac over OpenSSH. Every command in one session reused the daemon; the next session found \"Daemon is not running\" and no `mobium` process. The SSH server runs each session in a job object with `KILL_ON_JOB_CLOSE` (limit flags `0x2800`), and `DETACHED_PROCESS` leaves the console, not the job, so ending the session ended the daemon — and …", "gold": false}, {"id": "docs/guides/cli.md#8-the-daemon-and-running-several-at-once", "heading": "8. The daemon, and running several at once", "path": "docs/guides/cli.md", "excerpt": "The first command starts a daemon in the background, which holds the device sessions and the refs between commands, and exits after 30 idle minutes: ``` $ mobium daemon status Daemon running (pid 4156, up 8s) version 0.1.0-dev socket ~/.mobium/daemon/mobium.sock ``` (The home directory is shortened to `~` here and below.) One daemon serves one call at a time. Two runs at once — two terminals, two CI jobs, two devices…", "gold": false}, {"id": "docs/SHUTDOWN.md#1-mobium-daemon-stop-always-first", "heading": "1. `mobium daemon stop`, always first", "path": "docs/SHUTDOWN.md", "excerpt": "The daemon owns the device-side sessions: a UiAutomator2 server running as instrumentation on Android, a WebDriverAgent process on an iOS simulator. Stopping it tells both to shut down. On an iOS simulator the next session starts on the home screen, whatever app was in front: WebDriverAgent's runner takes the foreground as it launches and leaves it to the home screen. The first command says so and names `app_launch` …", "gold": false}, {"id": "CHALLENGES#28", "heading": "28. `mobium daemon stop` returned before the daemon stopped", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** hitting it three times while doing other work, then reproducing it deliberately instead of retrying past it. `daemon stop` sent the shutdown request and returned as soon as it was acknowledged, while the daemon was still tearing down — closing a UiAutomator2 session takes about a second. The next command's auto-start then found the socket still held, failed to bind, and sat waiting ten seconds for a dae…", "gold": false}], "missed": true, "facts": ["Windows' OpenSSH server kills every process in a session's job when the session ends, which used to take the daemon with it. ⟦OpenSSH⟧", "Detach now adds CREATE_BREAKAWAY_FROM_JOB when the job allows breakaway, so the daemon outlives the session. ⟦CREATE_BREAKAWAY_FROM_JOB⟧"], "concern": "", "check": "Claude's reading: Detach sets CREATE_NEW_PROCESS_GROUP|DETACHED_PROCESS and adds CREATE_BREAKAWAY_FROM_JOB only when JOB_OBJECT_LIMIT_BREAKAWAY_OK is set (detach_windows.go:21-40); the auto-started daemon goes through it (daemon_client.go:119). CHALLENGES#359 is the defect behind it and an equally good source. Verified in: internal/device/detach_windows.go:13-40, cmd/mobium/daemon_client.go:114-119."}, {"id": "g010", "kind": "multi", "question": "My Android emulator on a Windows host has frozen: adb still lists it but every shell call times out. Will mobium shutdown end it, and how?", "tags": ["behavior", "test-author", "new since 7b590a4"], "gold": [{"id": "docs/SHUTDOWN.md#2-simulators-then-emulators", "heading": "2. Simulators, then emulators", "path": "docs/SHUTDOWN.md", "excerpt": "```sh xcrun simctl shutdown <udid> # or `all` adb -s emulator-5554 emu kill ``` `mobium shutdown <serial | avd | udid | simulator>` does this for one device in the same order — its session ended, then the device — and returns once the device is gone. It ends only its own daemon's session and does not check for other daemons on the device, so stop those first (`MOBIUM_SESSION=<name> mobium daemon stop` for each). A **…"}, {"id": "CHALLENGES#360", "heading": "360. On Windows, a frozen emulator could not be shut down, and the error said to shut it down", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** a sweep of the checks on the Windows laptop's emulator, which froze under `network.sh` twice — adb listed it as `device` and every shell call timed out. Every check after it was refused as \"not answering adb\", and the refusal's remedy was 285's: `mobium shutdown emulator-5554`. On Windows that answered \"ending an emulator by its process is not done on Windows\", and `boot.sh`, which shuts its AVD down fi…"}], "retrieved": [{"id": "CHALLENGES#360", "heading": "360. On Windows, a frozen emulator could not be shut down, and the error said to shut it down", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** a sweep of the checks on the Windows laptop's emulator, which froze under `network.sh` twice — adb listed it as `device` and every shell call timed out. Every check after it was refused as \"not answering adb\", and the refusal's remedy was 285's: `mobium shutdown emulator-5554`. On Windows that answered \"ending an emulator by its process is not done on Windows\", and `boot.sh`, which shuts its AVD down fi…", "gold": true}, {"id": "CHALLENGES#285", "heading": "285. A frozen emulator was told to try the other driver, and could not be shut down", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** the lead 284 left. An emulator stopped with SIGSTOP timed out on `adb shell` as a session opened, and the error added \"To run without the UiAutomator2 server, use --driver uiautomator\" — a driver that goes through the same adb. The remedy that would help, a restart, did not work either: `mobium shutdown` on the frozen emulator ran six minutes and ended \"read response: i/o timeout\" with the emulator stil…", "gold": false}, {"id": "docs/SHUTDOWN.md#2-simulators-then-emulators", "heading": "2. Simulators, then emulators", "path": "docs/SHUTDOWN.md", "excerpt": "```sh xcrun simctl shutdown <udid> # or `all` adb -s emulator-5554 emu kill ``` `mobium shutdown <serial | avd | udid | simulator>` does this for one device in the same order — its session ended, then the device — and returns once the device is gone. It ends only its own daemon's session and does not check for other daemons on the device, so stop those first (`MOBIUM_SESSION=<name> mobium daemon stop` for each). A **…", "gold": true}, {"id": "docs/WINDOWS.md#windows-support", "heading": "Windows support", "path": "docs/WINDOWS.md", "excerpt": "**Status: devices driven from Windows since 2026-10-22; not yet declared supported.** On a Windows 11 laptop (24H2, i7-8565U, 8 GB), an Android 15 emulator and a Pixel 8 Pro over USB were driven through `mobium mcp`, the CLI over the named pipe, and all five clients, which passed every step on both. A sweep of the checks on the emulator found six things, all fixed: the daemon dying with the SSH session that started i…", "gold": false}, {"id": "CHALLENGES#93", "heading": "93. Every Android session ended by leaving a crash report on the device", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** `app_crashes` itself, run on a Pixel 8 Pro (Android 17) while hardening it: of the phone's recorded crashes, most were `io.appium.uiautomator2.server` — `RuntimeException: Error while disconnecting UiAutomation`, caused by `DeadObjectException` — each one at the moment a Mobium session had ended. Teardown cancelled the host of `adb shell am instrument`, which takes the UiAutomation connection down with …", "gold": false}], "missed": false, "facts": ["mobium shutdown gives adb emu kill ten seconds, then ends the process the emulator's discovery file names once that process is an emulator by name. ⟦discovery file⟧", "On Windows this now works too: the process is read with QueryFullProcessImageName and ended, where it used to be refused. ⟦QueryFullProcessImageName⟧"], "concern": "docs/SHUTDOWN.md#2-simulators-then-emulators still ends with 'On Windows it does not end the process, and says so', but #268 (CHALLENGES 360) made killEmulatorProcess work on Windows (boot.go:400-428, procpath_windows.go); SHUTDOWN.md is stale.", "check": "Claude's reading: emuKillWait is 10s (boot.go:32) and killEmulatorProcess ends the discovery file's pid when its image name contains qemu or emulator, on every OS (boot.go:400-428). The SHUTDOWN.md section gives the mechanism and CHALLENGES 360 gives Windows; a right answer must say it works on Windows despite the stale line. Verified in: internal/device/boot.go:32, internal/device/boot.go:250-270, internal/device/boot.go:400-428, internal/device/procpath_windows.go:8-20."}, {"id": "g011", "kind": "multi", "question": "I run two Android emulators at once on one machine and want a test run on each in parallel without the two slowing each other down. How do I set that up?", "tags": ["how-to", "ci-engineer"], "gold": [{"id": "docs/SETUP.md#running-two-at-once", "heading": "Running two at once", "path": "docs/SETUP.md", "excerpt": "```sh emulator -avd mobium-test -no-snapshot-save -no-boot-anim & # 5554 emulator -avd mobium-test-17 -no-snapshot-save -no-boot-anim -port 5556 & # 5556 ``` Then pass `--device emulator-5556` to every command, or give a client the device option. With two ready, a call that names no device is refused, so `MOBIUM_SESSION` alone does not choose one: it gives each run its own daemon ([parallel runs](#parallel-runs)), an…"}, {"id": "docs/SETUP.md#parallel-runs", "heading": "Parallel runs", "path": "docs/SETUP.md", "excerpt": "**Give each run that drives a device at the same time as another its own daemon.** One daemon serves one call at a time, across every device it holds, so two runs sharing one go at the pace of the slower device. Measured on 2026-09-27, 15 `map` calls on each of an Android 15 emulator and an iPhone 17 Pro simulator at once: | | the emulator's 15 calls | | --- | --- | | alone | 0.3s | | sharing a daemon with the simula…"}], "retrieved": [{"id": "docs/SETUP.md#running-two-at-once", "heading": "Running two at once", "path": "docs/SETUP.md", "excerpt": "```sh emulator -avd mobium-test -no-snapshot-save -no-boot-anim & # 5554 emulator -avd mobium-test-17 -no-snapshot-save -no-boot-anim -port 5556 & # 5556 ``` Then pass `--device emulator-5556` to every command, or give a client the device option. With two ready, a call that names no device is refused, so `MOBIUM_SESSION` alone does not choose one: it gives each run its own daemon ([parallel runs](#parallel-runs)), an…", "gold": true}, {"id": "docs/SETUP.md#parallel-runs", "heading": "Parallel runs", "path": "docs/SETUP.md", "excerpt": "**Give each run that drives a device at the same time as another its own daemon.** One daemon serves one call at a time, across every device it holds, so two runs sharing one go at the pace of the slower device. Measured on 2026-09-27, 15 `map` calls on each of an Android 15 emulator and an iPhone 17 Pro simulator at once: | | the emulator's 15 calls | | --- | --- | | alone | 0.3s | | sharing a daemon with the simula…", "gold": true}, {"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": false}, {"id": "docs/guides/test-runner.md#6-more-than-one-device", "heading": "6. More than one device", "path": "docs/guides/test-runner.md", "excerpt": "Add a project per device. An iOS simulator's id is one Mac's, and a phone's is somebody's, so a project can take its device from the environment, and an unset variable is refused by name before any test runs: ```json { \"testDir\": \"tests\", \"projects\": [ {\"name\": \"android\", \"device\": \"emulator-5554\"}, {\"name\": \"ios\", \"device\": \"${MOBIUM_IOS_DEVICE}\", \"driver\": \"wda\"} ] } ``` ```sh MOBIUM_IOS_DEVICE=<simulator-udid> mob…", "gold": false}, {"id": "docs/ROADMAP.md#under-consideration", "heading": "Under consideration", "path": "docs/ROADMAP.md", "excerpt": "- **Locators for when there is no ref** (written down 2026-10-12). A ref from `map` lasts one map, so an agent has one and a `mobium test` file does not: a hand-written test has the flat `kind=value` locators — text, label, testid, role, class, path, narrowed by `,role=` — which match one element or are refused. That is right on a form and leaves nothing durable on a list. Every Ice Cubes post has a \"…\" (CHALLENGES 2…", "gold": false}], "missed": false, "facts": ["With two devices ready, a call that names no device is refused, so each run names its device with --device (or the client's device option); a second emulator gets its own console port with -port 5556. ⟦-port 5556⟧", "Give each run its own daemon by naming it with MOBIUM_SESSION, since one daemon serves one call at a time across every device it holds. ⟦MOBIUM_SESSION⟧", "Keep the session name short: it is part of a socket path capped at about 104 bytes. ⟦104⟧"], "concern": "", "check": "Claude's reading: adb.go:429 refuses with 'N devices are ready — pick one with --device'; the daemon serializes handlers with one mutex (daemon.go:30); paths.go names the socket from MOBIUM_SESSION and guards the 104-byte limit. docs/guides/cli.md#8 also explains MOBIUM_SESSION and is a near miss. Verified in: internal/device/adb.go:429, internal/daemon/daemon.go:30, internal/paths/paths.go:44-48, internal/paths/paths.go:77."}, {"id": "g012", "kind": "fact", "question": "If I leave Mobium alone for a while, does the background process it started keep running forever?", "tags": ["behavior", "new-user"], "gold": [{"id": "docs/guides/cli.md#8-the-daemon-and-running-several-at-once", "heading": "8. The daemon, and running several at once", "path": "docs/guides/cli.md", "excerpt": "The first command starts a daemon in the background, which holds the device sessions and the refs between commands, and exits after 30 idle minutes: ``` $ mobium daemon status Daemon running (pid 4156, up 8s) version 0.1.0-dev socket ~/.mobium/daemon/mobium.sock ``` (The home directory is shortened to `~` here and below.) One daemon serves one call at a time. Two runs at once — two terminals, two CI jobs, two devices…"}], "retrieved": [{"id": "docs/SHUTDOWN.md#1-mobium-daemon-stop-always-first", "heading": "1. `mobium daemon stop`, always first", "path": "docs/SHUTDOWN.md", "excerpt": "The daemon owns the device-side sessions: a UiAutomator2 server running as instrumentation on Android, a WebDriverAgent process on an iOS simulator. Stopping it tells both to shut down. On an iOS simulator the next session starts on the home screen, whatever app was in front: WebDriverAgent's runner takes the foreground as it launches and leaves it to the home screen. The first command says so and names `app_launch` …", "gold": false}, {"id": "docs/SHUTDOWN.md#a-leak-this-actually-caught", "heading": "A leak this actually caught", "path": "docs/SHUTDOWN.md", "excerpt": "A backgrounded wait loop of mine — `until adb shell getprop ...` against two attached devices, so it could never succeed — was still spinning `sleep 3` forty-two minutes later. It was reported as a *second daemon*, because its command line contained `bin/mobium daemon stop`. Two lessons in one process: a loop waiting on a condition that cannot be met runs forever, and a check matching command-line text will find your…", "gold": false}, {"id": "docs/SHUTDOWN.md#what-to-leave-alone", "heading": "What to leave alone", "path": "docs/SHUTDOWN.md", "excerpt": "- **`~/.mobium/uiautomator2` and `~/.mobium/webdriveragent`** — about 40MB of pinned, checksummed agents. Deleting them only costs the next run a download. - **A physical device.** Releasing the session is enough; unplugging is yours. USB and wireless debugging stay on until you turn them off — a network device's link is ended by `--quit`, its debugging setting is not. - **Anything you did not start.** Check what a p…", "gold": false}, {"id": "docs/guides/graybox.md#when-the-app-is-not-waited-for", "heading": "When the app is not waited for", "path": "docs/guides/graybox.md", "excerpt": "Three things end a wait early, and the result says which, so a check that did not run never reads as one that passed: - **The app went to the background.** The library says `away` and `back`; while the app is away, an action elsewhere is not held up by it. - **The app stopped saying it is busy.** Busy is a lease: while work is in flight the library restates the count every half second, from a native timer that a busy…", "gold": false}, {"id": "docs/guides/cli.md#8-the-daemon-and-running-several-at-once", "heading": "8. The daemon, and running several at once", "path": "docs/guides/cli.md", "excerpt": "The first command starts a daemon in the background, which holds the device sessions and the refs between commands, and exits after 30 idle minutes: ``` $ mobium daemon status Daemon running (pid 4156, up 8s) version 0.1.0-dev socket ~/.mobium/daemon/mobium.sock ``` (The home directory is shortened to `~` here and below.) One daemon serves one call at a time. Two runs at once — two terminals, two CI jobs, two devices…", "gold": true}], "missed": false, "facts": ["The first command starts a daemon in the background that holds the device sessions and refs, and it exits after 30 idle minutes. ⟦30 idle minutes⟧", "mobium daemon stop stops it, ending its sessions."], "concern": "", "check": "Claude's reading: the auto-start passes --idle-timeout 30m (daemon_client.go:19, 114) and watchIdle shuts the daemon down after that (daemon.go:184-210). The question avoids the word daemon on purpose. Verified in: cmd/mobium/daemon_client.go:16-19, cmd/mobium/daemon_client.go:114, internal/daemon/daemon.go:184-210."}, {"id": "g013", "kind": "multi", "question": "I have two lab Macs with emulators on them. How do I spread my test runs across both machines' devices, and what does each lab Mac need for that?", "tags": ["how-to", "ci-engineer"], "gold": [{"id": "docs/guides/grid.md#2-a-grid", "heading": "2. A grid", "path": "docs/guides/grid.md", "excerpt": "`MOBIUM_GRID=node1,node2` names the nodes. At a run's first call, mobium asks each node for its devices and which are held, takes the first free one that matches what the run asked for, and connects to its node as `--remote` would. `mobium grid status` shows the same answers routing reads: ``` $ MOBIUM_GRID=localhost mobium grid status NODE DEVICE PLATFORM OS MODEL STATE HELD BY localhost emulator-5554 android Androi…"}, {"id": "docs/guides/grid.md#what-a-node-needs", "heading": "What a node needs", "path": "docs/guides/grid.md", "excerpt": "A node is any Mac or Linux machine with devices and mobium on it. | | | | --- | --- | | **SSH without a prompt** | key-based login from your machine to the node. mobium runs SSH with `BatchMode=yes`, since a password prompt would land in the stream a client speaks. `MOBIUM_SSH` replaces the `ssh` command, options and all — `ssh -i ~/.ssh/node_key` | | **mobium on the node** | reachable by the node's non-interactive s…"}], "retrieved": [{"id": "docs/guides/grid.md#quick-start-another-machines-devices-and-a-grid", "heading": "Quick start: another machine's devices, and a grid", "path": "docs/guides/grid.md", "excerpt": "Two steps, the second built on the first: - **`--remote`** drives the devices plugged into one other machine, over SSH — with any command and any client, and no change to its code. - **`MOBIUM_GRID`** spreads runs over several machines' devices, with no hub: each run gets the first free device that matches, and waits when there is none. Every command and every line of output below is what mobium printed on 2026-09-28…", "gold": false}, {"id": "docs/guides/test-runner.md#6-more-than-one-device", "heading": "6. More than one device", "path": "docs/guides/test-runner.md", "excerpt": "Add a project per device. An iOS simulator's id is one Mac's, and a phone's is somebody's, so a project can take its device from the environment, and an unset variable is refused by name before any test runs: ```json { \"testDir\": \"tests\", \"projects\": [ {\"name\": \"android\", \"device\": \"emulator-5554\"}, {\"name\": \"ios\", \"device\": \"${MOBIUM_IOS_DEVICE}\", \"driver\": \"wda\"} ] } ``` ```sh MOBIUM_IOS_DEVICE=<simulator-udid> mob…", "gold": false}, {"id": "docs/ROADMAP.md#under-consideration", "heading": "Under consideration", "path": "docs/ROADMAP.md", "excerpt": "- **Locators for when there is no ref** (written down 2026-10-12). A ref from `map` lasts one map, so an agent has one and a `mobium test` file does not: a hand-written test has the flat `kind=value` locators — text, label, testid, role, class, path, narrowed by `,role=` — which match one element or are refused. That is right on a form and leaves nothing durable on a list. Every Ice Cubes post has a \"…\" (CHALLENGES 2…", "gold": false}, {"id": "docs/SETUP.md#running-two-at-once", "heading": "Running two at once", "path": "docs/SETUP.md", "excerpt": "```sh emulator -avd mobium-test -no-snapshot-save -no-boot-anim & # 5554 emulator -avd mobium-test-17 -no-snapshot-save -no-boot-anim -port 5556 & # 5556 ``` Then pass `--device emulator-5556` to every command, or give a client the device option. With two ready, a call that names no device is refused, so `MOBIUM_SESSION` alone does not choose one: it gives each run its own daemon ([parallel runs](#parallel-runs)), an…", "gold": false}, {"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": false}], "missed": true, "facts": ["Set MOBIUM_GRID=node1,node2; at a run's first call mobium asks each node for its devices and takes the first free one that matches. ⟦MOBIUM_GRID⟧", "Each node needs key-based SSH with no prompt (mobium runs SSH with BatchMode=yes) and mobium reachable by its non-interactive shell, set with MOBIUM_REMOTE_BIN if needed. ⟦BatchMode=yes ; MOBIUM_REMOTE_BIN⟧", "On a Mac node, Remote Login must be on. ⟦Remote Login⟧"], "concern": "", "check": "Claude's reading: grid.go splits MOBIUM_GRID on commas and remote.go adds -o BatchMode=yes and honors MOBIUM_SSH and MOBIUM_REMOTE_BIN. SETUP.md#a-grid and SETUP.md#driving-another-machines-devices say most of this too; Remote Login is only in the grid guide. Verified in: cmd/mobium/grid.go:23-40, cmd/mobium/remote.go:151-162, cmd/mobium/remote.go:183-186."}, {"id": "g014", "kind": "fact", "question": "A teammate's phone is plugged into one of our grid machines. Could a grid test run end up installing and tapping on it?", "tags": ["behavior", "ci-engineer"], "gold": [{"id": "docs/guides/grid.md#phones-on-a-grid", "heading": "Phones on a grid", "path": "docs/guides/grid.md", "excerpt": "A phone plugged into a node is usually somebody's, and a grid run would install on it, tap and change its settings. So the grid lends a physical device only when **the node's own** environment sets `MOBIUM_GRID_PHONES=1` — the node's choice, never the caller's. Until then a phone is listed as not offered, as above, and a run that asks for it by serial is told so. What a grid shows about a phone is its model, never it…"}], "retrieved": [{"id": "docs/guides/grid.md#phones-on-a-grid", "heading": "Phones on a grid", "path": "docs/guides/grid.md", "excerpt": "A phone plugged into a node is usually somebody's, and a grid run would install on it, tap and change its settings. So the grid lends a physical device only when **the node's own** environment sets `MOBIUM_GRID_PHONES=1` — the node's choice, never the caller's. Until then a phone is listed as not offered, as above, and a run that asks for it by serial is told so. What a grid shows about a phone is its model, never it…", "gold": true}, {"id": "docs/SETUP.md#a-grid", "heading": "A grid", "path": "docs/SETUP.md", "excerpt": "**`MOBIUM_GRID=node1,node2` spreads runs over several machines' devices**, with no hub. At a run's first call — which is where it says what it wants: a serial, or `platform` when it starts a session — mobium asks every node over SSH for its devices and which of them are held, takes the first free one that matches, and connects to its node as `--remote` would. The lease that keeps a device to one run lives on the node…", "gold": false}, {"id": "docs/guides/grid.md#quick-start-another-machines-devices-and-a-grid", "heading": "Quick start: another machine's devices, and a grid", "path": "docs/guides/grid.md", "excerpt": "Two steps, the second built on the first: - **`--remote`** drives the devices plugged into one other machine, over SSH — with any command and any client, and no change to its code. - **`MOBIUM_GRID`** spreads runs over several machines' devices, with no hub: each run gets the first free device that matches, and waits when there is none. Every command and every line of output below is what mobium printed on 2026-09-28…", "gold": false}, {"id": "docs/guides/grid.md#4-tests-on-a-grid", "heading": "4. Tests on a grid", "path": "docs/guides/grid.md", "excerpt": "`mobium test` goes through a grid the same way. A project that names no device asks for one by `platform`, and with `MOBIUM_GRID` set each project gets a connection of its own, which leases a device before any test runs and releases it when the run ends: ```json { \"testDir\": \"tests\", \"projects\": [ {\"name\": \"android-a\", \"platform\": \"android\"}, {\"name\": \"android-b\", \"platform\": \"android\"} ] } ``` ``` $ MOBIUM_GRID=loca…", "gold": false}, {"id": "docs/guides/grid.md#what-stays-local", "heading": "What stays local", "path": "docs/guides/grid.md", "excerpt": "`daemon`, `doctor` and `mcp` are about this machine and ignore `--remote`. One device still belongs to one run at a time, on a node as anywhere: a test run holds each project's device for the whole run, so a grid with two free devices serves two projects at once, not more.", "gold": false}], "missed": false, "facts": ["The grid lends a physical device only when the node's own environment sets MOBIUM_GRID_PHONES=1, the node's choice, never the caller's; until then it is listed as not offered. ⟦MOBIUM_GRID_PHONES=1⟧", "A grid shows a phone's model, never its name."], "concern": "", "check": "Claude's reading: grid.go marks a device Offered only if it is an emulator/simulator or the node's MOBIUM_GRID_PHONES is 1 (line 96) and tells a run asking for one so (line 211). SETUP.md#a-grid~1 also covers phones but not the model-not-name point. Verified in: cmd/mobium/grid.go:60-96, cmd/mobium/grid.go:211."}, {"id": "g015", "kind": "fact", "question": "How do I connect my Fire TV so Mobium can drive it over Wi-Fi from my Mac, and what do I do when adb connect says \"No route to host\" although the TV answers ping?", "tags": ["how-to", "new-user"], "gold": [{"id": "docs/SETUP.md#over-wi-fi", "heading": "Over Wi-Fi", "path": "docs/SETUP.md", "excerpt": "Android 11+. The phone and the Mac must be on the same network. 1. **Developer options → Wireless debugging → on.** 2. **\"Pair device with pairing code\"** — it shows an address and a six-digit code. Both expire in about a minute. 3. Find the address without reading it off the screen: ```sh adb mdns services # adb-XXXXXXXX-abcdef _adb-tls-pairing._tcp 192.0.2.20:33169 # adb-XXXXXXXX-abcdef _adb-tls-connect._tcp 192.0.2.20…"}], "retrieved": [{"id": "docs/SETUP.md#over-wi-fi", "heading": "Over Wi-Fi", "path": "docs/SETUP.md", "excerpt": "Android 11+. The phone and the Mac must be on the same network. 1. **Developer options → Wireless debugging → on.** 2. **\"Pair device with pairing code\"** — it shows an address and a six-digit code. Both expire in about a minute. 3. Find the address without reading it off the screen: ```sh adb mdns services # adb-XXXXXXXX-abcdef _adb-tls-pairing._tcp 192.0.2.20:33169 # adb-XXXXXXXX-abcdef _adb-tls-connect._tcp 192.0.2.20…", "gold": true}, {"id": "docs/SHUTDOWN.md#a-tv-or-anything-reached-by-adb-connect", "heading": "A TV, or anything reached by `adb connect`", "path": "docs/SHUTDOWN.md", "excerpt": "A Fire TV is reached over Wi-Fi with `adb connect <tv>:5555`, after ADB debugging is turned on in its Developer Options. It is somebody's living-room TV, so the device checks above run on it as on a phone, and four more run on every device: - **A screen mirror's server.** scrcpy was how the TV was watched while it was measured, and its server streams the screen off the device for as long as it runs. On the device it …", "gold": false}, {"id": "docs/ROADMAP.md#under-consideration", "heading": "Under consideration", "path": "docs/ROADMAP.md", "excerpt": "- **Locators for when there is no ref** (written down 2026-10-12). A ref from `map` lasts one map, so an agent has one and a `mobium test` file does not: a hand-written test has the flat `kind=value` locators — text, label, testid, role, class, path, narrowed by `,role=` — which match one element or are refused. That is right on a form and leaves nothing durable on a list. Every Ice Cubes post has a \"…\" (CHALLENGES 2…", "gold": false}], "missed": false, "facts": ["Turn on ADB Debugging in the Fire TV's Developer Options (shown under Settings > Device & Software after selecting the device name seven times in About), then run adb connect <tv>:5555 with the TV's IPv4 address and accept the prompt on the TV; a Fire TV has no pairing step. ⟦ADB Debugging ; 5555⟧", "\"No route to host\" while ping works is macOS Local Network privacy silently blocking an adb server that a background process started; run adb kill-server && adb connect <tv>:5555 from a Terminal window so macOS asks, and allow it. ⟦Local Network ; adb kill-server⟧"], "concern": "", "check": "Claude's reading: replaces a draft that duplicated g074 (simulator audio setup). Both facts are in SETUP.md#over-wi-fi; the Local Network trap is macOS behavior, measured on the Fire TV and recorded in the doc, not something the code can show, and the code's own part is the disconnect-then-connect before it reports a network device missing (internal/device/adb.go:358). SHUTDOWN.md's TV section repeats the trap and could also count. Verified in: internal/device/adb.go:358."}, {"id": "g016", "kind": "fact", "question": "How do I set up an Apple TV simulator for Mobium, and how do I move around in it given that it has no touch screen?", "tags": ["how-to", "test-author"], "gold": [{"id": "docs/SETUP.md#an-apple-tv-simulator", "heading": "An Apple TV simulator", "path": "docs/SETUP.md", "excerpt": "Verified on a tvOS 26.5 simulator (Apple TV 4K, 3rd generation, at 1080p) with Xcode 26.6, on 2026-10-09. The tvOS platform is a separate download: ```sh xcodebuild -downloadPlatform tvOS # or Xcode > Settings > Components xcrun simctl create \"Apple TV\" \\ com.apple.CoreSimulator.SimDeviceType.Apple-TV-4K-3rd-generation-1080p \\ com.apple.CoreSimulator.SimRuntime.tvOS-26-5 xcrun simctl boot <udid> && open -a Simulator …"}], "retrieved": [{"id": "docs/SETUP.md#an-apple-tv-simulator", "heading": "An Apple TV simulator", "path": "docs/SETUP.md", "excerpt": "Verified on a tvOS 26.5 simulator (Apple TV 4K, 3rd generation, at 1080p) with Xcode 26.6, on 2026-10-09. The tvOS platform is a separate download: ```sh xcodebuild -downloadPlatform tvOS # or Xcode > Settings > Components xcrun simctl create \"Apple TV\" \\ com.apple.CoreSimulator.SimDeviceType.Apple-TV-4K-3rd-generation-1080p \\ com.apple.CoreSimulator.SimRuntime.tvOS-26-5 xcrun simctl boot <udid> && open -a Simulator …", "gold": true}, {"id": "CHALLENGES#296", "heading": "296. On an Apple TV the runner kept the screen, and every press went to it", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** the first Apple TV simulator session (tvOS 26.5), 2026-10-09. The first daemon's launch put MobiumTV in front and every press worked. After a daemon restart `current` named WebDriverAgent's own runner, `map` found nothing, and two D-pad presses reported that nothing on screen had focus: tvOS's runner answers from the foreground and stays there, as an iPad's does before it answers at all (147). Home, pre…", "gold": false}, {"id": "docs/RELEASE-CHECKLIST.md#ios-a-booted-iphone-simulator", "heading": "iOS — a booted iPhone simulator", "path": "docs/RELEASE-CHECKLIST.md", "excerpt": "- [ ] `mobium --driver wda map` on the home screen returns icons - [ ] Wait for something already on screen, and across a cold app launch - [ ] `mobium scroll-to` reaches a Settings row below the fold, and tapping it opens that screen - [ ] `mobium grant com.apple.Preferences photos` succeeds and says it could not be verified - [ ] `mobium grant <anything> camera` is refused, naming the missing service - [ ] Coordina…", "gold": false}, {"id": "docs/BACK.md#ios", "heading": "iOS", "path": "docs/BACK.md", "excerpt": "iOS has no system back. Going back is the app's: a navigation bar's back button, and, for a `UINavigationController`, a swipe. Mobium refuses `press back` there by design (it is not an event iOS sends); `press back --gesture` sends the swipe, starting in the navigation bar, since the measurements below found a swipe over a list row taken by the row ([In Mobium](#in-mobium)). | | MobiumApp | Control | | --- | --- | --…", "gold": false}, {"id": "docs/SETUP.md#running-headless", "heading": "Running headless", "path": "docs/SETUP.md", "excerpt": "Add `-no-window`. Everything mobium does works unchanged, screenshots included — `adb exec-out screencap` reads the framebuffer, not the window: ```sh emulator -avd mobium-test -no-window -no-snapshot-save -no-boot-anim -no-audio & ``` **Unlike an iOS simulator, the window cannot be attached afterwards.** `simctl boot` is always headless and `open -a Simulator` shows it later; the Android emulator decides at launch, …", "gold": false}], "missed": false, "facts": ["The tvOS platform is a separate download: xcodebuild -downloadPlatform tvOS, then create and boot an Apple TV simulator; the first command installs WebDriverAgent's tvOS runner. ⟦-downloadPlatform tvOS⟧", "It is driven with the remote: press dpad-up/down/left/right and select, back is the Menu button; tap and other gestures are refused. ⟦dpad-up ; select⟧"], "concern": "", "check": "Claude's reading: remote.go and alerts.go refuse touches on an Apple TV because it has no touch screen, and buttons.go maps back to the remote's Menu button on tvOS. README.md#platforms~2 summarizes TVs and is a near miss without the setup commands. Verified in: internal/agent/remote.go:12, internal/mobiumdriver/buttons.go:194, internal/mobiumdriver/alerts.go:73."}, {"id": "g017", "kind": "fact", "question": "Does Mobium work with Wear OS watches, and what can't it do on one yet?", "tags": ["support", "test-author"], "gold": [{"id": "README.md#platforms", "heading": "Platforms", "path": "README.md", "excerpt": "Verified on devices, not only compiled: a Pixel 7 emulator on Android 15 and Android 17, a Pixel 8 Pro on Android 17, an iPhone 17 Pro simulator on iOS 26.5, and an iPhone 15 Plus on iOS 26.6.2. The end-to-end flows in [docs/checks/](docs/checks/) each drive a real device and assert on what happened rather than on an exit code. | | `uiautomator2` | `uiautomator` | `wda` | | --- | --- | --- | --- | | platform | Androi…"}], "retrieved": [{"id": "docs/SETUP.md#a-wear-os-emulator", "heading": "A Wear OS emulator", "path": "docs/SETUP.md", "excerpt": "Wear OS images are on the stable channel, Wear OS 3 to 6.1, and 7.0 at API 37. A watch is driven as any Android device, by the same backends: ```sh sdkmanager \"system-images;android-35-ext15;android-wear;arm64-v8a\" # Wear OS 5.1 avdmanager create avd -n mobium-wear -d wearos_large_round \\ -k \"system-images;android-35-ext15;android-wear;arm64-v8a\" emulator -avd mobium-wear -port 5558 -no-snapshot-load -no-boot-anim & …", "gold": false}, {"id": "docs/THREAT-MODEL.md#what-it-is-for-this-purpose", "heading": "What it is, for this purpose", "path": "docs/THREAT-MODEL.md", "excerpt": "- **Mobium does not run a model.** It is the hands of one: an agent, or a script, calls tools; Mobium acts on a device and reports what it saw. - **Everything it reports comes from apps it does not control.** `map` labels, `text`, `source`, WebView `eval` results, notifications, device logs, crash reports, the clipboard. Any app or page can put text there, including text written to be read by an agent as an instructi…", "gold": false}, {"id": "docs/ACCESSIBILITY.md#assistive-technology", "heading": "Assistive technology", "path": "docs/ACCESSIBILITY.md", "excerpt": "What Mobium can do with the tools disabled people use to operate a phone or a TV: screen readers, speech that drives the screen, and voice assistants that do a task without it. What was measured, what it found, and the plan to build on it, in the order it should be built. Each step names the control that shows it can fail before its result counts. **Status on 2026-10-20.** TalkBack stays on through a session (CHALLEN…", "gold": false}, {"id": "docs/ROADMAP.md#next", "heading": "Next", "path": "docs/ROADMAP.md", "excerpt": "- **Found reviewing the docs evaluation's golden set** (written down 2026-10-12, read from the code, not yet run on a device): 1. ~~**On an Apple TV, a dialog of three or more buttons named a remedy that cannot work.**~~ Done 2026-10-12, CHALLENGES 313: `app_alert` asks the driver whether the device is answered by its remote before choosing accept, dismiss or a button, and on a TV every one of them is refused naming …", "gold": false}, {"id": "docs/WINDOWS.md#what-is-expected-to-work-already", "heading": "What is expected to work already", "path": "docs/WINDOWS.md", "excerpt": "Never run against a device on Windows — that is the point of this exercise — but these have no platform-specific code: - the tool layer, the driver interface, the tree parser, locators and refs - `adb` discovery and every Android command, including port forwarding - the UiAutomator2 backend, its APK download and checksum verification - WebView contexts over CDP - **`mobium mcp`**, which runs the tool layer in-process…", "gold": false}], "missed": true, "facts": ["Wear OS is driven by the Android backends with nothing added, verified on a Wear OS 5.1 emulator, with swiping right as a watch's back. ⟦Wear OS 5.1⟧", "Not yet a real watch, and not the crown: press has no rotary input. ⟦rotary⟧"], "concern": "", "check": "Claude's reading: the press button list in schema.go has D-pad, select, back and media keys and no rotary or crown input; nothing in internal/ handles a crown. SETUP.md#a-wear-os-emulator says 'the crown has no command yet' but not that a real watch is untested, so README is the sufficient section. Verified in: internal/agent/schema.go:1438, internal/mobiumdriver/buttons.go:37."}, {"id": "g018", "kind": "fact", "question": "mobium doctor printed several 'note' lines on my machine. Does that mean my setup is broken, and will doctor fail a CI setup step because of them?", "tags": ["behavior", "ci-engineer"], "gold": [{"id": "docs/SETUP.md#setting-up-devices", "heading": "Setting up devices", "path": "docs/SETUP.md", "excerpt": "Everything Mobium needs on the machine and on the device, for all four kinds of target. Written from doing it: every trap below cost real time here, and most of them report something that names the wrong cause. **Run `mobium doctor` first.** It checks the whole list without needing a device, and exits non-zero if it found something: ``` ok adb Android Debug Bridge version 1.0.41 at /opt/homebrew/bin/adb note android …"}], "retrieved": [{"id": "docs/SETUP.md#setting-up-devices", "heading": "Setting up devices", "path": "docs/SETUP.md", "excerpt": "Everything Mobium needs on the machine and on the device, for all four kinds of target. Written from doing it: every trap below cost real time here, and most of them report something that names the wrong cause. **Run `mobium doctor` first.** It checks the whole list without needing a device, and exits non-zero if it found something: ``` ok adb Android Debug Bridge version 1.0.41 at /opt/homebrew/bin/adb note android …", "gold": true}, {"id": "CHALLENGES#32", "heading": "32. `doctor` could not run in the situation it exists for", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** testing it against a deliberately broken environment, which is the only way this would ever have shown up. The first version of `mobium doctor` went through the daemon like every other command. Pointed at a `MOBIUM_HOME` long enough to push the Unix socket path over the OS limit, it failed with *that* error instead of producing a report — the error it exists to explain. A diagnostic that only works on a…", "gold": false}, {"id": "docs/guides/test-runner.md#7-in-ci", "heading": "7. In CI", "path": "docs/guides/test-runner.md", "excerpt": "The command a CI job runs, and what it publishes: ```sh mobium test --reporter list,junit,html # junit: mobium-report/junit.xml — for the CI's test report # html: mobium-report/ — as a build artifact ``` The exit status is 0 when every test passed or was flaky, 1 when any failed, and one of mobium's own codes when the run could not start — 2 for a bad file or an unset device, 3 for no device — so a job can tell \"the …", "gold": false}, {"id": "CHALLENGES#if-you-are-seeing-something-odd-start-here", "heading": "If you are seeing something odd, start here", "path": "docs/CHALLENGES.md", "excerpt": "Symptom first, because that is what you have. Every row points at the entry with the evidence. | What you are seeing | What it usually is | | --- | --- | | A command \"succeeded\" and nothing changed | Nothing here reports failure by exit code. `pm grant`, `simctl privacy`, `am start`, `adb uninstall` and `uiautomator dump` each fail differently — 25, 26, 27, 30 | | An element is on screen but a locator says it is not …", "gold": false}, {"id": "skills/mobile-check/SKILL.md#when-something-fails-for-no-good-reason", "heading": "When something fails for no good reason", "path": "skills/mobile-check/SKILL.md", "excerpt": "`mobium doctor` checks the environment and needs no device — that is the point. Several of the toolchain's own errors name the wrong cause, so run it before believing one of them. It exits non-zero if it found anything.", "gold": false}], "missed": false, "facts": ["A note means something is missing that is only needed for part of the job, such as no Xcode on a machine doing Android work, which is normal. ⟦part of the job⟧", "doctor checks the whole list without a device and exits non-zero when it found a problem (a FAIL line), so a script can act on it. ⟦non-zero⟧"], "concern": "", "check": "Claude's reading: only checks with status problem (printed FAIL) count toward Problems, and the command exits non-zero only when Problems > 0, so notes alone exit zero. The doc says 'exits non-zero if it found something', which a reviewer may find vaguer than the code; the answer that notes do not fail is from the code, so the second fact is left to the judge on that point. Verified in: internal/agent/doctor.go:42-67, internal/agent/doctor.go:343-345, cmd/mobium/doctor.go:29-34."}, {"id": "g019", "kind": "unanswerable", "question": "How do I set up the Mobium daemon to start automatically at login as a launchd or systemd service, so it is always up before my tests run?", "tags": ["ci-engineer"], "gold": [], "retrieved": [{"id": "docs/quickstart/go.md#3-the-code", "heading": "3. The code", "path": "docs/quickstart/go.md", "excerpt": "Save this as `main.go` in the project folder — it is [examples/go/main.go](examples/go/main.go). ```go // Mobium quick start: start a session, drive Settings, quit. // // MOBIUM_PLATFORM=android go run . # or ios package main import ( \"context\" \"fmt\" \"log\" \"os\" \"strings\" \"time\" mobium \"github.com/mobiumdev/mobium/clients/go\" ) // Settings is on every emulator, simulator and phone, with nothing to install. var platfor…", "gold": false}, {"id": "docs/guides/inspector.md#4-record-a-test", "heading": "4. Record a test", "path": "docs/guides/inspector.md", "excerpt": "A test starts from a freshly launched app, so a recording should too: **Start from a fresh app** stops the app in front and launches it again, as `mobium test` does before each test, and starts recording. From there, every action is a step. Recorded on the Login Demo: ```json { \"app\": \"dev.mobium.mobiumapp\", \"description\": \"Recorded with mobium inspect.\", \"tests\": [ { \"name\": \"recorded\", \"steps\": [ {\"tap\": \"text=Logi…", "gold": false}, {"id": "docs/quickstart/README.md#contents", "heading": "Contents", "path": "docs/quickstart/README.md", "excerpt": "- [Where it runs](#where-it-runs) - [1. Install mobium](#1-install-mobium) - [2. Start a device](#2-start-a-device) - [3. Check the setup](#3-check-the-setup) - [4. Start, work, quit](#4-start-work-quit) - [Next](#next) - [When something goes wrong](#when-something-goes-wrong)", "gold": false}, {"id": "docs/quickstart/python.md#3-the-code", "heading": "3. The code", "path": "docs/quickstart/python.md", "excerpt": "Save this as `quickstart.py` in the project folder — it is [examples/python/quickstart.py](examples/python/quickstart.py). ```python \"\"\"Mobium quick start: start a session, drive Settings, quit. MOBIUM_PLATFORM=android python3 quickstart.py # or ios \"\"\" import os from mobium import start # Settings is on every emulator, simulator and phone, with nothing to install. PLATFORMS = { \"android\": {\"app\": \"com.android.settin…", "gold": false}, {"id": "docs/quickstart/cli.md#2-the-code", "heading": "2. The code", "path": "docs/quickstart/cli.md", "excerpt": "Save this as `quickstart.sh` — it is [examples/cli/quickstart.sh](examples/cli/quickstart.sh). ```sh #!/bin/sh # Mobium quick start from the command line: start a session, drive Settings, # quit. # # MOBIUM_PLATFORM=android sh quickstart.sh # or ios set -e PLATFORM=\"${MOBIUM_PLATFORM:-android}\" if [ \"$PLATFORM\" = ios ]; then APP=com.apple.Preferences ROW=General NEXT=\"label=About,role=button\" else APP=com.android.set…", "gold": false}], "missed": false, "facts": [], "concern": "", "check": "Claude's reading: the corpus mentions launchd only for simulator internals and Chrome's crash handler, never systemd or a login service; the code only auto-starts the daemon from the first command (daemon_client.go) or `daemon start`. The docs explain auto-start and idle exit, which a retriever will return, but never how to run it as a service. Nearest sections: docs/guides/cli.md#8-the-daemon-and-running-several-at-once, docs/SHUTDOWN.md#1-mobium-daemon-stop-always-first. Verified in: cmd/mobium/daemon_client.go:16-19, cmd/mobium/daemon_cmd.go:46."}, {"id": "g020", "kind": "unanswerable", "question": "When will Mobium's first prebuilt release, v0.1.0, be published so I can install without Go?", "tags": ["new-user"], "gold": [], "retrieved": [{"id": "docs/quickstart/README.md#1-install-mobium", "heading": "1. Install mobium", "path": "docs/quickstart/README.md", "excerpt": "Until the first release there are no prebuilt binaries: mobium installs with **Go 1.24 or later** ([go.dev/dl](https://go.dev/dl/)), and needs nothing else. ```sh go install github.com/mobiumdev/mobium/cmd/mobium@latest mobium --version ``` It lands in `$(go env GOPATH)/bin`; make sure that is on your `PATH`. Each client page says how to install that client. Python (with `git`) and Go install straight from GitHub tod…", "gold": false}, {"id": "docs/SETUP.md#installing-a-release", "heading": "Installing a release", "path": "docs/SETUP.md", "excerpt": "From the first tagged release on, each one carries mobium prebuilt for macOS, Linux and Windows, on amd64 and arm64, so installing it needs no Go: `mobium_<version>_<os>_<arch>.tar.gz` (`.zip` for Windows), each holding the binary, the license and its notices, and the README, and `SHA256SUMS` over all of them. The binary is static — nothing else to install with it. ```sh v=0.1.0; os=darwin; arch=arm64 # or linux / wi…", "gold": false}, {"id": "docs/ROADMAP.md#next", "heading": "Next", "path": "docs/ROADMAP.md", "excerpt": "- **Found reviewing the docs evaluation's golden set** (written down 2026-10-12, read from the code, not yet run on a device): 1. ~~**On an Apple TV, a dialog of three or more buttons named a remedy that cannot work.**~~ Done 2026-10-12, CHALLENGES 313: `app_alert` asks the driver whether the device is answered by its remote before choosing accept, dismiss or a button, and on a TV every one of them is refused naming …", "gold": false}, {"id": "README.md#quick-start", "heading": "Quick start", "path": "README.md", "excerpt": "Requirements: - **Go 1.24+**, to install it — prebuilt binaries arrive with the first release ([SETUP.md](docs/SETUP.md#installing-a-release)) - **Android:** platform-tools on `PATH` (or `ANDROID_HOME`, or `MOBIUM_ADB_PATH`), and an emulator or a phone with USB debugging on - **iOS:** full Xcode and a booted simulator — or an iPhone on a cable, with an Apple ID (a free one works) added to Xcode ```sh go install githu…", "gold": false}, {"id": "docs/upstream/webdriveragent-mjpeg-ignores-use-ip.md#what-mobium-does-meanwhile", "heading": "What Mobium does meanwhile", "path": "docs/upstream/webdriveragent-mjpeg-ignores-use-ip.md", "excerpt": "- **Real iPhone:** Mobium builds the runner from the pinned source and applies this line before building (`internal/device/wdapatch.go`), refusing to build if the line it attaches to is gone. - **Simulator:** Mobium installs the prebuilt release, which it does not patch. The server is bound with `USE_IP=127.0.0.1`; the stream is left to the Mac's firewall. A runner built for the simulator from source could not be lau…", "gold": false}], "missed": false, "facts": [], "concern": "", "check": "Claude's reading: the corpus describes what a release will contain and that installs need Go until the first release, and uses v0.1.0 as an example version, but states no date; release gating is a checklist, not a schedule. A right answer says the docs give no date. Nearest sections: docs/SETUP.md#installing-a-release, docs/quickstart/README.md#1-install-mobium. Verified in: docs/RELEASE-CHECKLIST.md."}, {"id": "g021", "kind": "fact", "question": "My locator text=Settings also clicks things like \"Display settings\" because it matches part of the text. How do I make a Mobium locator match only an element whose text is exactly Settings?", "tags": ["how-to", "test-author"], "gold": [{"id": "docs/guides/cli.md#4-locators-and-refs", "heading": "4. Locators and refs", "path": "docs/guides/cli.md", "excerpt": "Anything that takes a target takes either: - **a ref** from the last `map` — `@e3` — short, and valid until the screen changes; or - **a locator** — `testid=username`, `label=Login Demo`, `text=Sign in`, `role=button` — which survives across screens and runs, and is what a script or a test should use. `testid=` is the one that survives a translation and a redesign. A string locator matches part of the words, in any c…"}], "retrieved": [{"id": "CHALLENGES#306", "heading": "306. A locator printed as exact was pasted back as a part", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** writing down what a hand-written locator cannot say, for the roadmap's locators entry. CHALLENGES 233's wait for `text=Internet` was met by \"Network & internet\" on the screen being left, and 185 had already noted \"no syntax to ask for the whole of it\". The locators `map` derives are exact — byte for byte — but a locator printed itself without saying so: a near miss suggested `label=Card 8`, an exact mat…", "gold": false}, {"id": "CHALLENGES#315", "heading": "315. On a watch, `text=` found a control and its own title", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** measuring Wear OS for the docs evaluation's question about it (ROADMAP), on a Wear OS 5.1 emulator (API 35, 454×454 round). `text=\"Security\"` on Settings matched two elements and was refused, and so was every row: a Wear \"chip\" is a `Button` whose own `text` repeats its title's `TextView` (`wear_chip_primary_text`). A phone's settings row carries no text of its own, so there only the title matched. The …", "gold": false}, {"id": "README.md#refs", "heading": "Refs", "path": "README.md", "excerpt": "`mobium map` snapshots the accessibility hierarchy, keeps the nodes a person could act on, and gives each one the most durable locator that identifies it uniquely — a resource-id if there is one, then an accessibility label, then visible text, and a sibling path only as a last resort. `mobium tap @e5` **re-snapshots and re-resolves** that locator before touching anything. It never replays the coordinates from the map…", "gold": false}, {"id": "docs/guides/cli.md#4-locators-and-refs", "heading": "4. Locators and refs", "path": "docs/guides/cli.md", "excerpt": "Anything that takes a target takes either: - **a ref** from the last `map` — `@e3` — short, and valid until the screen changes; or - **a locator** — `testid=username`, `label=Login Demo`, `text=Sign in`, `role=button` — which survives across screens and runs, and is what a script or a test should use. `testid=` is the one that survives a translation and a redesign. A string locator matches part of the words, in any c…", "gold": true}], "missed": false, "facts": ["An unquoted string locator matches part of the words, in any case; putting the value in double quotes matches the whole of it (still in any case). ⟦double quotes⟧", "For example text=\"Internet\" finds only an element whose text is Internet, not \"Network & internet\". ⟦text=\"Internet\"⟧"], "concern": "", "check": "Claude's reading: cli.md section 4 states the quoted-whole rule; Locator.field compares a quoted (Whole) value with strings.EqualFold after trimming, and an unquoted one by case-insensitive substring (match). Reviewer: the question's example is mine, the anchor example is the doc's. Verified in: internal/uitree/locator.go:425, internal/uitree/locator.go:441."}, {"id": "g022", "kind": "fact", "question": "Every row in my list has its own \"More\" button. How do I write a locator in a test file for the More button in the row titled \"Card 8\", one that still works after the list scrolls?", "tags": ["how-to", "test-author"], "gold": [{"id": "docs/guides/cli.md#4-locators-and-refs", "heading": "4. Locators and refs", "path": "docs/guides/cli.md", "excerpt": "Anything that takes a target takes either: - **a ref** from the last `map` — `@e3` — short, and valid until the screen changes; or - **a locator** — `testid=username`, `label=Login Demo`, `text=Sign in`, `role=button` — which survives across screens and runs, and is what a script or a test should use. `testid=` is the one that survives a translation and a redesign. A string locator matches part of the words, in any c…"}], "retrieved": [{"id": "docs/guides/inspector.md#4-record-a-test", "heading": "4. Record a test", "path": "docs/guides/inspector.md", "excerpt": "A test starts from a freshly launched app, so a recording should too: **Start from a fresh app** stops the app in front and launches it again, as `mobium test` does before each test, and starts recording. From there, every action is a step. Recorded on the Login Demo: ```json { \"app\": \"dev.mobium.mobiumapp\", \"description\": \"Recorded with mobium inspect.\", \"tests\": [ { \"name\": \"recorded\", \"steps\": [ {\"tap\": \"text=Logi…", "gold": false}, {"id": "docs/guides/cli.md#4-locators-and-refs", "heading": "4. Locators and refs", "path": "docs/guides/cli.md", "excerpt": "Anything that takes a target takes either: - **a ref** from the last `map` — `@e3` — short, and valid until the screen changes; or - **a locator** — `testid=username`, `label=Login Demo`, `text=Sign in`, `role=button` — which survives across screens and runs, and is what a script or a test should use. `testid=` is the one that survives a translation and a redesign. A string locator matches part of the words, in any c…", "gold": true}, {"id": "CHALLENGES#307", "heading": "307. A scoped locator found the switch in the row beside it", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** the first run on a device of `within`, which scopes a locator to a row — `label=More within text=Card 8`, the More in Card 8's row. The rule keeps, of the target's matches, the one nearest the anchor, climbing from the anchor and stopping at the list, so a row without the target finds nothing rather than its neighbor's. The tests passed on lists built for them, each marked `scrollable=\"true\"`. On the An…", "gold": false}], "missed": false, "facts": ["Use within to scope a locator to a row, e.g. label=More within text=Card 8; both sides are whole locators. ⟦within text= / within label=⟧", "It keeps the match nearest the anchor and never reaches past the list holding the anchor, so a row without the target finds nothing rather than the neighbor's.", "Both sides are resolved again on every read, since a list reuses its rows as it scrolls (unlike a ref, which is gone with its map)."], "concern": "", "check": "Claude's reading: cli.md section 4 describes within; Locator.Resolve keeps the target matches nearest the anchor and the comment above it says the climb stops at a scroll container and resolves whole on every read. Facts 2 and 3 have no distinctive token and are left to the judge. Verified in: internal/uitree/locator.go:40, internal/uitree/locator.go:491, internal/uitree/locator.go:508."}, {"id": "g023", "kind": "multi", "question": "In my hybrid app the Save button sits inside an iframe on the embedded web page. How do I tap it from the Mobium CLI?", "tags": ["how-to", "test-author"], "gold": [{"id": "README.md#hybrid-apps-and-webviews", "heading": "Hybrid apps and WebViews", "path": "README.md", "excerpt": "A hybrid app's web content is not usable through the accessibility tree, so Mobium attaches to the WebView, and switching context changes what `map` and `tap` operate on: ``` $ mobium contexts NATIVE_APP (current) WEBVIEW_com.example — Checkout https://shop.example/cart $ mobium context WEBVIEW_com.example $ mobium map @e1 Promo code (input) @e2 Apply (button) $ mobium tap @e2 tapped @e2 at (462, 397) in WEBVIEW_com.…"}, {"id": "docs/guides/cli.md#4-locators-and-refs", "heading": "4. Locators and refs", "path": "docs/guides/cli.md", "excerpt": "Anything that takes a target takes either: - **a ref** from the last `map` — `@e3` — short, and valid until the screen changes; or - **a locator** — `testid=username`, `label=Login Demo`, `text=Sign in`, `role=button` — which survives across screens and runs, and is what a script or a test should use. `testid=` is the one that survives a translation and a redesign. A string locator matches part of the words, in any c…"}], "retrieved": [{"id": "CHALLENGES#228", "heading": "228. A WebView's map stopped at the edge of every frame", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** taking ROADMAP's \"Frames and iframes inside a WebView\" to MobiumApp's Frames page, built for it: a same-origin frame, a frame nested inside it and a cross-origin one, each of whose buttons tells the page it was tapped. In the WebView's context `map` listed the page's own button and nothing in any frame, on the simulator and an emulator alike: the scripts that find elements, check them and fill them read…", "gold": false}, {"id": "skills/mobile-check/SKILL.md#when-things-fail", "heading": "When things fail", "path": "skills/mobile-check/SKILL.md", "excerpt": "Mobium's errors say what to do; read them rather than retrying blindly. Every failure also carries a **code**, so you can act on the kind without parsing the sentence: `--json` prints it (`\"code\": \"no_such_element\"`, with a `remedy` and `details`), and the exit status groups it: | Exit | Codes | What to do | | --- | --- | --- | | 2 | `invalid_argument` | fix the command; retrying it unchanged cannot help | | 3 | `no_…", "gold": false}, {"id": "skills/mobile-check/SKILL.md#hybrid-apps-webviews", "heading": "Hybrid apps (WebViews)", "path": "skills/mobile-check/SKILL.md", "excerpt": "Web content inside an app is a separate context: ```sh mobium contexts # NATIVE_APP, WEBVIEW_com.example mobium context WEBVIEW_com.example # map and tap now work on the page mobium context NATIVE_APP # back to the native shell ``` This works on **both platforms**. Android WebViews must be debuggable (`setWebContentsDebuggingEnabled(true)`) and iOS WKWebViews must be inspectable (`webView.isInspectable = true` on iOS…", "gold": false}, {"id": "README.md#hybrid-apps-and-webviews", "heading": "Hybrid apps and WebViews", "path": "README.md", "excerpt": "A hybrid app's web content is not usable through the accessibility tree, so Mobium attaches to the WebView, and switching context changes what `map` and `tap` operate on: ``` $ mobium contexts NATIVE_APP (current) WEBVIEW_com.example — Checkout https://shop.example/cart $ mobium context WEBVIEW_com.example $ mobium map @e1 Promo code (input) @e2 Apply (button) $ mobium tap @e2 tapped @e2 at (462, 397) in WEBVIEW_com.…", "gold": true}, {"id": "docs/quickstart/cli.md#2-the-code", "heading": "2. The code", "path": "docs/quickstart/cli.md", "excerpt": "Save this as `quickstart.sh` — it is [examples/cli/quickstart.sh](examples/cli/quickstart.sh). ```sh #!/bin/sh # Mobium quick start from the command line: start a session, drive Settings, # quit. # # MOBIUM_PLATFORM=android sh quickstart.sh # or ios set -e PLATFORM=\"${MOBIUM_PLATFORM:-android}\" if [ \"$PLATFORM\" = ios ]; then APP=com.apple.Preferences ROW=General NEXT=\"label=About,role=button\" else APP=com.android.set…", "gold": false}], "missed": false, "facts": ["Switch to the WebView's context first (mobium contexts, then mobium context WEBVIEW_...), after which map and tap operate on the page. ⟦mobium context⟧", "Then use a css= locator with the frame's path before the selector, separated by >>, as map prints it, e.g. 'css=iframe#f >> button'. ⟦css= ; >>⟧"], "concern": "", "check": "Claude's reading: README's hybrid section gives the context switch, cli.md section 4 the css= selector with a frame path; findWebByLocator and webview/css.go split the selector on ' >> ' and resolve inside that frame. CHALLENGES 312 and SKILL 'When things fail' also mention the frame path; I kept gold to the two sections a new user needs. Verified in: internal/agent/webview.go:1057, internal/webview/css.go:35, internal/agent/webview.go:51."}, {"id": "g024", "kind": "multi", "question": "Is there a way to click an element on my device's screen and see which locator I should put in my test for it?", "tags": ["how-to", "new-user"], "gold": [{"id": "docs/guides/inspector.md#1-start-it", "heading": "1. Start it", "path": "docs/guides/inspector.md", "excerpt": "``` $ mobium inspect --device emulator-5554 mobium inspect on http://127.0.0.1:47311/819d02101356fef7563223333156107f/ — Ctrl-C to stop ``` Open that URL — `--open` does it for you. The long part of it is a token: the page answers nothing that does not carry it ([below](#who-can-reach-it)). It calls the same tools every command does, through the same daemon, so a terminal and the page drive one session: run `mobium t…"}, {"id": "docs/guides/inspector.md#2-find-the-locator-for-anything", "heading": "2. Find the locator for anything", "path": "docs/guides/inspector.md", "excerpt": "![The inspector on MobiumApp's Login Demo: the username field selected, its locator testid=username, its role, ref and bounds, and both buttons outlined in orange for role=button](images/inspector.jpg) Click an element on the screen, or in the list under it. The panel says what `map` says of it — label, role, ref, bounds, checked state — and, at the top, **the locator a test should use**: the one `map` derived as the…"}], "retrieved": [{"id": "docs/guides/inspector.md#2-find-the-locator-for-anything", "heading": "2. Find the locator for anything", "path": "docs/guides/inspector.md", "excerpt": "![The inspector on MobiumApp's Login Demo: the username field selected, its locator testid=username, its role, ref and bounds, and both buttons outlined in orange for role=button](images/inspector.jpg) Click an element on the screen, or in the list under it. The panel says what `map` says of it — label, role, ref, bounds, checked state — and, at the top, **the locator a test should use**: the one `map` derived as the…", "gold": true}, {"id": "docs/guides/inspector.md#quick-start-mobium-inspect", "heading": "Quick start: `mobium inspect`", "path": "docs/guides/inspector.md", "excerpt": "A page on your own machine with the device's screen in it: every element `map` finds outlined, the locator for the one you click, actions on it, a place to try a locator and see what it matches — and what you do, kept as a test `mobium test` runs. Everything below was run on 2026-09-29 against [MobiumApp](https://github.com/mobiumdev/mobium-app) on an Android 15 emulator; the output is what mobium printed. Before thi…", "gold": false}, {"id": "docs/guides/test-runner.md#writing-tests", "heading": "Writing tests", "path": "docs/guides/test-runner.md", "excerpt": "- **Find targets with `map` first.** `mobium map` on the screen you are testing gives each element's locator; `testid=` is the one that survives a translation and a redesign. - **Assert with `app_wait_for`**, never a sleep. `--for` in the CLI is `condition` in a step: `visible`, `hidden`, `text` (with `exact`), `value`, `enabled`, `disabled`, `checked`, `unchecked`, `selected`, `unselected`, `focused`, `count`, and `…", "gold": false}, {"id": "docs/ROADMAP.md#under-consideration", "heading": "Under consideration", "path": "docs/ROADMAP.md", "excerpt": "- **Locators for when there is no ref** (written down 2026-10-12). A ref from `map` lasts one map, so an agent has one and a `mobium test` file does not: a hand-written test has the flat `kind=value` locators — text, label, testid, role, class, path, narrowed by `,role=` — which match one element or are refused. That is right on a form and leaves nothing durable on a list. Every Ice Cubes post has a \"…\" (CHALLENGES 2…", "gold": false}, {"id": "docs/guides/cli.md#4-locators-and-refs", "heading": "4. Locators and refs", "path": "docs/guides/cli.md", "excerpt": "Anything that takes a target takes either: - **a ref** from the last `map` — `@e3` — short, and valid until the screen changes; or - **a locator** — `testid=username`, `label=Login Demo`, `text=Sign in`, `role=button` — which survives across screens and runs, and is what a script or a test should use. `testid=` is the one that survives a translation and a redesign. A string locator matches part of the words, in any c…", "gold": false}], "missed": false, "facts": ["Run mobium inspect (optionally --device and --open), which serves a local page showing the device's screen. ⟦mobium inspect ; --open⟧", "Clicking an element shows what map says of it, and at the top the locator a test should use: the most durable one that names it alone (the ref names it on this screen only). ⟦the locator a test should use⟧"], "concern": "", "check": "Claude's reading: inspector guide sections 1 and 2 together answer it; cmd/mobium/inspect.go defines --port, --open and --record, and inspect.go's target() returns map's derived locator as the one a test names. Section 3 (Try a locator) is related but not needed. Verified in: cmd/mobium/inspect.go:71, internal/inspect/inspect.go:205."}, {"id": "g025", "kind": "multi", "question": "On an Apple TV simulator mobium tap is refused. How do I get to a particular tile and open it, and how do I know which tile will be opened before I press?", "tags": ["how-to", "test-author", "new since 7b590a4"], "gold": [{"id": "docs/SETUP.md#an-apple-tv-simulator", "heading": "An Apple TV simulator", "path": "docs/SETUP.md", "excerpt": "Verified on a tvOS 26.5 simulator (Apple TV 4K, 3rd generation, at 1080p) with Xcode 26.6, on 2026-10-09. The tvOS platform is a separate download: ```sh xcodebuild -downloadPlatform tvOS # or Xcode > Settings > Components xcrun simctl create \"Apple TV\" \\ com.apple.CoreSimulator.SimDeviceType.Apple-TV-4K-3rd-generation-1080p \\ com.apple.CoreSimulator.SimRuntime.tvOS-26-5 xcrun simctl boot <udid> && open -a Simulator …"}, {"id": "CHALLENGES#355", "heading": "355. A TV's map did not say which tile select would press", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** the Fire TV and Apple TV entries in ROADMAP, then MobiumTV's home screen on the Android TV emulator and the Apple TV simulator. A TV is driven by focus: the D-pad moves it and select presses what has it. Both platforms report it on the node — Android's `focused`, and iOS's since 297 — and a D-pad press already read it back (\"focus moved to Focus or Select\"). But `map` built its entries without it, so af…"}], "retrieved": [{"id": "CHALLENGES#334", "heading": "334. On an Apple TV, a dialog rule tapped, and refusals said to tap", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** Morpho Market's Apple TV app, on a tvOS 26.5 simulator. Its tests start from `mobiumshop://reset`, and tvOS asks \"Open in “Morpho Market”?\" before a link opens the app, until Open is pressed once — as iOS does, where the phone suite answers it with a dialog rule. On the Apple TV the same rule failed every action it met: the rule tapped the button, and a TV refuses every tap (`an Apple TV has no touch sc…", "gold": false}, {"id": "docs/ROADMAP.md#under-consideration", "heading": "Under consideration", "path": "docs/ROADMAP.md", "excerpt": "- **Locators for when there is no ref** (written down 2026-10-12). A ref from `map` lasts one map, so an agent has one and a `mobium test` file does not: a hand-written test has the flat `kind=value` locators — text, label, testid, role, class, path, narrowed by `,role=` — which match one element or are refused. That is right on a form and leaves nothing durable on a list. Every Ice Cubes post has a \"…\" (CHALLENGES 2…", "gold": false}, {"id": "docs/RELEASE-CHECKLIST.md#ios-a-booted-iphone-simulator", "heading": "iOS — a booted iPhone simulator", "path": "docs/RELEASE-CHECKLIST.md", "excerpt": "- [ ] `mobium --driver wda map` on the home screen returns icons - [ ] Wait for something already on screen, and across a cold app launch - [ ] `mobium scroll-to` reaches a Settings row below the fold, and tapping it opens that screen - [ ] `mobium grant com.apple.Preferences photos` succeeds and says it could not be verified - [ ] `mobium grant <anything> camera` is refused, naming the missing service - [ ] Coordina…", "gold": false}, {"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": false}, {"id": "docs/SETUP.md#an-apple-tv-simulator", "heading": "An Apple TV simulator", "path": "docs/SETUP.md", "excerpt": "Verified on a tvOS 26.5 simulator (Apple TV 4K, 3rd generation, at 1080p) with Xcode 26.6, on 2026-10-09. The tvOS platform is a separate download: ```sh xcodebuild -downloadPlatform tvOS # or Xcode > Settings > Components xcrun simctl create \"Apple TV\" \\ com.apple.CoreSimulator.SimDeviceType.Apple-TV-4K-3rd-generation-1080p \\ com.apple.CoreSimulator.SimRuntime.tvOS-26-5 xcrun simctl boot <udid> && open -a Simulator …", "gold": true}], "missed": false, "facts": ["An Apple TV has no touch screen, so tap and other gestures are refused; it is driven with the remote: press dpad-up/down/left/right to move focus, and press select to press what has focus. ⟦dpad-down / dpad-right / dpad-up / dpad-left ; no touch screen⟧", "map marks the element with focus as (button, focused), and map --diff reports focus moving, so the focused tile is the one select will press. ⟦(button, focused)⟧"], "concern": "", "check": "Claude's reading: SETUP's Apple TV section gives the remote buttons and the refusal of tap; CHALLENGES 355 (#259, after the pin) adds focused to map and map --diff, which snapshot.go and mapdiff.go implement. ROADMAP 'Under consideration' also mentions 355 for the Fire TV. Verified in: internal/agent/remote.go:11, cmd/mobium/buttons.go:8, internal/uitree/snapshot.go:80, internal/agent/mapdiff.go:99."}, {"id": "g026", "kind": "fact", "question": "My Compose screen has a Material 3 RangeSlider for a price range, with a minimum and a maximum thumb. How do I set each thumb with Mobium, and how does Mobium move it?", "tags": ["how-to", "test-author", "new since 7b590a4"], "gold": [{"id": "CHALLENGES#357", "heading": "357. A two-thumb slider: a fill that moved nothing said it moved, and a thumb at the edge closed the app", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** native two-thumb sliders (ROADMAP, \"Sliders\"), on a price range added to Morpho Market for them — Material 3's `RangeSlider` on Android, and on iOS a control the app draws, since SwiftUI has none. Three things, each measured on the Android 15 emulator and the iPhone 17 Pro simulator: - **A fill that moved nothing was reported as moved.** Material reports each thumb as a seek bar the size of the thumb — …"}], "retrieved": [{"id": "docs/ROADMAP.md#under-consideration", "heading": "Under consideration", "path": "docs/ROADMAP.md", "excerpt": "- **Locators for when there is no ref** (written down 2026-10-12). A ref from `map` lasts one map, so an agent has one and a `mobium test` file does not: a hand-written test has the flat `kind=value` locators — text, label, testid, role, class, path, narrowed by `,role=` — which match one element or are refused. That is right on a form and leaves nothing durable on a list. Every Ice Cubes post has a \"…\" (CHALLENGES 2…", "gold": false}, {"id": "CHALLENGES#357", "heading": "357. A two-thumb slider: a fill that moved nothing said it moved, and a thumb at the edge closed the app", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** native two-thumb sliders (ROADMAP, \"Sliders\"), on a price range added to Morpho Market for them — Material 3's `RangeSlider` on Android, and on iOS a control the app draws, since SwiftUI has none. Three things, each measured on the Android 15 emulator and the iPhone 17 Pro simulator: - **A fill that moved nothing was reported as moved.** Material reports each thumb as a seek bar the size of the thumb — …", "gold": true}, {"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": false}, {"id": "CHALLENGES#320", "heading": "320. A two-thumb slider built from ARIA was not in `map`, and one built from ranges moved the wrong thumb", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** measuring two-thumb sliders, as pages build them, on MobiumApp's Slider Demo: Price, two `<input type=\"range\">` laid over one track, the minimum kept at or below the maximum by the page; and Hours, two `role=\"slider\"` thumbs on a drawn track, moved by a finger or the arrow keys, the way component libraries build one. Hours was not in `map` at all: the list of a page's elements had no `[role=slider]`. Pr…", "gold": false}], "missed": false, "facts": ["Each thumb is its own slider element (Material reports them as seek bars such as \"Range start\" and \"Range end\"), filled one at a time with fill and a position. ⟦Range start / Range end⟧", "A thumb of a two-thumb range is filled by dragging the thumb itself (a touch on the track would move the nearer thumb), and the result is read back from the thumb's own bounds, a short drag corrected. ⟦dragging the thumb itself⟧", "On Android the drag takes hold 32dp in from the screen's sides (20 points on iOS), so it is not taken as the system back gesture. ⟦32dp⟧"], "concern": "", "check": "Claude's reading: CHALLENGES 357 (#262, after the pin) is the only place the native two-thumb fill is described; RangeThumb recognizes two slider/adjustable children of one parent and dragThumb drags and reads back with up to three attempts. The 0-to-1 position rule itself is in CHALLENGES 219 and the fill help, not in 357; I did not make it a fact. Verified in: internal/uitree/rangethumb.go:13, internal/mobiumdriver/range.go:33, internal/agent/slider.go:37."}, {"id": "g027", "kind": "fact", "question": "After tapping Log In, my test needs to wait until the error label says exactly \"Incorrect username or password.\" How do I write that wait with Mobium, and how long does it wait before failing?", "tags": ["how-to", "test-author"], "gold": [{"id": "docs/guides/autowait.md#5-waiting-on-purpose-mobium-wait", "heading": "5. Waiting on purpose: `mobium wait`", "path": "docs/guides/autowait.md", "excerpt": "The checks above make each action wait for its own target. For everything else — a result to arrive, a spinner to go, a state to change — say what you are waiting for, instead of sleeping: ``` $ mobium wait testid=loginError --for text --text \"Incorrect username or password.\" --exact testid=loginError says exactly \"Incorrect username or password.\" after 1.631s — @e1 ScrollView (list) ``` It returned as soon as the te…"}], "retrieved": [{"id": "docs/guides/autowait.md#5-waiting-on-purpose-mobium-wait", "heading": "5. Waiting on purpose: `mobium wait`", "path": "docs/guides/autowait.md", "excerpt": "The checks above make each action wait for its own target. For everything else — a result to arrive, a spinner to go, a state to change — say what you are waiting for, instead of sleeping: ``` $ mobium wait testid=loginError --for text --text \"Incorrect username or password.\" --exact testid=loginError says exactly \"Incorrect username or password.\" after 1.631s — @e1 ScrollView (list) ``` It returned as soon as the te…", "gold": true}, {"id": "docs/guides/test-runner.md#4-run-only-what-failed", "heading": "4. Run only what failed", "path": "docs/guides/test-runner.md", "excerpt": "``` $ mobium test --last-failed FAIL [android] login.test.json › a wrong password is refused (8.7s) step 4 (app_wait_for): [timeout] step 4 of 4 (app_wait_for) failed: timed out after 3.018s waiting for testid=loginError to say exactly \"Wrong password.\" — its text is \"Incorrect username or password.\"; steps 1-3 ran before it, and nothing after 0 passed, 1 failed (8.7s) error: 1 of 1 tests failed ``` The previous run'…", "gold": false}, {"id": "docs/guides/autowait.md#2-waiting-for-a-control-to-be-enabled", "heading": "2. Waiting for a control to be enabled", "path": "docs/guides/autowait.md", "excerpt": "The Login Demo disables Log In while it signs in. Tap it, and tap it again at once: ``` $ mobium fill testid=username mobium typed \"mobium\" into testid=username $ mobium fill testid=password wrongpass1 typed 10 characters into testid=password, a password field — not echoed $ mobium tap testid=loginBtn tapped testid=loginBtn at (540, 1457) $ mobium wait testid=loginBtn --for disabled testid=loginBtn is disabled after …", "gold": false}, {"id": "docs/guides/cli.md#7-several-steps-in-one-call-batch", "heading": "7. Several steps in one call: `batch`", "path": "docs/guides/cli.md", "excerpt": "A known sequence can go as one call — from a file, or `-` for stdin. Every step is checked before the first runs, and it stops at the first failure, with that step's own error: ```json [ {\"name\": \"app_tap\", \"arguments\": {\"target\": \"label=Login Demo\"}}, {\"name\": \"app_fill\", \"arguments\": {\"target\": \"testid=username\", \"text\": \"mobium\"}}, {\"name\": \"app_fill\", \"arguments\": {\"target\": \"testid=password\", \"text\": \"hunter2\"}}…", "gold": false}, {"id": "skills/mobile-check/SKILL.md#waiting", "heading": "Waiting", "path": "skills/mobile-check/SKILL.md", "excerpt": "Never sleep. Every action already retries for two seconds while the screen settles, so a tap straight after a launch or another tap is fine. When something takes longer than that — a login, a network fetch — wait for the thing itself rather than for a duration: - `mobium wait \"text=Welcome back\"` — until it is on screen - `mobium wait 'text=\"Wi-Fi\"'` — quoted: the whole text, so a part of it on the screen you are lea…", "gold": false}], "missed": false, "facts": ["mobium wait <locator> --for text --text \"...\" --exact waits until the element's text is exactly that (without --exact it waits for the text to contain it). ⟦--exact ; --for text⟧", "The default timeout is 10 seconds; --timeout changes it, up to two minutes."], "concern": "", "check": "Claude's reading: autowait.md section 5 has the exact command and the timeout table; wait.go sets defaultWaitTimeout 10s and maxWaitTimeout 120s, and the CLI's --exact matches the whole text. The 10-second and two-minute numbers are too common in the corpus to anchor, so fact 2 is left to the judge. Verified in: cmd/mobium/wait.go:59, cmd/mobium/wait.go:61, internal/agent/wait.go:54."}, {"id": "g028", "kind": "fact", "question": "What does Mobium do when I tap a button that another view is drawn over, both when the cover hides the whole button and when it hides only the middle of it?", "tags": ["behavior", "test-author"], "gold": [{"id": "docs/guides/autowait.md#3-refusing-what-is-covered", "heading": "3. Refusing what is covered", "path": "docs/guides/autowait.md", "excerpt": "The Obstruction Demo draws controls over its targets — a full cover, a half cover over the center, an edge cover that leaves the center clear, views that take no touches, an overlay hidden from accessibility, a scrim: ![The Obstruction Demo: a column of buttons, each with something drawn over it](images/autowait-5-covers.jpg) One is covered entirely by another button: ``` $ mobium tap testid=fullTarget error: testid=…"}], "retrieved": [{"id": "docs/guides/autowait.md#3-refusing-what-is-covered", "heading": "3. Refusing what is covered", "path": "docs/guides/autowait.md", "excerpt": "The Obstruction Demo draws controls over its targets — a full cover, a half cover over the center, an edge cover that leaves the center clear, views that take no touches, an overlay hidden from accessibility, a scrim: ![The Obstruction Demo: a column of buttons, each with something drawn over it](images/autowait-5-covers.jpg) One is covered entirely by another button: ``` $ mobium tap testid=fullTarget error: testid=…", "gold": true}, {"id": "CHALLENGES#115", "heading": "115. A tap under the app's own overlay reported success", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** MobiumApp's Obstruction Demo, built for the purpose after the Dialog Demo's pinned button was seen covering the camera button while both platforms called both visible. Each case is a target with a known cover, every cover itself pressable, and one line saying which of them a tap really reached. On a Pixel 7 AVD and an iPhone 17 Pro simulator, `tap` answered \"tapped\" eight times out of eight, and six of …", "gold": false}, {"id": "CHALLENGES#107", "heading": "107. A tap on a button under the keyboard reported success", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** the iOS login demo, where Log In sat under the keyboard; the app's layout was fixed then, and the Dialog Demo's pinned button is the case kept on purpose. The keyboard is the dialog case one layer over, in the same two shapes. On iOS the keyboard is an `XCUIElementTypeKeyboard` in the app's tree, and what it covers stays there, marked not visible — the field being typed into included — so a locator reso…", "gold": false}, {"id": "docs/guides/autowait.md#what-it-does-not-see", "heading": "What it does not see", "path": "docs/guides/autowait.md", "excerpt": "- **An overlay hidden from accessibility on iOS.** On a real iPhone no action checks for one: a tap under it lands on the overlay and is reported as tapped. WebDriverAgent's tree does not contain it, and its own `hittable` gets it wrong too, measured. It is uncommon — none was met in five third-party apps driven on the phone — and asking each action would cost more than the action: through the gray box, one question …", "gold": false}], "missed": false, "facts": ["Fully covered: it waits about two seconds in case the cover goes (a toast does), then refuses with failed check receivesEvents, naming the cover, rather than pressing it. ⟦receivesEvents⟧", "Covered only over its center: it taps a clear point of the target and says so in the result. ⟦clear point⟧"], "concern": "", "check": "Claude's reading: autowait.md section 3 shows both outputs; resolveAim waits up to the implicit wait (2s; longer for a notification banner) for a full cover, then coveredBy refuses, and a center-only cover gets the 'touched at a clear point' note. Verified in: internal/agent/cover.go:73, internal/agent/cover.go:130, internal/agent/cover.go:153."}, {"id": "g029", "kind": "fact", "question": "How long will a Mobium tap keep waiting for a button that is still animating into place, and how long for one that is disabled, before it gives up?", "tags": ["behavior", "test-author"], "gold": [{"id": "docs/guides/autowait.md#the-checks", "heading": "The checks", "path": "docs/guides/autowait.md", "excerpt": "Five checks, each with a name that a refusal carries: | Check | What it asks | If it fails | | --- | --- | --- | | `visible` | is the target on the screen, not just in the hierarchy? | scrolls to it, then refuses | | `stable` | has it stopped moving? | waits, up to 5 seconds | | `enabled` | does it take input? | waits, up to the implicit wait of 2 seconds, then refuses | | `receivesEvents` | would a finger reach it —…"}], "retrieved": [{"id": "skills/mobile-check/SKILL.md#acting", "heading": "Acting", "path": "skills/mobile-check/SKILL.md", "excerpt": "Every action waits, for up to two seconds, until its target is on screen, **enabled** and holding still, and refuses — with a reason and a remedy — rather than tapping something a user could not: a target under a system dialog or under the keyboard, a control that stays disabled, or a button passed to `type`. - `mobium tap @e5` — tap a ref - `mobium tap \"text=Sign In\"` — tap by locator, no map needed - `mobium tap 54…", "gold": false}, {"id": "skills/mobile-check/SKILL.md#waiting", "heading": "Waiting", "path": "skills/mobile-check/SKILL.md", "excerpt": "Never sleep. Every action already retries for two seconds while the screen settles, so a tap straight after a launch or another tap is fine. When something takes longer than that — a login, a network fetch — wait for the thing itself rather than for a duration: - `mobium wait \"text=Welcome back\"` — until it is on screen - `mobium wait 'text=\"Wi-Fi\"'` — quoted: the whole text, so a part of it on the screen you are lea…", "gold": false}, {"id": "docs/guides/autowait.md#5-waiting-on-purpose-mobium-wait", "heading": "5. Waiting on purpose: `mobium wait`", "path": "docs/guides/autowait.md", "excerpt": "The checks above make each action wait for its own target. For everything else — a result to arrive, a spinner to go, a state to change — say what you are waiting for, instead of sleeping: ``` $ mobium wait testid=loginError --for text --text \"Incorrect username or password.\" --exact testid=loginError says exactly \"Incorrect username or password.\" after 1.631s — @e1 ScrollView (list) ``` It returned as soon as the te…", "gold": false}, {"id": "docs/guides/autowait.md#1-waiting-for-something-to-stop-moving", "heading": "1. Waiting for something to stop moving", "path": "docs/guides/autowait.md", "excerpt": "The Motion Demo's Replay button slides a target in over two seconds. Tap the target the moment after Replay, with no sleep in between: ``` $ mobium tap testid=ignoringReplay tapped testid=ignoringReplay at (540, 1315) $ mobium tap testid=ignoringTarget tapped testid=ignoringTarget at (316, 1472) $ mobium text testid=ignoringResult Ignoring: tapped 2697ms after replay ``` | Just after Replay: the target still sliding …", "gold": false}, {"id": "CHALLENGES#118", "heading": "118. A tap inside a WebView was never checked, and went wherever the page put it", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** MobiumApp's Actionability page, the Obstruction Demo's web counterpart, built once native actions had learned to wait and to refuse. In a WebView none of that applied: a tap resolved its ref to the element's rectangle and touched the center. On a Pixel 7 AVD and an iPhone 17 Pro simulator, `tap` answered \"tapped\" nine times out of nine: | Target | What the tap reached | | --- | --- | | sliding in over t…", "gold": false}], "missed": true, "facts": ["The stable check waits up to 5 seconds for the target to stop moving, then refuses. ⟦stable⟧", "The enabled check waits up to the implicit wait of 2 seconds for the control to take input, then refuses. ⟦implicit wait⟧"], "concern": "skills/mobile-check/SKILL.md#acting says every action waits 'for up to two seconds, until its target is on screen, enabled and holding still'; the code's settleTimeout for holding still is 5 seconds (internal/agent/wait.go:47), as autowait.md says. The skill's sentence understates the stable wait.", "check": "Claude's reading: autowait.md's checks table matches wait.go (implicitWait 2s, settleTimeout 5s) and the enabled poll in resolveNodeOnce uses h.implicitWait. The skill's 'up to two seconds' for all three is the disagreement in concern. The numbers are too common to anchor; the anchors are the check names, and the judge must hold 5 s and 2 s. Verified in: internal/agent/wait.go:32, internal/agent/wait.go:47, internal/agent/handlers.go:1835."}, {"id": "g030", "kind": "fact", "question": "After mobium press back on Android, how can my test tell whether the app went to its previous screen or closed altogether?", "tags": ["behavior", "test-author"], "gold": [{"id": "docs/BACK.md#in-mobium", "heading": "In Mobium", "path": "docs/BACK.md", "excerpt": "Fixed on 2026-10-01, and held by `docs/checks/back.sh`, which passed on the Pixel 8 Pro, both AVDs, the simulator and the iPhone 15 Plus: - `press back` says what back did: \"it left <app>; <app> is in the foreground\", or \"<app> is still in the foreground\", and on iOS what the navigation bar says now. It waits for that outcome by its own clock — a back that left an app handed focus over in about 0.1s — so a back insid…"}], "retrieved": [{"id": "docs/BACK.md#in-mobium", "heading": "In Mobium", "path": "docs/BACK.md", "excerpt": "Fixed on 2026-10-01, and held by `docs/checks/back.sh`, which passed on the Pixel 8 Pro, both AVDs, the simulator and the iPhone 15 Plus: - `press back` says what back did: \"it left <app>; <app> is in the foreground\", or \"<app> is still in the foreground\", and on iOS what the navigation bar says now. It waits for that outcome by its own clock — a back that left an app handed focus over in about 0.1s — so a back insid…", "gold": true}, {"id": "CHALLENGES#204", "heading": "204. Back said \"pressed back\" whether it went back or closed the app", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** Lana, on the Pixel 8 Pro: in MobiumApp a swipe back from any demo closed the app. Measuring it on five devices (docs/BACK.md) showed the app was at fault — it handled no back — and that Mobium would never have said so: `press back` answered \"pressed back\" whether the app went to its home screen or closed, its result claimed nothing, and a test using it saw the same answer for the bug and for the fix. Ba…", "gold": false}, {"id": "docs/BACK.md#back-on-each-platform", "heading": "Back, on each platform", "path": "docs/BACK.md", "excerpt": "What \"back\" is on Android and iOS, what Mobium sends for it, what MobiumApp did with it, and what is still missing before back can be relied on in a test. Every row below was measured on 2026-10-01; nothing here is from documentation alone unless it says so. It started with a report: on the Pixel 8 Pro, open MobiumApp, open any demo, swipe from the right edge — and the whole app closes, where Android users expect the…", "gold": false}, {"id": "CHALLENGES#findings-that-were-not-defects", "heading": "Findings that were not defects", "path": "docs/CHALLENGES.md", "excerpt": "Worth recording because each one closed off an approach that looked obvious. - **Predictive back on Android 15 closes a React Native app.** MobiumApp built with predictive back turned on went back to closing on every back from a demo on the Android 15 AVD, `BackHandler` never called, while on Android 17 — the AVD and the Pixel 8 Pro — it went back to its home screen. React Native 0.86 registers the callback that repl…", "gold": false}, {"id": "docs/ROADMAP.md#under-consideration", "heading": "Under consideration", "path": "docs/ROADMAP.md", "excerpt": "- **Locators for when there is no ref** (written down 2026-10-12). A ref from `map` lasts one map, so an agent has one and a `mobium test` file does not: a hand-written test has the flat `kind=value` locators — text, label, testid, role, class, path, narrowed by `,role=` — which match one element or are refused. That is right on a form and leaves nothing durable on a list. Every Ice Cubes post has a \"…\" (CHALLENGES 2…", "gold": false}], "missed": false, "facts": ["press back says what back did: 'it left <app>; <app> is in the foreground' when back left the app, or '<app> is still in the foreground' when it stayed inside it. ⟦it left ; still in the foreground⟧"], "concern": "", "check": "Claude's reading: BACK.md 'In Mobium' lists the outcome wording; backOutcome in back.go builds exactly those strings. SKILL 'Interruptions and hardware buttons' says the same; I kept gold to BACK.md, so a reviewer may want to add the skill section as an alternative. Verified in: internal/agent/back.go:160."}, {"id": "g031", "kind": "fact", "question": "My CI script needs to tell a tap refused because something covered the target apart from other failures. What exit status and JSON fields should it check?", "tags": ["behavior", "ci-engineer"], "gold": [{"id": "docs/guides/autowait.md#6-reading-a-refusal-from-code", "heading": "6. Reading a refusal from code", "path": "docs/guides/autowait.md", "excerpt": "`--json` gives the structured half of every answer. The same covered tap: ``` $ mobium --json tap testid=fullTarget { \"error\": \"testid=fullTarget failed check receivesEvents: it is covered by \\\"full cover\\\" (button), and was for 2.2s — a touch there would press that instead; wait for it to go, dismiss it, or tap its own ref from app_map if it is what you meant\", \"code\": \"element_not_reachable\", \"message\": \"testid=ful…"}], "retrieved": [{"id": "docs/guides/autowait.md#6-reading-a-refusal-from-code", "heading": "6. Reading a refusal from code", "path": "docs/guides/autowait.md", "excerpt": "`--json` gives the structured half of every answer. The same covered tap: ``` $ mobium --json tap testid=fullTarget { \"error\": \"testid=fullTarget failed check receivesEvents: it is covered by \\\"full cover\\\" (button), and was for 2.2s — a touch there would press that instead; wait for it to go, dismiss it, or tap its own ref from app_map if it is what you meant\", \"code\": \"element_not_reachable\", \"message\": \"testid=ful…", "gold": true}, {"id": "docs/guides/autowait.md#3-refusing-what-is-covered", "heading": "3. Refusing what is covered", "path": "docs/guides/autowait.md", "excerpt": "The Obstruction Demo draws controls over its targets — a full cover, a half cover over the center, an edge cover that leaves the center clear, views that take no touches, an overlay hidden from accessibility, a scrim: ![The Obstruction Demo: a column of buttons, each with something drawn over it](images/autowait-5-covers.jpg) One is covered entirely by another button: ``` $ mobium tap testid=fullTarget error: testid=…", "gold": false}, {"id": "CHALLENGES#118", "heading": "118. A tap inside a WebView was never checked, and went wherever the page put it", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** MobiumApp's Actionability page, the Obstruction Demo's web counterpart, built once native actions had learned to wait and to refuse. In a WebView none of that applied: a tap resolved its ref to the element's rectangle and touched the center. On a Pixel 7 AVD and an iPhone 17 Pro simulator, `tap` answered \"tapped\" nine times out of nine: | Target | What the tap reached | | --- | --- | | sliding in over t…", "gold": false}, {"id": "README.md#actions-wait-and-refuse-what-they-cannot-do", "heading": "Actions wait, and refuse what they cannot do", "path": "README.md", "excerpt": "Before acting, every action waits for its target to exist, be in view, stop moving and be enabled, and scrolls to it if it is off screen. It refuses — rather than taps — a target under a dialog or the keyboard, and `type` refuses what is certainly not a text field. When the app itself has drawn a control over the target, a tap aims at a clear part of it, waits for the cover to go, or refuses and names the cover; anyt…", "gold": false}, {"id": "docs/guides/autowait.md#4-refusing-the-wrong-kind-of-target", "heading": "4. Refusing the wrong kind of target", "path": "docs/guides/autowait.md", "excerpt": "`type` and `fill` go into text fields. Anything that is certainly not one is refused before a key is sent: ``` $ mobium type testid=loginBtn hello error: testid=loginBtn failed check editable: it is a button, not a text field — app_type types into a field; to press it, use app_tap ```", "gold": false}], "missed": false, "facts": ["With --json the refusal has code element_not_reachable, and the CLI exits with status 4. ⟦element_not_reachable ; exit status (4⟧", "details.check names the failed check (receivesEvents for a cover); decide by code and details.check, never by the message text, which may change. ⟦details.check⟧"], "concern": "", "check": "Claude's reading: autowait.md section 6 shows the JSON and names exit 4; mobiumerr.ExitCode returns 4 for element_not_reachable and failedCheck puts check and reason in details. Exit 4 also covers no_such_element and ambiguous_locator, so the code field is what separates them. Verified in: internal/mobiumerr/mobiumerr.go:245, internal/agent/handlers.go:1142."}, {"id": "g032", "kind": "fact", "question": "In my Compose app the Price filter chip is off the right edge of a horizontal row of chips that sits above a large product grid. Which container does mobium scroll-to --direction right swipe to find it?", "tags": ["behavior", "test-author", "new since 7b590a4"], "gold": [{"id": "CHALLENGES#358", "heading": "358. A sideways scroll swiped the list below the row it was for", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** Morpho Market's Price chip, past the right edge of its category row, on the Android 15 emulator: `scroll-to testid=priceFilter --direction right` said \"scrolled right to the end of the list (1 scroll) without bringing it into view\", and the row had not moved. Compose leaves a chip off the row's edge out of the tree, so the loop had no node to ask which container held it, took the largest scrollable on t…"}], "retrieved": [{"id": "CHALLENGES#358", "heading": "358. A sideways scroll swiped the list below the row it was for", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** Morpho Market's Price chip, past the right edge of its category row, on the Android 15 emulator: `scroll-to testid=priceFilter --direction right` said \"scrolled right to the end of the list (1 scroll) without bringing it into view\", and the row had not moved. Compose leaves a chip off the row's edge out of the tree, so the loop had no node to ask which container held it, took the largest scrollable on t…", "gold": true}, {"id": "CHALLENGES#241", "heading": "241. A chip taller than its row was scrolled for fifteen times", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** the same search. A tap on the Podcasts filter chip swiped the results down fifteen times and gave up — \"on the screen but never scrolled fully into view\" — with the chip in plain sight throughout, and the swipes left the results scrolled over it. The chips are 36 points high in a horizontal scroll view 34 points high, a point over each edge, and a target had to fit inside its container's view to count a…", "gold": false}, {"id": "CHALLENGES#322", "heading": "322. A chip in plain sight, a point past its row, was swiped for", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** a SwiftUI checkout app written to be tested (Morpho Market, mobiumdev/morpho-market), on the iPhone 17 Pro simulator, iOS 26.5. Its size and category chips are capsules with an outline, and SwiftUI reports each one's frame a point outside its horizontal scroll view: 34 points high from y=452 in a row from y=453 to 486, and the first chip a point past the leading edge too. A target had to fit inside its …", "gold": false}, {"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": false}, {"id": "CHALLENGES#176", "heading": "176. Every Compose icon button mapped twice", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** `mobium map` on Seal, a Jetpack Compose app from F-Droid, on the first screen — the first Compose app this project had driven. Its three icon buttons came out as six entries: \"Settings\", and \"Settings (button)\". Compose wraps an icon button in a tooltip box, long-clickable so a long press shows the tooltip, and lays it out a pixel off the button's own bounds: `[32,95][158,221]` around `[33,96][159,222]`…", "gold": false}], "missed": false, "facts": ["A scroll given a direction swipes the largest scrollable whose class says it scrolls that way; Compose reports a horizontalScroll row as HorizontalScrollView, so the chip row is swiped, not the grid. ⟦HorizontalScrollView⟧", "An up or down scroll never swipes a row that says it scrolls sideways; nothing infers an axis that no class states. ⟦never swipes⟧"], "concern": "skills/mobile-check/SKILL.md#reaching-things-below-the-fold says scroll-to is for 'Vertical lists only. For a horizontal pager or carousel use mobium swipe left', but scroll-to takes --direction left/right (cmd/mobium/scroll.go:17 and :27, example 'a horizontal pager') and scrollContainerFor picks a sideways row (internal/agent/scroll.go:893). The skill is stale.", "check": "Claude's reading: CHALLENGES 358 (#262, after the pin) is the only description; scrollContainerFor in scroll.go matches it line for line. The skill's 'vertical lists only' contradicts the code; see concern. Verified in: internal/agent/scroll.go:893, cmd/mobium/scroll.go:27."}, {"id": "g033", "kind": "multi", "question": "mobium press back --gesture is refused on my Android emulator, while plain press back works. Why, and how do I check which mode the device is in?", "tags": ["troubleshooting", "test-author"], "gold": [{"id": "docs/BACK.md#mobiumapp-as-shipped", "heading": "MobiumApp as shipped", "path": "docs/BACK.md", "excerpt": "The same on all three devices, gesture navigation: | Input | After | Process | Activities | Reopened at | | --- | --- | --- | --- | --- | | key | launcher | alive | 0 | home | | right edge | launcher | alive | 0 | home | | left edge | launcher | alive | 0 | home | So the report is exact: every back from a demo left the app, its activity was destroyed, and reopening it started again at home. Settings, given the same t…"}, {"id": "docs/BACK.md#in-mobium", "heading": "In Mobium", "path": "docs/BACK.md", "excerpt": "Fixed on 2026-10-01, and held by `docs/checks/back.sh`, which passed on the Pixel 8 Pro, both AVDs, the simulator and the iPhone 15 Plus: - `press back` says what back did: \"it left <app>; <app> is in the foreground\", or \"<app> is still in the foreground\", and on iOS what the navigation bar says now. It waits for that outcome by its own clock — a back that left an app handed focus over in about 0.1s — so a back insid…"}], "retrieved": [{"id": "skills/mobile-check/SKILL.md#interruptions-and-hardware-buttons", "heading": "Interruptions and hardware buttons", "path": "skills/mobile-check/SKILL.md", "excerpt": "```sh mobium press back # primary navigation on Android; says where it went mobium press back --gesture # the swipe in from the edge; the only back on iOS mobium press home # says the launcher came forward mobium lock lock # a state, not a toggle mobium call ring # then accept, or hang mobium sms \"your code is 123456\" mobium timezone Asia/Tokyo mobium notifications # what is in the shade? mobium notifications --post …", "gold": false}, {"id": "docs/BACK.md#in-mobium", "heading": "In Mobium", "path": "docs/BACK.md", "excerpt": "Fixed on 2026-10-01, and held by `docs/checks/back.sh`, which passed on the Pixel 8 Pro, both AVDs, the simulator and the iPhone 15 Plus: - `press back` says what back did: \"it left <app>; <app> is in the foreground\", or \"<app> is still in the foreground\", and on iOS what the navigation bar says now. It waits for that outcome by its own clock — a back that left an app handed focus over in about 0.1s — so a back insid…", "gold": true}, {"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": false}, {"id": "docs/BACK.md#ios", "heading": "iOS", "path": "docs/BACK.md", "excerpt": "iOS has no system back. Going back is the app's: a navigation bar's back button, and, for a `UINavigationController`, a swipe. Mobium refuses `press back` there by design (it is not an event iOS sends); `press back --gesture` sends the swipe, starting in the navigation bar, since the measurements below found a swipe over a list row taken by the row ([In Mobium](#in-mobium)). | | MobiumApp | Control | | --- | --- | --…", "gold": false}], "missed": false, "facts": ["An edge swipe is back only in gesture navigation; with three-button navigation it does nothing, so press back --gesture is refused there and the back button (plain press back) is the user's back. ⟦three-button⟧", "The mode can be read with settings get secure navigation_mode (2 gestures, 0 three buttons), and mobium devices names an Android device's navigation mode. ⟦navigation_mode⟧"], "concern": "", "check": "Claude's reading: BACK.md 'MobiumApp as shipped' measured that edge swipes do nothing in three-button mode and gives navigation_mode values; 'In Mobium' says --gesture is refused on button navigation and devices names the mode. gestureBack returns unsupported unless the mode is gestures. Verified in: internal/agent/back.go:46, internal/agent/back.go:51."}, {"id": "g034", "kind": "fact", "question": "mobium contexts lists only NATIVE_APP for my app even though a screen clearly shows web content. Why can't Mobium see the WebView, and what has to change?", "tags": ["troubleshooting", "test-author"], "gold": [{"id": "README.md#hybrid-apps-and-webviews", "heading": "Hybrid apps and WebViews", "path": "README.md", "excerpt": "A hybrid app's web content is not usable through the accessibility tree, so Mobium attaches to the WebView, and switching context changes what `map` and `tap` operate on: ``` $ mobium contexts NATIVE_APP (current) WEBVIEW_com.example — Checkout https://shop.example/cart $ mobium context WEBVIEW_com.example $ mobium map @e1 Promo code (input) @e2 Apply (button) $ mobium tap @e2 tapped @e2 at (462, 397) in WEBVIEW_com.…"}], "retrieved": [{"id": "skills/mobile-check/SKILL.md#hybrid-apps-webviews", "heading": "Hybrid apps (WebViews)", "path": "skills/mobile-check/SKILL.md", "excerpt": "Web content inside an app is a separate context: ```sh mobium contexts # NATIVE_APP, WEBVIEW_com.example mobium context WEBVIEW_com.example # map and tap now work on the page mobium context NATIVE_APP # back to the native shell ``` This works on **both platforms**. Android WebViews must be debuggable (`setWebContentsDebuggingEnabled(true)`) and iOS WKWebViews must be inspectable (`webView.isInspectable = true` on iOS…", "gold": false}, {"id": "README.md#hybrid-apps-and-webviews", "heading": "Hybrid apps and WebViews", "path": "README.md", "excerpt": "A hybrid app's web content is not usable through the accessibility tree, so Mobium attaches to the WebView, and switching context changes what `map` and `tap` operate on: ``` $ mobium contexts NATIVE_APP (current) WEBVIEW_com.example — Checkout https://shop.example/cart $ mobium context WEBVIEW_com.example $ mobium map @e1 Promo code (input) @e2 Apply (button) $ mobium tap @e2 tapped @e2 at (462, 397) in WEBVIEW_com.…", "gold": true}, {"id": "docs/APP-TYPES.md#hybrid", "heading": "Hybrid", "path": "docs/APP-TYPES.md", "excerpt": "A native app with a WebView inside it. The article's point that a hybrid app is *technically a subcategory of native* — because the outermost component is native — is exactly the shape of Mobium's context model: `NATIVE_APP` is the shell, and each page is its own `WEBVIEW_<package>` context. The more useful observation is the one about **ratio**: some hybrid apps are almost entirely WebView, others expose a small one…", "gold": false}, {"id": "CHALLENGES#312", "heading": "312. `find` inside a WebView answered from the native screen", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** giving WebViews locators (ROADMAP, locators item 4) and checking them on MobiumApp's Actionability and Frames pages, each tap judged by what the page said it reached. With a WebView's context selected, every action named the page's element, but `find role=button` listed the app's own Back button first and then the page's buttons as the platform's accessibility saw them: `app_find` never asked which cont…", "gold": false}, {"id": "CHALLENGES#138", "heading": "138. On iOS, `contexts` listed the pages of apps not in front", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** listing contexts on the iPhone 15 Plus with Wikipedia in front and seeing Safari's page; reproduced with MobiumApp, three times in three, after opening a page in Safari and coming back. Every application webinspectord knew was asked for its pages, and every page was listed, whichever app was on screen. Switching to one attached a page that was not on screen, and a tap into it would have been aimed throu…", "gold": false}], "missed": false, "facts": ["A WebView is reachable only if the app opted in: WebView.setWebContentsDebuggingEnabled(true) on Android, isInspectable on iOS 16.4 and later; neither can be forced from outside. ⟦setWebContentsDebuggingEnabled(true) ; isInspectable⟧"], "concern": "", "check": "Claude's reading: README's hybrid section states the opt-in; noWebViewsHint gives the same remedy per platform when contexts finds none, and adds that a page must be open on iOS. SKILL 'Hybrid apps' repeats it; gold kept to README. Verified in: internal/agent/webview.go:702, internal/agent/webview.go:108."}, {"id": "g035", "kind": "fact", "question": "On an iPhone, my tap on Add to Cart is refused because the on-screen keyboard covers the button. How do I get the keyboard out of the way?", "tags": ["troubleshooting", "agent-builder"], "gold": [{"id": "skills/mobile-check/SKILL.md#when-things-fail", "heading": "When things fail", "path": "skills/mobile-check/SKILL.md", "excerpt": "Mobium's errors say what to do; read them rather than retrying blindly. Every failure also carries a **code**, so you can act on the kind without parsing the sentence: `--json` prints it (`\"code\": \"no_such_element\"`, with a `remedy` and `details`), and the exit status groups it: | Exit | Codes | What to do | | --- | --- | --- | | 2 | `invalid_argument` | fix the command; retrying it unchanged cannot help | | 3 | `no_…"}], "retrieved": [{"id": "CHALLENGES#325", "heading": "325. A button under the keyboard was blamed on another screen", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** checking 322's fix on a SwiftUI checkout app written to be tested (Morpho Market, mobiumdev/morpho-market), on the iPhone 17 Pro simulator, iOS 26.5. With the keyboard up after typing a gift card's email, Add to Cart sat under the keys, and the tap was refused: \"another screen of the app is in front of it — close the screen in front first\". There was no such screen. With the keyboard up, SwiftUI reports…", "gold": false}, {"id": "CHALLENGES#107", "heading": "107. A tap on a button under the keyboard reported success", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** the iOS login demo, where Log In sat under the keyboard; the app's layout was fixed then, and the Dialog Demo's pinned button is the case kept on purpose. The keyboard is the dialog case one layer over, in the same two shapes. On iOS the keyboard is an `XCUIElementTypeKeyboard` in the app's tree, and what it covers stays there, marked not visible — the field being typed into included — so a locator reso…", "gold": false}, {"id": "CHALLENGES#184", "heading": "184. Reading a label under the keyboard was refused as if it were a tap", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** MobiumApp's OTP Demo on an iPhone 17 Pro simulator, typing a code into the six boxes and reading back the line that says what they hold. The one-time-code number pad was up over it, and `app_text` answered \"failed check receivesEvents: the keyboard is over it\". Nothing was being touched: iOS keeps what the keyboard covers in the tree, with its text, and the text was right there — `app_find` printed it i…", "gold": false}, {"id": "docs/guides/autowait.md#3-refusing-what-is-covered", "heading": "3. Refusing what is covered", "path": "docs/guides/autowait.md", "excerpt": "The Obstruction Demo draws controls over its targets — a full cover, a half cover over the center, an edge cover that leaves the center clear, views that take no touches, an overlay hidden from accessibility, a scrim: ![The Obstruction Demo: a column of buttons, each with something drawn over it](images/autowait-5-covers.jpg) One is covered entirely by another button: ``` $ mobium tap testid=fullTarget error: testid=…", "gold": false}, {"id": "CHALLENGES#230", "heading": "230. With the iOS keyboard up, every action in a WebView was refused", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** typing into MobiumApp's cross-origin frame field on the iPhone simulator (CHALLENGES 229), and then on its Web form, which has no frames: once a tap on a web field raised the keyboard, a `type` or a `tap` in the same WebView was refused — \"the WebView element is 584 CSS pixels tall but the page's viewport is 571, so the page does not fill its host\". That check was written for mobile Safari, whose chrome…", "gold": false}], "missed": true, "facts": ["On an iPhone, which has no hide key, use mobium keyboard --key enter; elsewhere mobium keyboard --hide. ⟦keyboard --key enter ; keyboard --hide⟧"], "concern": "", "check": "Claude's reading: the skill's receivesEvents bullet gives both commands; handlers.go's hideKeyboard remedy text says the same, naming the iPhone's missing hide key. CHALLENGES 325 shows keyboard --key enter working on a simulator but is not needed. Verified in: internal/agent/handlers.go:1237."}, {"id": "g036", "kind": "fact", "question": "Can Mobium move the two thumbs of a range slider in an Android app built with Views, using the Material Components RangeSlider rather than Compose?", "tags": ["support", "test-author", "new since 7b590a4"], "gold": [{"id": "docs/ROADMAP.md#under-consideration", "heading": "Under consideration", "path": "docs/ROADMAP.md", "excerpt": "- **Locators for when there is no ref** (written down 2026-10-12). A ref from `map` lasts one map, so an agent has one and a `mobium test` file does not: a hand-written test has the flat `kind=value` locators — text, label, testid, role, class, path, narrowed by `,role=` — which match one element or are refused. That is right on a form and leaves nothing durable on a list. Every Ice Cubes post has a \"…\" (CHALLENGES 2…"}], "retrieved": [{"id": "docs/ROADMAP.md#under-consideration", "heading": "Under consideration", "path": "docs/ROADMAP.md", "excerpt": "- **Locators for when there is no ref** (written down 2026-10-12). A ref from `map` lasts one map, so an agent has one and a `mobium test` file does not: a hand-written test has the flat `kind=value` locators — text, label, testid, role, class, path, narrowed by `,role=` — which match one element or are refused. That is right on a form and leaves nothing durable on a list. Every Ice Cubes post has a \"…\" (CHALLENGES 2…", "gold": true}, {"id": "CHALLENGES#320", "heading": "320. A two-thumb slider built from ARIA was not in `map`, and one built from ranges moved the wrong thumb", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** measuring two-thumb sliders, as pages build them, on MobiumApp's Slider Demo: Price, two `<input type=\"range\">` laid over one track, the minimum kept at or below the maximum by the page; and Hours, two `role=\"slider\"` thumbs on a drawn track, moved by a finger or the arrow keys, the way component libraries build one. Hours was not in `map` at all: the list of a page's elements had no `[role=slider]`. Pr…", "gold": false}, {"id": "CHALLENGES#357", "heading": "357. A two-thumb slider: a fill that moved nothing said it moved, and a thumb at the edge closed the app", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** native two-thumb sliders (ROADMAP, \"Sliders\"), on a price range added to Morpho Market for them — Material 3's `RangeSlider` on Android, and on iOS a control the app draws, since SwiftUI has none. Three things, each measured on the Android 15 emulator and the iPhone 17 Pro simulator: - **A fill that moved nothing was reported as moved.** Material reports each thumb as a seek bar the size of the thumb — …", "gold": false}, {"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": false}], "missed": false, "facts": ["Native two-thumb sliders are done for Material 3's RangeSlider in Compose and an iOS app's own (since 2026-10-22); a View-system RangeSlider (Material Components) is not yet supported, nor measured on a phone. ⟦View-system ; Material 3⟧"], "concern": "", "check": "Claude's reading: ROADMAP 'Under consideration', Sliders entry, says not yet for a View-system RangeSlider; RangeThumb needs two slider children under one parent, which the Compose and iOS builds give — a View RangeSlider is one view, so it would not be recognized. That last point is my reading of the code, not measured. Verified in: internal/uitree/rangethumb.go:7."}, {"id": "g037", "kind": "fact", "question": "Why does mobium tap @e5 look the element up again instead of tapping the coordinates that mobium map printed for it?", "tags": ["rationale", "new-user"], "gold": [{"id": "README.md#refs", "heading": "Refs", "path": "README.md", "excerpt": "`mobium map` snapshots the accessibility hierarchy, keeps the nodes a person could act on, and gives each one the most durable locator that identifies it uniquely — a resource-id if there is one, then an accessibility label, then visible text, and a sibling path only as a last resort. `mobium tap @e5` **re-snapshots and re-resolves** that locator before touching anything. It never replays the coordinates from the map…"}], "retrieved": [{"id": "README.md#refs", "heading": "Refs", "path": "README.md", "excerpt": "`mobium map` snapshots the accessibility hierarchy, keeps the nodes a person could act on, and gives each one the most durable locator that identifies it uniquely — a resource-id if there is one, then an accessibility label, then visible text, and a sibling path only as a last resort. `mobium tap @e5` **re-snapshots and re-resolves** that locator before touching anything. It never replays the coordinates from the map…", "gold": true}, {"id": "docs/ARCHITECTURE.md#one-call-end-to-end", "heading": "One call, end to end", "path": "docs/ARCHITECTURE.md", "excerpt": "`mobium tap @e5`, on Android with the default backend: ```mermaid sequenceDiagram participant CLI as mobium tap @e5 participant D as daemon participant A as internal/agent participant U as uiautomator2 driver participant S as UiAutomator2 server CLI->>D: tools/call app_tap {target: \"@e5\"} D->>A: dispatch A->>A: look up @e5's locator from the last map loop until settled, or the wait runs out A->>U: snapshot U->>S: GET…", "gold": false}, {"id": "skills/mobile-check/SKILL.md#core-workflow", "heading": "Core Workflow", "path": "skills/mobile-check/SKILL.md", "excerpt": "Every automation follows the same loop: 1. **Map**: `mobium map` — lists what is on screen as `@e1`, `@e2`, … 2. **Act**: `mobium tap @e5`, `mobium type @e2 \"text\"`, `mobium swipe up` 3. **Re-map**: after anything that changes the screen, run `mobium map` again **Refs are only valid for the screen they were taken from.** A ref is re-resolved against a fresh snapshot before every action, so a stale one fails loudly ra…", "gold": false}, {"id": "skills/mobile-check/SKILL.md#acting", "heading": "Acting", "path": "skills/mobile-check/SKILL.md", "excerpt": "Every action waits, for up to two seconds, until its target is on screen, **enabled** and holding still, and refuses — with a reason and a remedy — rather than tapping something a user could not: a target under a system dialog or under the keyboard, a control that stays disabled, or a button passed to `type`. - `mobium tap @e5` — tap a ref - `mobium tap \"text=Sign In\"` — tap by locator, no map needed - `mobium tap 54…", "gold": false}, {"id": "skills/mobile-check/SKILL.md#when-things-fail", "heading": "When things fail", "path": "skills/mobile-check/SKILL.md", "excerpt": "Mobium's errors say what to do; read them rather than retrying blindly. Every failure also carries a **code**, so you can act on the kind without parsing the sentence: `--json` prints it (`\"code\": \"no_such_element\"`, with a `remedy` and `details`), and the exit status groups it: | Exit | Codes | What to do | | --- | --- | --- | | 2 | `invalid_argument` | fix the command; retrying it unchanged cannot help | | 3 | `no_…", "gold": false}], "missed": false, "facts": ["tap re-snapshots and re-resolves the ref's locator before touching anything. ⟦re-resolves / re-snapshots⟧", "It never replays map's coordinates because the screen moves between commands, and a tap at a stale point fails silently; a locator that became ambiguous is refused rather than guessed. ⟦stale point⟧"], "concern": "", "check": "Claude's reading: README 'Refs' gives the reason; the comment on resolveNode says every action re-snapshots, since acting on a node from an older snapshot lands on whatever moved into its place. Verified in: internal/agent/handlers.go:1548."}, {"id": "g038", "kind": "fact", "question": "Why does Mobium refuse press-tap (hold one finger, then tap with a second) on an iPhone instead of just sending it?", "tags": ["rationale", "test-author"], "gold": [{"id": "docs/GESTURES.md#three-ways-a-second-finger-went-wrong", "heading": "Three ways a second finger went wrong", "path": "docs/GESTURES.md", "excerpt": "All three were found by a witness, and none was visible to the tool, which reported every gesture as delivered until the last one, which reported a failure and left the device unable to accept any touch at all. **UiAutomator2 forgets a finger that pauses.** It builds each step's Android `MotionEvent` from the fingers that have an event *in that step*, and counts the fingers already down from the same events. A holdin…"}], "retrieved": [{"id": "docs/GESTURES.md#three-ways-a-second-finger-went-wrong", "heading": "Three ways a second finger went wrong", "path": "docs/GESTURES.md", "excerpt": "All three were found by a witness, and none was visible to the tool, which reported every gesture as delivered until the last one, which reported a failure and left the device unable to accept any touch at all. **UiAutomator2 forgets a finger that pauses.** It builds each step's Android `MotionEvent` from the fingers that have an event *in that step*, and counts the fingers already down from the same events. A holdin…", "gold": true}, {"id": "CHALLENGES#86", "heading": "86. On Android 16 and later, one press-tap breaks injected touch for the whole device", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** the gesture check on a Pixel 8 Pro (Android 17), where press-tap failed with UiAutomator2's \"Unable to perform W3C actions\" — and then so did everything after it, plain taps included, and `adb shell input tap` too. UiAutomator2 (10.6.6, the newest release) stamps each event with the down time of the finger that produced it (`startTimestamp + event.startDelta`, the chain's own `pointerDown`). Android's c…", "gold": false}, {"id": "CHALLENGES#149", "heading": "149. `double-tap` reached a React Native control on iOS as one press", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** a person, as the control ROADMAP had asked for: Lana double-tapped MobiumApp's Press target on the iPhone 15 Plus and it counted two presses 200ms apart, where `double-tap` on the same target counted one. Mobium used WebDriverAgent's own double-tap endpoint, Apple's primitive, and a React Native `Pressable` reports that as one press — which 70 had taken for the Pressable coalescing any double tap. The W…", "gold": false}, {"id": "docs/guides/autowait.md#auto-wait-what-an-action-waits-for-and-what-it-refuses", "heading": "Auto-wait: what an action waits for, and what it refuses", "path": "docs/guides/autowait.md", "excerpt": "A tap in Mobium is not a touch at some coordinates. Before it touches anything, an action finds its target on a fresh read of the screen and checks that a finger could really press it. It **waits** for the checks that time can fix, and **refuses** the ones it can't — with a reason, never with a touch somewhere else reported as success. This guide goes through each check on [MobiumApp](https://github.com/mobiumdev/mob…", "gold": false}, {"id": "docs/GESTURES.md#the-chart", "heading": "The chart", "path": "docs/GESTURES.md", "excerpt": "Three sources name the gestures, and they agree more than they differ: the familiar touch-gesture reference chart (tap, double tap, drag, flick, pinch, spread, press, press and tap, press and drag, rotate), Apple's Human Interface Guidelines (tap, swipe, drag, touch and hold, double tap, zoom, rotate), and Android's Compose gesture guide (tap, double tap, long press and press through `detectTapGestures`; drag in thre…", "gold": false}], "missed": false, "facts": ["XCTest (through WebDriverAgent) gives a finger that lands after the gesture began an extra zero-length touch at its target at time zero. ⟦zero-length touch⟧", "An app can read that instant touch as a tap before the gesture, so Mobium refuses press-tap and press-drag on iOS rather than send a gesture that is also something else; multi-finger taps are unaffected. ⟦refuses press-tap⟧"], "concern": "", "check": "Claude's reading: GESTURES.md 'Three ways a second finger went wrong' explains it; errLateFinger in multitouch.go carries the same reason. Android 16+ is refused for a different reason (UiAutomator2's down time), in the same section's second part — not asked here. Verified in: internal/mobiumdriver/multitouch.go:181."}, {"id": "g039", "kind": "unanswerable", "question": "How do I raise Mobium's implicit wait so every tap waits up to 10 seconds for its target instead of 2?", "tags": ["how-to", "test-author"], "gold": [], "retrieved": [{"id": "skills/mobile-check/SKILL.md#waiting", "heading": "Waiting", "path": "skills/mobile-check/SKILL.md", "excerpt": "Never sleep. Every action already retries for two seconds while the screen settles, so a tap straight after a launch or another tap is fine. When something takes longer than that — a login, a network fetch — wait for the thing itself rather than for a duration: - `mobium wait \"text=Welcome back\"` — until it is on screen - `mobium wait 'text=\"Wi-Fi\"'` — quoted: the whole text, so a part of it on the screen you are lea…", "gold": false}, {"id": "skills/mobile-check/SKILL.md#acting", "heading": "Acting", "path": "skills/mobile-check/SKILL.md", "excerpt": "Every action waits, for up to two seconds, until its target is on screen, **enabled** and holding still, and refuses — with a reason and a remedy — rather than tapping something a user could not: a target under a system dialog or under the keyboard, a control that stays disabled, or a button passed to `type`. - `mobium tap @e5` — tap a ref - `mobium tap \"text=Sign In\"` — tap by locator, no map needed - `mobium tap 54…", "gold": false}, {"id": "docs/guides/autowait.md#1-waiting-for-something-to-stop-moving", "heading": "1. Waiting for something to stop moving", "path": "docs/guides/autowait.md", "excerpt": "The Motion Demo's Replay button slides a target in over two seconds. Tap the target the moment after Replay, with no sleep in between: ``` $ mobium tap testid=ignoringReplay tapped testid=ignoringReplay at (540, 1315) $ mobium tap testid=ignoringTarget tapped testid=ignoringTarget at (316, 1472) $ mobium text testid=ignoringResult Ignoring: tapped 2697ms after replay ``` | Just after Replay: the target still sliding …", "gold": false}, {"id": "docs/guides/graybox-tutorial.md#1-the-test", "heading": "1. The test", "path": "docs/guides/graybox-tutorial.md", "excerpt": "The Busy Demo's **Refresh quietly** starts 0.4 to 1.6 seconds of work and leaves the old rows up while it runs; then a new generation of rows replaces them. Tapping a row says whether it was `current` or `stale`. The test taps the refresh, then Row B, and expects the row to be current — five times, each from a fresh app: ``` busy-tests/ mobium.config.json tests/ busy.test.json ``` ```json { \"testDir\": \"tests\", \"proje…", "gold": false}, {"id": "docs/guides/graybox.md#what-an-action-does", "heading": "What an action does", "path": "docs/guides/graybox.md", "excerpt": "Before an action finds its target, it waits until the app has nothing in flight. The result says what it waited for (the iPhone): ``` $ mobium tap testid=busyQuiet tapped testid=busyQuiet at (645, 1011) gray box: waited 35 ms for the app to go idle $ mobium tap testid=busyRowB tapped testid=busyRowB at (645, 1218) gray box: waited 1018 ms for the app to go idle (busy: quiet) $ mobium text testid=busyOutcome row B, ge…", "gold": false}], "missed": false, "facts": [], "concern": "", "check": "Claude's reading: the docs state the 2-second implicit wait but never say whether it can be changed; no flag, env var or argument sets it — implicitWait is a constant (wait.go:32) whose comment says longer waits belong in an explicit wait. A retriever will return the checks table and mobium wait's --timeout, which answers a different question. Nearest sections: docs/guides/autowait.md#the-checks, skills/mobile-check/SKILL.md#acting, docs/guides/autowait.md#5-waiting-on-purpose-mobium-wait. Verified in: internal/agent/wait.go:32."}, {"id": "g040", "kind": "unanswerable", "question": "How long does mobium long-press hold the press by default when I don't pass --duration?", "tags": ["behavior", "test-author"], "gold": [], "retrieved": [{"id": "CHALLENGES#126", "heading": "126. On iOS a drag never held before it moved", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** the same run on an iPhone 17 Pro simulator. MobiumApp's drop zone measures the hold before a drag moves: asked for 1500ms, it read 183ms, three times in three, while the hold before the finger lifted arrived in full at 1517ms. The drop still succeeded, which is why `GESTURES.md` had drag down as working on iOS; but a list that arms reordering on a long press would never have armed. WebDriverAgent shorte…", "gold": false}, {"id": "skills/mobile-check/SKILL.md#waiting", "heading": "Waiting", "path": "skills/mobile-check/SKILL.md", "excerpt": "Never sleep. Every action already retries for two seconds while the screen settles, so a tap straight after a launch or another tap is fine. When something takes longer than that — a login, a network fetch — wait for the thing itself rather than for a duration: - `mobium wait \"text=Welcome back\"` — until it is on screen - `mobium wait 'text=\"Wi-Fi\"'` — quoted: the whole text, so a part of it on the screen you are lea…", "gold": false}, {"id": "skills/mobile-check/SKILL.md#acting", "heading": "Acting", "path": "skills/mobile-check/SKILL.md", "excerpt": "Every action waits, for up to two seconds, until its target is on screen, **enabled** and holding still, and refuses — with a reason and a remedy — rather than tapping something a user could not: a target under a system dialog or under the keyboard, a control that stays disabled, or a button passed to `type`. - `mobium tap @e5` — tap a ref - `mobium tap \"text=Sign In\"` — tap by locator, no map needed - `mobium tap 54…", "gold": false}, {"id": "docs/guides/autowait.md#5-waiting-on-purpose-mobium-wait", "heading": "5. Waiting on purpose: `mobium wait`", "path": "docs/guides/autowait.md", "excerpt": "The checks above make each action wait for its own target. For everything else — a result to arrive, a spinner to go, a state to change — say what you are waiting for, instead of sleeping: ``` $ mobium wait testid=loginError --for text --text \"Incorrect username or password.\" --exact testid=loginError says exactly \"Incorrect username or password.\" after 1.631s — @e1 ScrollView (list) ``` It returned as soon as the te…", "gold": false}, {"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": false}], "missed": false, "facts": [], "concern": "", "check": "Claude's reading: the default is 800ms in code (CLI flag and app_long_press's duration_ms), but no corpus section states it; GESTURES only says a 50ms hold must read as a tap, and FLAGS lists --duration without a default. CHALLENGES 86 mentions --lead-ms 800 for press-tap, a likely false match. Nearest sections: docs/GESTURES.md#the-chart, skills/mobile-check/SKILL.md#acting, docs/FLAGS.md#commands-and-what-they-send. Verified in: cmd/mobium/swipe.go:75, internal/agent/handlers.go:2466."}, {"id": "g041", "kind": "fact", "question": "I recorded a flow in mobium inspect. How do I get it as a Python program instead of a .test.json file, and which device will that program drive?", "tags": ["how-to", "test-author", "new since 7b590a4"], "gold": [{"id": "docs/guides/inspector.md#5-download-it-as-code", "heading": "5. Download it as code", "path": "docs/guides/inspector.md", "excerpt": "Next to **Download**, pick the language: the test file, or a program in Python, JavaScript, Go, Java or .NET. Every step is one tool call and every client has every tool, so the program is the same steps through the client's own methods, starting from the app launched fresh. The Table Demo recording above, as Python: ```python # Recorded with mobium inspect. from mobium import start with start() as device: device.ter…"}], "retrieved": [{"id": "docs/guides/inspector.md#5-download-it-as-code", "heading": "5. Download it as code", "path": "docs/guides/inspector.md", "excerpt": "Next to **Download**, pick the language: the test file, or a program in Python, JavaScript, Go, Java or .NET. Every step is one tool call and every client has every tool, so the program is the same steps through the client's own methods, starting from the app launched fresh. The Table Demo recording above, as Python: ```python # Recorded with mobium inspect. from mobium import start with start() as device: device.ter…", "gold": true}, {"id": "docs/guides/inspector.md#4-record-a-test", "heading": "4. Record a test", "path": "docs/guides/inspector.md", "excerpt": "A test starts from a freshly launched app, so a recording should too: **Start from a fresh app** stops the app in front and launches it again, as `mobium test` does before each test, and starts recording. From there, every action is a step. Recorded on the Login Demo: ```json { \"app\": \"dev.mobium.mobiumapp\", \"description\": \"Recorded with mobium inspect.\", \"tests\": [ { \"name\": \"recorded\", \"steps\": [ {\"tap\": \"text=Logi…", "gold": false}, {"id": "docs/guides/test-runner.md#the-commands", "heading": "The commands", "path": "docs/guides/test-runner.md", "excerpt": "| Command | What it does | | --- | --- | | `mobium test` | runs every `*.test.json` under the config's `testDir`, on every project | | `mobium test tests/login.test.json` | runs one file, or every file under a directory | | `mobium test -g login` | runs the tests whose title — \"file › name\" — matches a regular expression | | `mobium test --last-failed` | runs only the tests that failed last time | | `mobium test --pr…", "gold": false}, {"id": "docs/DEVELOPMENT.md#5-work-on-a-client", "heading": "5. Work on a client", "path": "docs/DEVELOPMENT.md", "excerpt": "Each client's tests start a fake `mobium` and need no device: | Client | Its tests | Run a program against it from this clone | | --- | --- | --- | | Python | `make clients` | `pip install ./clients/python` in a virtualenv | | JavaScript | `make clients` | `npm install ./clients/javascript` | | Go | `make test` | `go mod edit -replace=github.com/mobiumdev/mobium/clients/go=<path to this clone>/clients/go` in your mod…", "gold": false}, {"id": "docs/checks/README.md#device-checks", "heading": "Device checks", "path": "docs/checks/README.md", "excerpt": "Scripts that drive a real flow end to end through mobium's CLI and assert on the result. Not part of `make ci` — they need a device — but they are the thing [RELEASE-CHECKLIST.md](../RELEASE-CHECKLIST.md) asks you to run, written down so nobody has to invent them again. ```sh ./docs/checks/calculator.sh emulator-5554 ./docs/checks/calculator.sh <serial> ``` Getting a device attached in the first place is [../SETUP.md…", "gold": false}], "missed": false, "facts": ["Next to Download in the inspector, pick the language: the test file, or a program in Python, JavaScript, Go, Java or .NET. ⟦pick the language⟧", "The program starts from the app launched fresh (terminated, then launched), as mobium test starts each test. ⟦the app launched fresh⟧", "The program names no device: start() takes the only one running, and start(device=...) names one. ⟦start(device=...)⟧"], "concern": "", "check": "Claude's reading: inspector.md section 5 (added in #261, after 7b590a4) answers all three; codegen.Program prepends app_terminate and app_launch, and the Python writer emits `with start() as device:`. The device-selection part comes from the same section, so the question stays a single fact. Verified in: internal/codegen/codegen.go:24, internal/codegen/codegen.go:46, internal/codegen/languages.go:21, internal/inspect/inspect.go:464."}, {"id": "g042", "kind": "fact", "question": "While I click through my app in the inspector, how can I have the recording written into a file in my project as it grows, and which kinds of file can it write?", "tags": ["how-to", "test-author", "new since 7b590a4"], "gold": [{"id": "docs/guides/inspector.md#4-record-a-test", "heading": "4. Record a test", "path": "docs/guides/inspector.md", "excerpt": "A test starts from a freshly launched app, so a recording should too: **Start from a fresh app** stops the app in front and launches it again, as `mobium test` does before each test, and starts recording. From there, every action is a step. Recorded on the Login Demo: ```json { \"app\": \"dev.mobium.mobiumapp\", \"description\": \"Recorded with mobium inspect.\", \"tests\": [ { \"name\": \"recorded\", \"steps\": [ {\"tap\": \"text=Logi…"}], "retrieved": [{"id": "docs/guides/inspector.md#5-download-it-as-code", "heading": "5. Download it as code", "path": "docs/guides/inspector.md", "excerpt": "Next to **Download**, pick the language: the test file, or a program in Python, JavaScript, Go, Java or .NET. Every step is one tool call and every client has every tool, so the program is the same steps through the client's own methods, starting from the app launched fresh. The Table Demo recording above, as Python: ```python # Recorded with mobium inspect. from mobium import start with start() as device: device.ter…", "gold": false}, {"id": "docs/guides/inspector.md#4-record-a-test", "heading": "4. Record a test", "path": "docs/guides/inspector.md", "excerpt": "A test starts from a freshly launched app, so a recording should too: **Start from a fresh app** stops the app in front and launches it again, as `mobium test` does before each test, and starts recording. From there, every action is a step. Recorded on the Login Demo: ```json { \"app\": \"dev.mobium.mobiumapp\", \"description\": \"Recorded with mobium inspect.\", \"tests\": [ { \"name\": \"recorded\", \"steps\": [ {\"tap\": \"text=Logi…", "gold": true}, {"id": "docs/ROADMAP.md#under-consideration", "heading": "Under consideration", "path": "docs/ROADMAP.md", "excerpt": "- **Locators for when there is no ref** (written down 2026-10-12). A ref from `map` lasts one map, so an agent has one and a `mobium test` file does not: a hand-written test has the flat `kind=value` locators — text, label, testid, role, class, path, narrowed by `,role=` — which match one element or are refused. That is right on a form and leaves nothing durable on a list. Every Ice Cubes post has a \"…\" (CHALLENGES 2…", "gold": false}, {"id": "CHALLENGES#314", "heading": "314. A recording wrote locators that named less than `map` had, and refs", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** writing down a recording as code (ROADMAP, #202) and reading the recorder's `target` for what it would emit. Two things, both measured after: `map` derives every native locator as the whole value and checks it names one element so (`uitree.Derive`), and the inspector rebuilt it without `Exact`. So it recorded `text=Welcome`, which \"Welcome back\" meets too: the race of CHALLENGES 233, written into a test…", "gold": false}], "missed": false, "facts": ["mobium inspect --record <file> writes the recording after every step. ⟦--record⟧", "The file is a .test.json, or a program chosen by its extension: .py, .mjs, .go, .java or .cs, the same file the download gives. ⟦.mjs ; .cs⟧"], "concern": "", "check": "Claude's reading: the --record paragraph sits at the end of inspector.md section 4, not section 5, which is why the gold is #4; the extension table in codegen.go matches the doc's five. New since the pin (#261). Verified in: cmd/mobium/inspect.go:30, cmd/mobium/inspect.go:72, internal/codegen/codegen.go:28, internal/inspect/inspect.go:57."}, {"id": "g043", "kind": "fact", "question": "My inspector recording includes a two-finger tap. What happens when I try to download it as a Go program?", "tags": ["behavior", "test-author", "new since 7b590a4"], "gold": [{"id": "docs/guides/inspector.md#5-download-it-as-code", "heading": "5. Download it as code", "path": "docs/guides/inspector.md", "excerpt": "Next to **Download**, pick the language: the test file, or a program in Python, JavaScript, Go, Java or .NET. Every step is one tool call and every client has every tool, so the program is the same steps through the client's own methods, starting from the app launched fresh. The Table Demo recording above, as Python: ```python # Recorded with mobium inspect. from mobium import start with start() as device: device.ter…"}], "retrieved": [{"id": "CHALLENGES#86", "heading": "86. On Android 16 and later, one press-tap breaks injected touch for the whole device", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** the gesture check on a Pixel 8 Pro (Android 17), where press-tap failed with UiAutomator2's \"Unable to perform W3C actions\" — and then so did everything after it, plain taps included, and `adb shell input tap` too. UiAutomator2 (10.6.6, the newest release) stamps each event with the down time of the finger that produced it (`startTimestamp + event.startDelta`, the chain's own `pointerDown`). Android's c…", "gold": false}, {"id": "CHALLENGES#84", "heading": "84. UiAutomator2 forgets a finger that pauses", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** press-tap, on the Multi-Touch pad, which said \"one finger\" for a gesture the tool reported as two. Android's own pointer-location overlay agreed — `P: 0 / 1`, against `P: 0 / 2` for a two-finger tap, its control. UiAutomator2 (10.6.6, `ActionsExecutor.executeMotionEvents`) builds each W3C step's `MotionEvent` from the fingers that have an event in that step, and counts the fingers already down from the …", "gold": false}, {"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": false}, {"id": "CHALLENGES#67", "heading": "67. WebDriverAgent honors a pause only while the finger is down", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** a double tap that the page refused to call one. `app_tap --double` on Android made a WKWebView's counterpart fire `dblclick` immediately; on iOS the same code produced two clicks and no double, every time. Instrumenting the page gave the answer in one line. The touch stream was `down 43452, up 43519, down 43519, up 43586` — two taps, 67ms each, and **zero milliseconds between them**. The 120ms pause bet…", "gold": false}, {"id": "docs/GESTURES.md#three-ways-a-second-finger-went-wrong", "heading": "Three ways a second finger went wrong", "path": "docs/GESTURES.md", "excerpt": "All three were found by a witness, and none was visible to the tool, which reported every gesture as delivered until the last one, which reported a failure and left the device unable to accept any touch at all. **UiAutomator2 forgets a finger that pauses.** It builds each step's Android `MotionEvent` from the fingers that have an event *in that step*, and counts the fingers already down from the same events. A holdin…", "gold": false}], "missed": true, "facts": ["A step the language table cannot write exactly, such as a two-finger tap or a wait for a count, is refused when you download, naming the step, rather than written as a different step. ⟦refused when you download⟧", "For such a recording, download the test file instead. ⟦download the test file⟧"], "concern": "", "check": "Claude's reading: codegen.unsupported returns an unsupported error \"step N (...) cannot be written as code\" with the remedy \"download the recording as a test file and run it with mobium test\", matching the doc. Note the code also refuses an expect or soft step (codegen.go:52), which the doc does not mention but the inspector records waits, not expects. Verified in: internal/codegen/codegen.go:67, internal/codegen/codegen.go:77, internal/codegen/codegen.go:104."}, {"id": "g044", "kind": "fact", "question": "In a list where every row has its own More button, why does the inspector record my tap on one of them with a `within` locator instead of the path that map showed for that button?", "tags": ["rationale", "test-author", "new since 7b590a4"], "gold": [{"id": "docs/guides/inspector.md#4-record-a-test", "heading": "4. Record a test", "path": "docs/guides/inspector.md", "excerpt": "A test starts from a freshly launched app, so a recording should too: **Start from a fresh app** stops the app in front and launches it again, as `mobium test` does before each test, and starts recording. From there, every action is a step. Recorded on the Login Demo: ```json { \"app\": \"dev.mobium.mobiumapp\", \"description\": \"Recorded with mobium inspect.\", \"tests\": [ { \"name\": \"recorded\", \"steps\": [ {\"tap\": \"text=Logi…"}], "retrieved": [{"id": "docs/guides/inspector.md#4-record-a-test", "heading": "4. Record a test", "path": "docs/guides/inspector.md", "excerpt": "A test starts from a freshly launched app, so a recording should too: **Start from a fresh app** stops the app in front and launches it again, as `mobium test` does before each test, and starts recording. From there, every action is a step. Recorded on the Login Demo: ```json { \"app\": \"dev.mobium.mobiumapp\", \"description\": \"Recorded with mobium inspect.\", \"tests\": [ { \"name\": \"recorded\", \"steps\": [ {\"tap\": \"text=Logi…", "gold": true}, {"id": "CHALLENGES#356", "heading": "356. A recorded look-alike was named by its path, which the next row moves", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** building the recording as code (ROADMAP, \"A recording as code\", item 4) and recording a tap on MobiumApp's Table Demo, where every row has a More and a Delete. `map` names a look-alike by `path=` when nothing else names it alone — Item 2's More was `path=0/0/0/0/0/0/4/0/8` — and the recorder kept whatever `map` gave, so the test held the More's place in the tree. A path is the element's index under each…", "gold": false}, {"id": "CHALLENGES#307", "heading": "307. A scoped locator found the switch in the row beside it", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** the first run on a device of `within`, which scopes a locator to a row — `label=More within text=Card 8`, the More in Card 8's row. The rule keeps, of the target's matches, the one nearest the anchor, climbing from the anchor and stopping at the list, so a row without the target finds nothing rather than its neighbor's. The tests passed on lists built for them, each marked `scrollable=\"true\"`. On the An…", "gold": false}, {"id": "CHALLENGES#236", "heading": "236. A checkmark mapped as a target of its own, under its image's name", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** Pocket Casts' onboarding, on the simulator and the iPhone. Its \"Receive Notifications\" row is a button the app labeled whole, and inside it one button iOS calls not accessible draws the checkmark. `map` listed both, the checkmark as `discover_tick (button)` — the name of the image it draws, since the app gave it none — because the rule that put Ice Cubes' Reply, Boost, Favorite and Share in `map` (214) …", "gold": false}, {"id": "docs/guides/inspector.md#2-find-the-locator-for-anything", "heading": "2. Find the locator for anything", "path": "docs/guides/inspector.md", "excerpt": "![The inspector on MobiumApp's Login Demo: the username field selected, its locator testid=username, its role, ref and bounds, and both buttons outlined in orange for role=button](images/inspector.jpg) Click an element on the screen, or in the list under it. The panel says what `map` says of it — label, role, ref, bounds, checked state — and, at the top, **the locator a test should use**: the one `map` derived as the…", "gold": false}], "missed": false, "facts": ["A path (and a ref) names the element on this screen only: a ref lasts one map, and a path moves whenever the list adds or reuses a row, so a replay would tap another row's button or none. ⟦adds or reuses a row⟧", "The recorder tries the element's name within the nearest element with a locator or within a text on the screen, then its place among the look-alikes with nth=, keeping a candidate only if find shows it names that element alone. ⟦among the look-alikes⟧"], "concern": "", "check": "Claude's reading: inspector.md section 4 explains the scoping and why; CHALLENGES 356 tells the same story as a defect but is not needed for the answer, so it is left out of gold (a retriever may bring it back, which is fine). New since the pin (#261). Verified in: internal/inspect/inspect.go:308, internal/inspect/inspect.go:347, internal/inspect/inspect.go:364."}, {"id": "g045", "kind": "fact", "question": "I want one sign-in test to run with several different bad passwords and show up as separate results. How do I write that in a .test.json file?", "tags": ["how-to", "test-author"], "gold": [{"id": "docs/guides/test-runner.md#9-one-test-over-several-cases-each", "heading": "9. One test over several cases: `each`", "path": "docs/guides/test-runner.md", "excerpt": "A test with `\"each\"` runs once per case, as a test of its own. `${key}` in any string of its steps is that case's value; a string that is nothing but `${key}` keeps the value's type, so a count stays a number. `$${` writes a literal `${`. ```json {\"name\": \"a bad sign-in is refused, and says why: ${why}\", \"each\": [ {\"why\": \"a wrong password\", \"pass\": \"wrongpass1\", \"error\": \"loginError\"}, {\"why\": \"a short password\", \"p…"}], "retrieved": [{"id": "docs/guides/test-runner.md#9-one-test-over-several-cases-each", "heading": "9. One test over several cases: `each`", "path": "docs/guides/test-runner.md", "excerpt": "A test with `\"each\"` runs once per case, as a test of its own. `${key}` in any string of its steps is that case's value; a string that is nothing but `${key}` keeps the value's type, so a count stays a number. `$${` writes a literal `${`. ```json {\"name\": \"a bad sign-in is refused, and says why: ${why}\", \"each\": [ {\"why\": \"a wrong password\", \"pass\": \"wrongpass1\", \"error\": \"loginError\"}, {\"why\": \"a short password\", \"p…", "gold": true}, {"id": "docs/guides/test-runner.md#1-a-config-and-a-test-file", "heading": "1. A config and a test file", "path": "docs/guides/test-runner.md", "excerpt": "``` login-tests/ mobium.config.json tests/ login.test.json ``` `mobium.config.json` says where the tests are and which devices they run on. A **project** is a device to run on: ```json { \"testDir\": \"tests\", \"projects\": [ {\"name\": \"android\", \"device\": \"emulator-5554\"} ] } ``` `tests/login.test.json` is two tests of MobiumApp's Login Demo. Each step is exactly what [`app_batch`](../API.md) takes — a tool and its argume…", "gold": false}, {"id": "docs/guides/test-runner.md#writing-tests", "heading": "Writing tests", "path": "docs/guides/test-runner.md", "excerpt": "- **Find targets with `map` first.** `mobium map` on the screen you are testing gives each element's locator; `testid=` is the one that survives a translation and a redesign. - **Assert with `app_wait_for`**, never a sleep. `--for` in the CLI is `condition` in a step: `visible`, `hidden`, `text` (with `exact`), `value`, `enabled`, `disabled`, `checked`, `unchecked`, `selected`, `unselected`, `focused`, `count`, and `…", "gold": false}, {"id": "docs/guides/test-runner.md#2-run-it", "heading": "2. Run it", "path": "docs/guides/test-runner.md", "excerpt": "From the directory with the config: ``` $ mobium test ok [android] login.test.json › a wrong password is refused (7.7s) ok [android] login.test.json › the demo account signs in (7.8s) 2 passed (15.5s) ``` Exit status 0. Nothing in the test sleeps: every action waits for its own target ([auto-wait](autowait.md)), and every assertion retries until it holds or its timeout — ten seconds unless the step says otherwise.", "gold": false}, {"id": "docs/guides/test-runner.md#3-a-failure-and-what-it-leaves", "heading": "3. A failure, and what it leaves", "path": "docs/guides/test-runner.md", "excerpt": "Change the first test to expect a message the app never shows — `\"text\": \"Wrong password.\"`, with `\"timeout_ms\": 3000` — and run just that test, with all three reports: ``` $ mobium test -g \"wrong password\" --reporter list,junit,html FAIL [android] login.test.json › a wrong password is refused (9.5s) step 4 (app_wait_for): [timeout] step 4 of 4 (app_wait_for) failed: timed out after 3.012s waiting for testid=loginErr…", "gold": false}], "missed": false, "facts": ["Give the test an \"each\" array of cases; ${key} in any string of its steps is that case's value, and each case runs as a test of its own. ⟦\"each\" ; ${key}⟧", "Without a ${key} in the test's name the cases are numbered [1], [2] rather than named after values that may be a password. ⟦[1]⟧", "Each case starts over: the app is stopped and launched and beforeEach runs again. ⟦starts over⟧"], "concern": "", "check": "Claude's reading: expandEach in file.go makes one test per case, names unnamed cases \"<name> [i]\", keeps a lone ${key}'s type, and refuses a missing key, all as test-runner.md section 9 says. Verified in: internal/testrun/file.go:44, internal/testrun/file.go:539, internal/testrun/file.go:560, internal/testrun/file.go:598."}, {"id": "g046", "kind": "multi", "question": "Our mobium.config.json takes the iOS simulator from ${MOBIUM_IOS_DEVICE}. If a CI job runs mobium test without that variable set, what happens and what exit status does the job get?", "tags": ["behavior", "ci-engineer"], "gold": [{"id": "docs/guides/test-runner.md#6-more-than-one-device", "heading": "6. More than one device", "path": "docs/guides/test-runner.md", "excerpt": "Add a project per device. An iOS simulator's id is one Mac's, and a phone's is somebody's, so a project can take its device from the environment, and an unset variable is refused by name before any test runs: ```json { \"testDir\": \"tests\", \"projects\": [ {\"name\": \"android\", \"device\": \"emulator-5554\"}, {\"name\": \"ios\", \"device\": \"${MOBIUM_IOS_DEVICE}\", \"driver\": \"wda\"} ] } ``` ```sh MOBIUM_IOS_DEVICE=<simulator-udid> mob…"}, {"id": "docs/guides/test-runner.md#7-in-ci", "heading": "7. In CI", "path": "docs/guides/test-runner.md", "excerpt": "The command a CI job runs, and what it publishes: ```sh mobium test --reporter list,junit,html # junit: mobium-report/junit.xml — for the CI's test report # html: mobium-report/ — as a build artifact ``` The exit status is 0 when every test passed or was flaky, 1 when any failed, and one of mobium's own codes when the run could not start — 2 for a bad file or an unset device, 3 for no device — so a job can tell \"the …"}], "retrieved": [{"id": "tests/README.md#tests", "heading": "Tests", "path": "tests/README.md", "excerpt": "Mobium's own tests of MobiumApp, run by `mobium test` — and the suite that holds the runner to its word. The format is in the [test runner guide](../docs/guides/test-runner.md). ```sh cd tests mobium test --project android # emulator-5554 MOBIUM_IOS_DEVICE=<simulator-udid> mobium test # and an iOS simulator mobium test --reporter list,junit,html && mobium show-report mobium test --ui --open # pick, run and watch on a…", "gold": false}, {"id": "CHALLENGES#162", "heading": "162. An unset device refused every project, not just its own", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** running `docs/checks/test-runner.sh` in the Android-only mode its own header documents — not a device's doing. A project can take its device from the environment, `\"${MOBIUM_IOS_DEVICE}\"`, and an unset variable is refused by name. It was refused when the config was read, so `mobium test --project android` failed over the iOS project's variable, which that run never needed; every earlier run had happened…", "gold": false}, {"id": "docs/guides/test-runner.md#1-a-config-and-a-test-file", "heading": "1. A config and a test file", "path": "docs/guides/test-runner.md", "excerpt": "``` login-tests/ mobium.config.json tests/ login.test.json ``` `mobium.config.json` says where the tests are and which devices they run on. A **project** is a device to run on: ```json { \"testDir\": \"tests\", \"projects\": [ {\"name\": \"android\", \"device\": \"emulator-5554\"} ] } ``` `tests/login.test.json` is two tests of MobiumApp's Login Demo. Each step is exactly what [`app_batch`](../API.md) takes — a tool and its argume…", "gold": false}, {"id": "docs/checks/README.md#device-checks", "heading": "Device checks", "path": "docs/checks/README.md", "excerpt": "Scripts that drive a real flow end to end through mobium's CLI and assert on the result. Not part of `make ci` — they need a device — but they are the thing [RELEASE-CHECKLIST.md](../RELEASE-CHECKLIST.md) asks you to run, written down so nobody has to invent them again. ```sh ./docs/checks/calculator.sh emulator-5554 ./docs/checks/calculator.sh <serial> ``` Getting a device attached in the first place is [../SETUP.md…", "gold": false}, {"id": "docs/guides/test-runner.md#the-commands", "heading": "The commands", "path": "docs/guides/test-runner.md", "excerpt": "| Command | What it does | | --- | --- | | `mobium test` | runs every `*.test.json` under the config's `testDir`, on every project | | `mobium test tests/login.test.json` | runs one file, or every file under a directory | | `mobium test -g login` | runs the tests whose title — \"file › name\" — matches a regular expression | | `mobium test --last-failed` | runs only the tests that failed last time | | `mobium test --pr…", "gold": false}], "missed": true, "facts": ["An unset variable in a project's device is refused by name before any test runs. ⟦refused by name⟧", "The run exits with mobium's own code 2 (a bad file or an unset device), not 1, which means a test failed, so a job can tell a broken run from a broken app. ⟦2 for a bad file or an unset device⟧"], "concern": "", "check": "Claude's reading: run.go refuses a project with unset variables as invalid_argument naming the variable, and ExitCode maps invalid_argument to 2; section 6 has the refusal and section 7 the exit code, so both are needed. Verified in: internal/testrun/file.go:410, internal/testrun/run.go:242, internal/mobiumerr/mobiumerr.go:239, cmd/mobium/test.go:228."}, {"id": "g047", "kind": "multi", "question": "How do I get mobium test results into my CI system's test report, and how does a test that only passed on a retry show up there?", "tags": ["how-to", "ci-engineer"], "gold": [{"id": "docs/guides/test-runner.md#7-in-ci", "heading": "7. In CI", "path": "docs/guides/test-runner.md", "excerpt": "The command a CI job runs, and what it publishes: ```sh mobium test --reporter list,junit,html # junit: mobium-report/junit.xml — for the CI's test report # html: mobium-report/ — as a build artifact ``` The exit status is 0 when every test passed or was flaky, 1 when any failed, and one of mobium's own codes when the run could not start — 2 for a bad file or an unset device, 3 for no device — so a job can tell \"the …"}, {"id": "docs/guides/test-runner.md#5-retries-and-flaky", "heading": "5. Retries, and flaky", "path": "docs/guides/test-runner.md", "excerpt": "`--retries N` runs a failed test again, from a fresh app, up to N times. A test that fails and then passes is **flaky**: the run passes, and it says so. This is the runner's own control for it, from `tests/controls/` in this repository — it saves a counter, and passes only once the counter reaches 2, which the retry's relaunch makes it do. It counts from cleared app data, so clear it first — a counter left at 2 by an…"}], "retrieved": [{"id": "docs/guides/test-runner.md#quick-start-mobium-test", "heading": "Quick start: `mobium test`", "path": "docs/guides/test-runner.md", "excerpt": "From an empty directory to a test suite that runs on a device, fails with evidence, retries, and leaves a report CI can publish. Every command and every line of output below is what `mobium test` printed on 2026-09-28 — section 8 on 2026-09-29 — against [MobiumApp](https://github.com/mobiumdev/mobium-app) on an Android 15 emulator. Where a path to a report is shortened, it says so. Before this guide: [the quick start…", "gold": false}, {"id": "docs/guides/test-runner.md#7-in-ci", "heading": "7. In CI", "path": "docs/guides/test-runner.md", "excerpt": "The command a CI job runs, and what it publishes: ```sh mobium test --reporter list,junit,html # junit: mobium-report/junit.xml — for the CI's test report # html: mobium-report/ — as a build artifact ``` The exit status is 0 when every test passed or was flaky, 1 when any failed, and one of mobium's own codes when the run could not start — 2 for a bad file or an unset device, 3 for no device — so a job can tell \"the …", "gold": true}, {"id": "docs/guides/inspector.md#4-record-a-test", "heading": "4. Record a test", "path": "docs/guides/inspector.md", "excerpt": "A test starts from a freshly launched app, so a recording should too: **Start from a fresh app** stops the app in front and launches it again, as `mobium test` does before each test, and starts recording. From there, every action is a step. Recorded on the Login Demo: ```json { \"app\": \"dev.mobium.mobiumapp\", \"description\": \"Recorded with mobium inspect.\", \"tests\": [ { \"name\": \"recorded\", \"steps\": [ {\"tap\": \"text=Logi…", "gold": false}, {"id": "docs/guides/grid.md#4-tests-on-a-grid", "heading": "4. Tests on a grid", "path": "docs/guides/grid.md", "excerpt": "`mobium test` goes through a grid the same way. A project that names no device asks for one by `platform`, and with `MOBIUM_GRID` set each project gets a connection of its own, which leases a device before any test runs and releases it when the run ends: ```json { \"testDir\": \"tests\", \"projects\": [ {\"name\": \"android-a\", \"platform\": \"android\"}, {\"name\": \"android-b\", \"platform\": \"android\"} ] } ``` ``` $ MOBIUM_GRID=loca…", "gold": false}, {"id": "docs/guides/test-runner.md#5-retries-and-flaky", "heading": "5. Retries, and flaky", "path": "docs/guides/test-runner.md", "excerpt": "`--retries N` runs a failed test again, from a fresh app, up to N times. A test that fails and then passes is **flaky**: the run passes, and it says so. This is the runner's own control for it, from `tests/controls/` in this repository — it saves a counter, and passes only once the counter reaches 2, which the retry's relaunch makes it do. It counts from cleared app data, so clear it first — a counter left at 2 by an…", "gold": true}], "missed": false, "facts": ["Run mobium test --reporter list,junit,html; the JUnit file is mobium-report/junit.xml, for the CI's test report. ⟦mobium-report/junit.xml⟧", "With --retries, a test that fails then passes is flaky; in JUnit it is a pass with a flaky property. ⟦pass with a flaky property⟧", "The exit status is 0 when every test passed or was flaky. ⟦0 when every test passed or was flaky⟧"], "concern": "", "check": "Claude's reading: WriteJUnit writes junit.xml with a `flaky` property \"passed on attempt N\" and the command fails only when a test failed; section 7 has the command and path, section 5 the flaky-in-JUnit rule. Verified in: internal/testrun/report.go:137, internal/testrun/report.go:169, cmd/mobium/test.go:228."}, {"id": "g048", "kind": "fact", "question": "I only want step-by-step screenshots and a replayable recording for the tests that fail in my nightly mobium test run. What do I pass, and where does the recording end up?", "tags": ["how-to", "test-author"], "gold": [{"id": "docs/guides/test-runner.md#a-trace", "heading": "A trace", "path": "docs/guides/test-runner.md", "excerpt": "`--trace on` keeps a screenshot and the map after every step, and the HTML report shows them as a filmstrip; `--trace retain-on-failure` keeps them only for a test that failed. `trace` in the config sets the default. Each attempt is also kept as a recording in Vibium's record format, at `mobium-report/artifacts/trace/<project>-<file>-<test>-<attempt>/trace.zip`, which the report links and [player.vibium.dev](https://…"}], "retrieved": [{"id": "docs/guides/test-runner.md#a-trace", "heading": "A trace", "path": "docs/guides/test-runner.md", "excerpt": "`--trace on` keeps a screenshot and the map after every step, and the HTML report shows them as a filmstrip; `--trace retain-on-failure` keeps them only for a test that failed. `trace` in the config sets the default. Each attempt is also kept as a recording in Vibium's record format, at `mobium-report/artifacts/trace/<project>-<file>-<test>-<attempt>/trace.zip`, which the report links and [player.vibium.dev](https://…", "gold": true}, {"id": "CHALLENGES#274", "heading": "274. A capture saved into a folder not yet made was lost", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** the audio demo's repository, whose test file saved its capture to `mobium-report/sequence.wav` before anything had made that folder. Mobium's own `tests/audio/` had passed only because its `mobium-report/` was already there. The step failed with \"no such file or directory\" — after the capture had stopped, so the capture went with it, and a test meant to pass reported two failures that were not the app's…", "gold": false}, {"id": "CHALLENGES#212", "heading": "212. A trace went with its session, and a passing test kept none", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** recording a test on a Fire TV over Wi-Fi to play it in Vibium's player. The test passed with `--trace on` and its report had a screenshot for every step and no trace. The link had dropped and come back mid-run, so the next call found the session unhealthy and replaced it — and the running trace was a field of the session, closed with it. The runner's `app_trace stop` then found no trace, and the runner …", "gold": false}, {"id": "docs/guides/test-runner.md#the-commands", "heading": "The commands", "path": "docs/guides/test-runner.md", "excerpt": "| Command | What it does | | --- | --- | | `mobium test` | runs every `*.test.json` under the config's `testDir`, on every project | | `mobium test tests/login.test.json` | runs one file, or every file under a directory | | `mobium test -g login` | runs the tests whose title — \"file › name\" — matches a regular expression | | `mobium test --last-failed` | runs only the tests that failed last time | | `mobium test --pr…", "gold": false}, {"id": "docs/guides/test-runner.md#10-a-page-to-run-tests-from---ui", "heading": "10. A page to run tests from: `--ui`", "path": "docs/guides/test-runner.md", "excerpt": "```sh mobium test --ui --open ``` serves a page on this machine that lists the suite by file, with each test's result on each project. ▶ runs one test, a file, or everything; each step appears with the screen after it as it runs, and **Re-run failed** runs exactly what failed. The files are read again for every run, so a test you just saved is the test that runs. A run from the page is the run `mobium test` makes fro…", "gold": false}], "missed": false, "facts": ["--trace retain-on-failure keeps the screenshot and map after every step only for a test that failed (trace in the config sets the default). ⟦retain-on-failure⟧", "The recording is a zip in Vibium's record format at mobium-report/artifacts/trace/<project>-<file>-<test>-<attempt>/trace.zip, linked from the report. ⟦trace.zip⟧", "player.vibium.dev opens it. ⟦player.vibium.dev⟧"], "concern": "test-runner.md 'A trace' says \"Each attempt is also kept as a recording\", but run.go:477-487 keeps only the attempt reported (a flaky test's first failure, a failed test's last attempt, a pass) and pruneTraces deletes the other attempts' trace directories.", "check": "Claude's reading: the flag, the path and the player match the code. A reviewer should look at the concern: the doc says each attempt is kept, the code keeps one. Verified in: cmd/mobium/test.go:103, internal/testrun/run.go:477, internal/testrun/run.go:509, internal/testrun/run.go:513."}, {"id": "g049", "kind": "fact", "question": "If I attach the trace zip from a sign-in test to a bug report, will the username and password I typed be readable in it?", "tags": ["behavior", "test-author"], "gold": [{"id": "CHALLENGES#327", "heading": "327. A trace held an expect as a bare read, and said typed text was not in it", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** turning a `mobium test` trace back into a test, one step per traced call, and running both on MobiumApp builds with a deliberate bug each (the round-trip probe, mobiumdev/mobium-roundtrip), on the Android 15 emulator. The generated suite caught every bug the original did but lost one (bug, test) cell: \"the app is in front throughout\" is two `expect`s, and a trace kept each as the read it made — `app_sta…"}], "retrieved": [{"id": "CHALLENGES#327", "heading": "327. A trace held an expect as a bare read, and said typed text was not in it", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** turning a `mobium test` trace back into a test, one step per traced call, and running both on MobiumApp builds with a deliberate bug each (the round-trip probe, mobiumdev/mobium-roundtrip), on the Android 15 emulator. The generated suite caught every bug the original did but lost one (bug, test) cell: \"the app is in front throughout\" is two `expect`s, and a trace kept each as the read it made — `app_sta…", "gold": true}, {"id": "docs/guides/test-runner.md#a-trace", "heading": "A trace", "path": "docs/guides/test-runner.md", "excerpt": "`--trace on` keeps a screenshot and the map after every step, and the HTML report shows them as a filmstrip; `--trace retain-on-failure` keeps them only for a test that failed. `trace` in the config sets the default. Each attempt is also kept as a recording in Vibium's record format, at `mobium-report/artifacts/trace/<project>-<file>-<test>-<attempt>/trace.zip`, which the report links and [player.vibium.dev](https://…", "gold": false}, {"id": "docs/ROADMAP.md#under-consideration", "heading": "Under consideration", "path": "docs/ROADMAP.md", "excerpt": "- **Locators for when there is no ref** (written down 2026-10-12). A ref from `map` lasts one map, so an agent has one and a `mobium test` file does not: a hand-written test has the flat `kind=value` locators — text, label, testid, role, class, path, narrowed by `,role=` — which match one element or are refused. That is right on a form and leaves nothing durable on a list. Every Ice Cubes post has a \"…\" (CHALLENGES 2…", "gold": false}, {"id": "CHALLENGES#55", "heading": "55. Text entry failed on a field `map` had just handed out a ref for", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** the first React Native app this project has driven. Every prior Android app was Google's, Wikipedia's, F-Droid's or Aegis's, and every one of them reports a resource-id in the fully qualified form `com.example:id/name`. React Native reports a bare one. A `testID` of `password` arrives as `resource-id=\"password\"`, with no package. `map` handled it correctly — the node, the label, the `role=password` and …", "gold": false}, {"id": "CHALLENGES#43", "heading": "43. `map` printed a password in plaintext", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** the second and third real third-party apps. Typing into Aegis's master-password field and running `map` again gave: ``` @e2 Sup3rSecret! (input) ``` Android marks the node `password=\"true\"` **and** puts the typed value straight into its `text` attribute. Mobium parsed that flag into `Node.Password` and consulted it nowhere — the same shape as [defect 39](#39-a-visibility-field-that-nothing-consulted), f…", "gold": false}], "missed": false, "facts": ["A password is not recorded, only its length. ⟦only its length⟧", "Other typed text, such as the username, is in the trace: in the call's result and the screen after it. ⟦in the call's result⟧"], "concern": "", "check": "Claude's reading: only CHALLENGES 327 (its second part) states the corrected rule in the corpus; the CLI help and app_trace schema say the same, but neither is in the corpus. checks/README's trace.sh row adds that a typed password appears nowhere in the zip but does not cover other text. Verified in: cmd/mobium/trace.go:20, internal/agent/schema.go:882."}, {"id": "g050", "kind": "fact", "question": "My app polls a server in the background forever, and I launched it with --gray-box. What happens when I tap something?", "tags": ["behavior", "test-author"], "gold": [{"id": "docs/guides/graybox.md#what-an-action-does", "heading": "What an action does", "path": "docs/guides/graybox.md", "excerpt": "Before an action finds its target, it waits until the app has nothing in flight. The result says what it waited for (the iPhone): ``` $ mobium tap testid=busyQuiet tapped testid=busyQuiet at (645, 1011) gray box: waited 35 ms for the app to go idle $ mobium tap testid=busyRowB tapped testid=busyRowB at (645, 1218) gray box: waited 1018 ms for the app to go idle (busy: quiet) $ mobium text testid=busyOutcome row B, ge…"}], "retrieved": [{"id": "docs/guides/graybox.md#what-an-action-does", "heading": "What an action does", "path": "docs/guides/graybox.md", "excerpt": "Before an action finds its target, it waits until the app has nothing in flight. The result says what it waited for (the iPhone): ``` $ mobium tap testid=busyQuiet tapped testid=busyQuiet at (645, 1011) gray box: waited 35 ms for the app to go idle $ mobium tap testid=busyRowB tapped testid=busyRowB at (645, 1218) gray box: waited 1018 ms for the app to go idle (busy: quiet) $ mobium text testid=busyOutcome row B, ge…", "gold": true}, {"id": "CHALLENGES#251", "heading": "251. `launch --gray-box` of a running iOS app never reached it", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** walking the gray-box demo's quick start from scratch on the simulator, exactly as written. The quick start launches MobiumApp normally, opens the Busy Demo, and then launches it with `--gray-box` — without stopping it in between, as nobody would. The launch reported that the app had not answered the gray box, the app stayed on the Busy Demo, and the next tap landed stale. A launch argument reaches only …", "gold": false}, {"id": "docs/guides/graybox.md#gray-box-waiting-for-the-app-to-say-it-is-idle", "heading": "Gray box: waiting for the app to say it is idle", "path": "docs/guides/graybox.md", "excerpt": "Auto-wait judges a screen by what it shows: a target is there, has stopped moving, is enabled and is not covered. That cannot see work the screen does not show — a request in flight behind rows that look finished, which a tap then lands on just before they are replaced. Gray box asks the app instead. An app built with Mobium's gray-box library, and launched with `--gray-box`, says in the device log when it starts wor…", "gold": false}, {"id": "docs/guides/graybox.md#hooks-calling-into-the-app", "heading": "Hooks: calling into the app", "path": "docs/guides/graybox.md", "excerpt": "Waiting is the way out of the app. Hooks are the way in: functions the app registers by name, which a test calls to set up state without walking the UI — sign in, seed data, raise a toast. MobiumApp registers three; in outline: ```ts GrayBox.register('raiseToast', message => { showToast(message); return 'shown'; }); GrayBox.register('screen', () => screenRef.current); GrayBox.register('signIn', username => { setLogge…", "gold": false}, {"id": "docs/guides/graybox-tutorial.md#4-turning-the-gray-box-on", "heading": "4. Turning the gray box on", "path": "docs/guides/graybox-tutorial.md", "excerpt": "One key in the test file, beside `app`: ```json { \"app\": \"dev.mobium.mobiumapp\", \"grayBox\": true, \"beforeEach\": [ ``` Each test's launch now turns the library on, and every step waits for the app to say it is idle before finding its target: ``` $ mobium test ok [android · emulator-5554] busy.test.json › a row tapped after a quiet refresh is current (1) (7s) ok [android · emulator-5554] busy.test.json › a row tapped a…", "gold": false}], "missed": false, "facts": ["After 10 seconds the action is refused as a timeout that failed check idle, naming what the app said kept it busy. ⟦after 10 seconds ; failed check idle⟧", "The remedy is to launch the app again without the gray box, to act on the screen as it is. ⟦without --gray-box / without gray_box⟧"], "concern": "", "check": "Claude's reading: grayBoxIdleLimit is 10 s in agent/graybox.go, and the refusal text in the guide's example ends \"launch the app again without gray_box\". Verified in: internal/agent/graybox.go:28."}, {"id": "g051", "kind": "fact", "question": "My mobium test suite runs on a Fire TV over Wi-Fi whose adb link keeps dropping for a few seconds. What does the runner do with a step when the link goes?", "tags": ["behavior", "test-author"], "gold": [{"id": "docs/guides/test-runner.md#a-device-that-drops-off-and-comes-back", "heading": "A device that drops off and comes back", "path": "docs/guides/test-runner.md", "excerpt": "A retry starts the test over. A device whose link drops for a few seconds — a TV or a phone over Wi-Fi — is waited out within the test instead: a step whose call **never reached the device** is made again once it is back, for up to 90 seconds and never past the test's own time. A device reached by `adb connect` is connected again for you. Only that failure is waited out, and an error says which it was (`details.reach…"}], "retrieved": [{"id": "CHALLENGES#210", "heading": "210. A dropped link was reported as a failed install, with advice that could not work", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** running scenarios on a Fire TV over Wi-Fi, whose link drops every few minutes. A `map` called while it was down answered \"installing UiAutomator2 server\", then failed with `install server.apk: … adb: device offline` and advised `--driver uiautomator` — on a TV that had the pinned server installed, version 10.6.6, the whole time. Asking whether the server is installed treated a failed `dumpsys` or `pm li…", "gold": false}, {"id": "docs/SETUP.md#over-wi-fi", "heading": "Over Wi-Fi", "path": "docs/SETUP.md", "excerpt": "Android 11+. The phone and the Mac must be on the same network. 1. **Developer options → Wireless debugging → on.** 2. **\"Pair device with pairing code\"** — it shows an address and a six-digit code. Both expire in about a minute. 3. Find the address without reading it off the screen: ```sh adb mdns services # adb-XXXXXXXX-abcdef _adb-tls-pairing._tcp 192.0.2.20:33169 # adb-XXXXXXXX-abcdef _adb-tls-connect._tcp 192.0.2.20…", "gold": false}, {"id": "docs/ROADMAP.md#under-consideration", "heading": "Under consideration", "path": "docs/ROADMAP.md", "excerpt": "- **Locators for when there is no ref** (written down 2026-10-12). A ref from `map` lasts one map, so an agent has one and a `mobium test` file does not: a hand-written test has the flat `kind=value` locators — text, label, testid, role, class, path, narrowed by `,role=` — which match one element or are refused. That is right on a form and leaves nothing durable on a list. Every Ice Cubes post has a \"…\" (CHALLENGES 2…", "gold": false}, {"id": "docs/guides/test-runner.md#a-device-that-drops-off-and-comes-back", "heading": "A device that drops off and comes back", "path": "docs/guides/test-runner.md", "excerpt": "A retry starts the test over. A device whose link drops for a few seconds — a TV or a phone over Wi-Fi — is waited out within the test instead: a step whose call **never reached the device** is made again once it is back, for up to 90 seconds and never past the test's own time. A device reached by `adb connect` is connected again for you. Only that failure is waited out, and an error says which it was (`details.reach…", "gold": true}, {"id": "docs/SHUTDOWN.md#a-tv-or-anything-reached-by-adb-connect", "heading": "A TV, or anything reached by `adb connect`", "path": "docs/SHUTDOWN.md", "excerpt": "A Fire TV is reached over Wi-Fi with `adb connect <tv>:5555`, after ADB debugging is turned on in its Developer Options. It is somebody's living-room TV, so the device checks above run on it as on a phone, and four more run on every device: - **A screen mirror's server.** scrcpy was how the TV was watched while it was measured, and its server streams the screen off the device for as long as it runs. On the device it …", "gold": false}], "missed": false, "facts": ["A step whose call never reached the device is made again once the device is back, for up to 90 seconds and never past the test's own time; a device reached by adb connect is connected again. ⟦90 seconds ; connected again⟧", "A failure from a call that may have reached the device fails the step as before, because making it again could press twice. ⟦press twice⟧"], "concern": "", "check": "Claude's reading: callReaching retries only device.Unreached errors, every 2 s, until linkWait (90 s) or the test's deadline, as the section says. Verified in: internal/testrun/run.go:800, internal/testrun/run.go:807."}, {"id": "g052", "kind": "fact", "question": "I changed some Go code in Mobium and ran make build, but the CLI still behaves exactly as before my change. What am I missing?", "tags": ["troubleshooting", "contributor"], "gold": [{"id": "docs/DEVELOPMENT.md#3-run-what-ci-runs", "heading": "3. Run what CI runs", "path": "docs/DEVELOPMENT.md", "excerpt": "```sh make ci ``` It is exactly what the CI workflow runs, so a green local run means a green build. Among its other lines it prints `gofmt clean`, `clients parse`, a line per JavaScript and Python client check, a `checks, 0 failed` total for each of the Java and .NET suites, `license copies match` and `docs: spelling, anchors and quick-start pages clean`; the counts in them grow with the API, so none is quoted here.…"}], "retrieved": [{"id": "CLAUDE.md#rules", "heading": "Rules", "path": "CLAUDE.md", "excerpt": "- Run `make ci` before committing. After adding a tool, a flag or a schema property, run `make api flags` and add it everywhere — CLI, MCP schema, all five clients (CONTRIBUTING.md, \"Adding a tool, a flag or an error\") - Every error has a code: `mobiumerr.New(mobiumerr.<Code>, ...)`, never a bare `fmt.Errorf` - The CLI implements no behavior; it calls a tool. Behavior lives in `internal/agent` - After rebuilding, `mo…", "gold": false}, {"id": "docs/API.md#the-api-surface", "heading": "The API surface", "path": "docs/API.md", "excerpt": "**Generated — do not edit.** Run `make api` to rebuild this and [api/surface.json](api/surface.json) from the source. Mobium's architecture rests on one claim: every front door reaches the same tool layer, so a CLI command and an MCP tool cannot answer differently. This is that claim, enumerated, and a drift check keeps it true — `internal/apisurface` fails the build if any tool stops being reachable from any surface…", "gold": false}, {"id": "CONTRIBUTING.md#adding-a-tool-a-flag-or-an-error", "heading": "Adding a tool, a flag or an error", "path": "CONTRIBUTING.md", "excerpt": "- **A tool** goes everywhere at once: the CLI, the MCP schema and all five clients. `internal/apisurface` fails the build otherwise; a deliberate gap is declared there with a reason. Run `make api` to regenerate [docs/API.md](docs/API.md). - **A flag or schema property** is the same rule one level down: every argument a tool declares must be settable from the CLI, and every key a command sends must be one the tool de…", "gold": false}, {"id": "CONTRIBUTING.md#building-and-testing", "heading": "Building and testing", "path": "CONTRIBUTING.md", "excerpt": "[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) is the step-by-step version: the toolchains, a fresh clone to a passing `make ci`, driving a device, working on a client, and sending a pull request. In short: ```sh make build # -> bin/mobium make ci # what CI runs: gofmt, vet, lint, tests, client checks, # cross-compilation, and the generated-doc and spelling checks ``` Run `make ci` before sending a change; a green local …", "gold": false}, {"id": "docs/WINDOWS.md#project-rules-that-apply", "heading": "Project rules that apply", "path": "docs/WINDOWS.md", "excerpt": "From [CONTRIBUTING.md](../CONTRIBUTING.md): - **Verify by outcome, never exit code.** Especially here: a named pipe that accepts a connection and never answers looks identical to success. - Run `make ci` before committing, and `mobium daemon stop` after rebuilding, or you will debug a binary you are not running. - Never name a Go file `*_windows.go` unless you intend the build constraint — though here, you do.", "gold": false}], "missed": true, "facts": ["A daemon already running keeps serving the old binary; run bin/mobium daemon stop after rebuilding. ⟦bin/mobium daemon stop ; keeps serving the old binary⟧"], "concern": "", "check": "Claude's reading: the CLI sends every call to the running daemon and starts a new one only on a connection error, so a stale daemon is never replaced by itself. CONTRIBUTING.md#building-and-testing says the same; either section alone answers, and DEVELOPMENT is the step-by-step one. Verified in: cmd/mobium/daemon_client.go:50, cmd/mobium/daemon_client.go:56, cmd/mobium/daemon_client.go:66."}, {"id": "g053", "kind": "fact", "question": "I ran make api after adding a tool, but make ci still fails saying docs/API.md is not current. Why?", "tags": ["troubleshooting", "contributor"], "gold": [{"id": "docs/DEVELOPMENT.md#6-regenerate-what-is-generated", "heading": "6. Regenerate what is generated", "path": "docs/DEVELOPMENT.md", "excerpt": "Some documents are built from the code, and `make ci` fails when one is stale: | When you change | Run | It writes | | --- | --- | --- | | a tool, or which surfaces reach it | `make api` | [API.md](API.md) | | a tool's arguments or a command's flags | `make flags` | [FLAGS.md](FLAGS.md) | | a quick-start example or its captured output | `make quickstart` | the [quick start](quickstart/README.md) pages | | the root `L…"}], "retrieved": [{"id": "CLAUDE.md#rules", "heading": "Rules", "path": "CLAUDE.md", "excerpt": "- Run `make ci` before committing. After adding a tool, a flag or a schema property, run `make api flags` and add it everywhere — CLI, MCP schema, all five clients (CONTRIBUTING.md, \"Adding a tool, a flag or an error\") - Every error has a code: `mobiumerr.New(mobiumerr.<Code>, ...)`, never a bare `fmt.Errorf` - The CLI implements no behavior; it calls a tool. Behavior lives in `internal/agent` - After rebuilding, `mo…", "gold": false}, {"id": "CONTRIBUTING.md#adding-a-tool-a-flag-or-an-error", "heading": "Adding a tool, a flag or an error", "path": "CONTRIBUTING.md", "excerpt": "- **A tool** goes everywhere at once: the CLI, the MCP schema and all five clients. `internal/apisurface` fails the build otherwise; a deliberate gap is declared there with a reason. Run `make api` to regenerate [docs/API.md](docs/API.md). - **A flag or schema property** is the same rule one level down: every argument a tool declares must be settable from the CLI, and every key a command sends must be one the tool de…", "gold": false}, {"id": "docs/API.md#the-api-surface", "heading": "The API surface", "path": "docs/API.md", "excerpt": "**Generated — do not edit.** Run `make api` to rebuild this and [api/surface.json](api/surface.json) from the source. Mobium's architecture rests on one claim: every front door reaches the same tool layer, so a CLI command and an MCP tool cannot answer differently. This is that claim, enumerated, and a drift check keeps it true — `internal/apisurface` fails the build if any tool stops being reachable from any surface…", "gold": false}, {"id": "docs/DEVELOPMENT.md#6-regenerate-what-is-generated", "heading": "6. Regenerate what is generated", "path": "docs/DEVELOPMENT.md", "excerpt": "Some documents are built from the code, and `make ci` fails when one is stale: | When you change | Run | It writes | | --- | --- | --- | | a tool, or which surfaces reach it | `make api` | [API.md](API.md) | | a tool's arguments or a command's flags | `make flags` | [FLAGS.md](FLAGS.md) | | a quick-start example or its captured output | `make quickstart` | the [quick start](quickstart/README.md) pages | | the root `L…", "gold": true}, {"id": "docs/DEVELOPMENT.md#3-run-what-ci-runs", "heading": "3. Run what CI runs", "path": "docs/DEVELOPMENT.md", "excerpt": "```sh make ci ``` It is exactly what the CI workflow runs, so a green local run means a green build. Among its other lines it prints `gofmt clean`, `clients parse`, a line per JavaScript and Python client check, a `checks, 0 failed` total for each of the Java and .NET suites, `license copies match` and `docs: spelling, anchors and quick-start pages clean`; the counts in them grow with the API, so none is quoted here.…", "gold": false}], "missed": false, "facts": ["The generated-doc checks compare against the git index, so git add the regenerated files before running make ci. ⟦git index ; git add⟧"], "concern": "", "check": "Claude's reading: api-check and flags-check run `git diff --quiet -- docs/API.md docs/api/surface.json` (and FLAGS), which compares the working tree with the index, so unstaged regenerated files fail; the docs check uses git ls-files too. Verified in: Makefile:159, Makefile:191, Makefile:240."}, {"id": "g054", "kind": "fact", "question": "I started a second Mobium device check script on an emulator where another check was already running, and it stopped at once with a FAIL saying the device is in use. How do I run several checks at once?", "tags": ["troubleshooting", "contributor"], "gold": [{"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…"}], "retrieved": [{"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": true}, {"id": "CHALLENGES#276", "heading": "276. A check passed for a device it never touched", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** sweeping `audio.sh` on both emulators at once. Its last step runs `mobium test --project android`, and `tests/mobium.config.json` names that project's device `emulator-5554`. So `audio.sh emulator-5556` ran its test step on 5554: Android 17's pass never tested that step on Android 17, and the two checks' test steps started UiAutomator2 servers on 5554 within a third of a second — each start stops the se…", "gold": false}, {"id": "CHALLENGES#199", "heading": "199. An interrupted test run left its daemons running", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** `docs/checks/test-ui.sh`, which failed on its first draft partway through a run on an emulator and a simulator; its cleanup killed `mobium test --ui`, and two daemons, `mobium-<run>-1` and `-2`, were still running afterwards with their sockets left. A run gives each project a `mobium pipe` and a daemon of its own and stops them when it ends — in a deferred cleanup, which a killed process never reaches. …", "gold": false}, {"id": "docs/DEVELOPMENT.md#4-drive-a-device", "heading": "4. Drive a device", "path": "docs/DEVELOPMENT.md", "excerpt": "The Go suite is hermetic — fake servers and captured fixtures, no device. Behavior on a device is checked by the scripts in [checks/](checks/), each of which drives a real emulator, simulator or phone and asserts on what happened rather than on an exit code. Start one device — `mobium boot mobium-test` for an emulator, `mobium boot \"iPhone 17 Pro\"` for a simulator; [SETUP.md](SETUP.md) has every kind, and the traps —…", "gold": false}], "missed": false, "facts": ["Checks run one per device: check_lock takes the device, a second check on it is refused naming the first, and a lock whose holder has gone is taken over. ⟦check_lock⟧", "Checks on different devices can run side by side, each with a daemon of its own (MOBIUM_SESSION) stopped when it ends. ⟦of its own (MOBIUM_SESSION)⟧"], "concern": "", "check": "Claude's reading: lib.sh's check_lock prints \"is in use by another check ... run one check per device at a time\" and exits 2 when the holder's pid is alive, and takes over a dead holder's lock. The gold section is very long (the whole checks table); the answer is in its first part. Verified in: docs/checks/lib.sh:33, docs/checks/lib.sh:125, docs/checks/lib.sh:136."}, {"id": "g055", "kind": "multi", "question": "Can Mobium's gray box wait for my app's background work on a real iPhone, and can I use it with an app installed from the App Store?", "tags": ["support", "new-user"], "gold": [{"id": "docs/guides/graybox.md#gray-box-waiting-for-the-app-to-say-it-is-idle", "heading": "Gray box: waiting for the app to say it is idle", "path": "docs/guides/graybox.md", "excerpt": "Auto-wait judges a screen by what it shows: a target is there, has stopped moving, is enabled and is not covered. That cannot see work the screen does not show — a request in flight behind rows that look finished, which a tap then lands on just before they are replaced. Gray box asks the app instead. An app built with Mobium's gray-box library, and launched with `--gray-box`, says in the device log when it starts wor…"}, {"id": "docs/guides/graybox.md#what-it-does-not-do", "heading": "What it does not do", "path": "docs/guides/graybox.md", "excerpt": "- **Detect work.** The app says when it is busy. Work it does not declare is not waited for, and an app that says it is idle too early is believed. - **An app without the library** — anything from an app store — which stays driven the ordinary way. - **`--hit-test` together with it**, for now: launch with one of them. - **Switching apps.** The gray box belongs to the app last launched with it. An ordinary launch of a…"}], "retrieved": [{"id": "docs/guides/graybox.md#gray-box-waiting-for-the-app-to-say-it-is-idle", "heading": "Gray box: waiting for the app to say it is idle", "path": "docs/guides/graybox.md", "excerpt": "Auto-wait judges a screen by what it shows: a target is there, has stopped moving, is enabled and is not covered. That cannot see work the screen does not show — a request in flight behind rows that look finished, which a tap then lands on just before they are replaced. Gray box asks the app instead. An app built with Mobium's gray-box library, and launched with `--gray-box`, says in the device log when it starts wor…", "gold": true}, {"id": "docs/guides/graybox.md#hooks-calling-into-the-app", "heading": "Hooks: calling into the app", "path": "docs/guides/graybox.md", "excerpt": "Waiting is the way out of the app. Hooks are the way in: functions the app registers by name, which a test calls to set up state without walking the UI — sign in, seed data, raise a toast. MobiumApp registers three; in outline: ```ts GrayBox.register('raiseToast', message => { showToast(message); return 'shown'; }); GrayBox.register('screen', () => screenRef.current); GrayBox.register('signIn', username => { setLogge…", "gold": false}, {"id": "docs/guides/graybox-tutorial.md#5-your-own-app", "heading": "5. Your own app", "path": "docs/guides/graybox-tutorial.md", "excerpt": "The library is small, and what it writes is the whole contract. In a React Native app, copy MobiumApp's `modules/graybox` (Swift and Kotlin, about 160 lines between them) and call `busy` and `idle` around the work a test should wait for. In a native app, write the same lines yourself, only when launched with the gray box on — on iOS the argument `-MobiumGrayBox YES`, on Android the intent extra `MobiumGrayBox=true`: …", "gold": false}, {"id": "docs/guides/graybox.md#turning-it-on", "heading": "Turning it on", "path": "docs/guides/graybox.md", "excerpt": "``` $ mobium launch --gray-box dev.mobium.mobiumapp launched dev.mobium.mobiumapp, with the gray box: every action waits for the app to say it is idle ``` On iOS, `--gray-box` launches the app with the argument `-MobiumGrayBox YES`, which iOS keeps for that launch only. On Android it starts the app afresh — stopped first, so its activity reads what it was started with — with the intent extra `MobiumGrayBox=true`, whi…", "gold": false}, {"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": false}], "missed": false, "facts": ["Gray box works on iOS and Android, on simulators, emulators and phones, for an app built with Mobium's gray-box library and launched with --gray-box. ⟦simulators, emulators and phones⟧", "An app without the library, such as anything from an app store, is not waited for and stays driven the ordinary way. ⟦anything from an app store⟧"], "concern": "", "check": "Claude's reading: the intro states where it runs and that the app must link the library; 'What it does not do' states the app-store case. In code an app that never answers is launched normally with \"actions are not waited for\". Verified in: internal/agent/graybox.go:128, internal/device/graybox.go:74, internal/device/grayboxstream.go:77."}, {"id": "g056", "kind": "fact", "question": "Why doesn't Mobium's own CI run its tests on a hosted Android emulator or iOS simulator?", "tags": ["rationale", "contributor"], "gold": [{"id": "docs/RELEASE-CHECKLIST.md#why-there-is-no-device-job-in-ci", "heading": "Why there is no device job in CI", "path": "docs/RELEASE-CHECKLIST.md", "excerpt": "A hosted Android emulator job is possible and a hosted iOS simulator job is easy. Neither is here, for one reason: **a device test that runs unattended tells you it failed, not what the screen looked like.** Every defect in [CHALLENGES.md](CHALLENGES.md) was diagnosed by reading a hierarchy or comparing a computed point against a screenshot, which is a human activity. That is a judgment, not a law. Revisit it when th…"}], "retrieved": [{"id": "docs/RELEASE-CHECKLIST.md#why-there-is-no-device-job-in-ci", "heading": "Why there is no device job in CI", "path": "docs/RELEASE-CHECKLIST.md", "excerpt": "A hosted Android emulator job is possible and a hosted iOS simulator job is easy. Neither is here, for one reason: **a device test that runs unattended tells you it failed, not what the screen looked like.** Every defect in [CHALLENGES.md](CHALLENGES.md) was diagnosed by reading a hierarchy or comparing a computed point against a screenshot, which is a human activity. That is a judgment, not a law. Revisit it when th…", "gold": true}, {"id": "tests/README.md#tests", "heading": "Tests", "path": "tests/README.md", "excerpt": "Mobium's own tests of MobiumApp, run by `mobium test` — and the suite that holds the runner to its word. The format is in the [test runner guide](../docs/guides/test-runner.md). ```sh cd tests mobium test --project android # emulator-5554 MOBIUM_IOS_DEVICE=<simulator-udid> mobium test # and an iOS simulator mobium test --reporter list,junit,html && mobium show-report mobium test --ui --open # pick, run and watch on a…", "gold": false}, {"id": "docs/ROADMAP.md#under-consideration", "heading": "Under consideration", "path": "docs/ROADMAP.md", "excerpt": "- **Locators for when there is no ref** (written down 2026-10-12). A ref from `map` lasts one map, so an agent has one and a `mobium test` file does not: a hand-written test has the flat `kind=value` locators — text, label, testid, role, class, path, narrowed by `,role=` — which match one element or are refused. That is right on a form and leaves nothing durable on a list. Every Ice Cubes post has a \"…\" (CHALLENGES 2…", "gold": false}, {"id": "docs/FORMFLUX.md#running-it", "heading": "Running it", "path": "docs/FORMFLUX.md", "excerpt": "The parsing is covered by fixtures captured from the device. The behavior is not, and cannot be — so there is a device-backed test, opt-in like the network one: ```sh MOBIUM_DEVICE_TESTS=1 MOBIUM_DEVICE=emulator-5554 \\ go test ./internal/formflux/ -run Device -v ``` `TestDeviceCatchesThePlantedTargets` needs MobiumApp installed, and skips without it. The iOS test has its own switch, because it may create and delete s…", "gold": false}, {"id": "docs/guides/network.md#why-not-the-emulators-own-throttling", "heading": "Why not the emulator's own throttling", "path": "docs/guides/network.md", "excerpt": "The Android emulator's console has `network speed` and `network delay`, and they look made for this. They accept a setting and read it back — and change nothing: on emulator 37.1.11, 2MB at a 1000 kbit/s limit still arrived in 1.1 seconds where 16 were due, and a 500ms delay left a ping at 1ms. So Mobium does not use them; it shapes the traffic itself, and every figure above was measured from the traffic, not the set…", "gold": false}], "missed": false, "facts": ["A device test that runs unattended tells you it failed, not what the screen looked like; every defect was diagnosed by a person reading a hierarchy or a screenshot. ⟦not what the screen looked like⟧", "Here the harness is the thing under test and its defects are mostly misreadings of a device that a green unattended run would pass, so what an assertion can decide is in make ci and what needs a person is in the release checklist. ⟦harness is the thing under test⟧"], "concern": "", "check": "Claude's reading: a rationale section with nothing to check in code beyond the ci target having no device job (Makefile:240). The section quotes the author's own article; that is a public link, not private data. Verified in: Makefile:240."}, {"id": "g057", "kind": "fact", "question": "Walking through the login screen at the start of every test is slow. How can a test put my app straight into a signed-in state instead?", "tags": ["how-to", "test-author"], "gold": [{"id": "docs/guides/graybox.md#hooks-calling-into-the-app", "heading": "Hooks: calling into the app", "path": "docs/guides/graybox.md", "excerpt": "Waiting is the way out of the app. Hooks are the way in: functions the app registers by name, which a test calls to set up state without walking the UI — sign in, seed data, raise a toast. MobiumApp registers three; in outline: ```ts GrayBox.register('raiseToast', message => { showToast(message); return 'shown'; }); GrayBox.register('screen', () => screenRef.current); GrayBox.register('signIn', username => { setLogge…"}], "retrieved": [{"id": "docs/guides/inspector.md#4-record-a-test", "heading": "4. Record a test", "path": "docs/guides/inspector.md", "excerpt": "A test starts from a freshly launched app, so a recording should too: **Start from a fresh app** stops the app in front and launches it again, as `mobium test` does before each test, and starts recording. From there, every action is a step. Recorded on the Login Demo: ```json { \"app\": \"dev.mobium.mobiumapp\", \"description\": \"Recorded with mobium inspect.\", \"tests\": [ { \"name\": \"recorded\", \"steps\": [ {\"tap\": \"text=Logi…", "gold": false}, {"id": "docs/guides/graybox.md#hooks-calling-into-the-app", "heading": "Hooks: calling into the app", "path": "docs/guides/graybox.md", "excerpt": "Waiting is the way out of the app. Hooks are the way in: functions the app registers by name, which a test calls to set up state without walking the UI — sign in, seed data, raise a toast. MobiumApp registers three; in outline: ```ts GrayBox.register('raiseToast', message => { showToast(message); return 'shown'; }); GrayBox.register('screen', () => screenRef.current); GrayBox.register('signIn', username => { setLogge…", "gold": true}, {"id": "docs/guides/network.md#4-in-a-test", "heading": "4. In a test", "path": "docs/guides/network.md", "excerpt": "`app_network` is a step like any other in a [`mobium test`](test-runner.md) file, and its answer can be expected on: ```json { \"app\": \"dev.mobium.mobiumapp\", \"beforeEach\": [ {\"name\": \"app_network\", \"arguments\": {\"reset\": true}, \"description\": \"every test starts online and unshaped, whatever the last one left\"} ], \"tests\": [ { \"name\": \"the device goes offline, and comes back\", \"steps\": [ {\"name\": \"app_network\", \"argum…", "gold": false}, {"id": "docs/guides/test-runner.md#1-a-config-and-a-test-file", "heading": "1. A config and a test file", "path": "docs/guides/test-runner.md", "excerpt": "``` login-tests/ mobium.config.json tests/ login.test.json ``` `mobium.config.json` says where the tests are and which devices they run on. A **project** is a device to run on: ```json { \"testDir\": \"tests\", \"projects\": [ {\"name\": \"android\", \"device\": \"emulator-5554\"} ] } ``` `tests/login.test.json` is two tests of MobiumApp's Login Demo. Each step is exactly what [`app_batch`](../API.md) takes — a tool and its argume…", "gold": false}, {"id": "docs/guides/test-runner.md#stepping-through-a-test", "heading": "Stepping through a test", "path": "docs/guides/test-runner.md", "excerpt": "`--debug` stops before every step, prints it and the screen, and waits: Enter runs the step, `m` maps again, `c` runs the rest of the test, `q` quits. One project at a time, and the test's timeout is off while you read. ``` $ mobium test mobiumapp/form.test.json -g checkbox --project android --debug [android] form.test.json › a checkbox reaches the state asked for — beforeEach {\"arguments\":{\"target\":\"label=Form Demo\"…", "gold": false}], "missed": false, "facts": ["The app registers hooks by name with the gray-box library (GrayBox.register), and a test calls one with mobium hook <name> [args], or app_hook from MCP, getting back what it returned. ⟦GrayBox.register ; mobium hook / app_hook⟧", "Hooks answer only when the app was launched with --gray-box; otherwise the call is device_not_ready. ⟦without --gray-box is device_not_ready⟧"], "concern": "", "check": "Claude's reading: hook.go's help and agent/graybox.go (15 s default limit, device_not_ready when not launched with the gray box) match the guide's Hooks section. Verified in: cmd/mobium/hook.go:8, internal/agent/graybox.go:150, internal/agent/graybox.go:192."}, {"id": "g058", "kind": "multi", "question": "My app is native Swift and Kotlin, not React Native. What does it have to do so that mobium test waits for its background loading before each step?", "tags": ["how-to", "test-author"], "gold": [{"id": "docs/guides/graybox-tutorial.md#5-your-own-app", "heading": "5. Your own app", "path": "docs/guides/graybox-tutorial.md", "excerpt": "The library is small, and what it writes is the whole contract. In a React Native app, copy MobiumApp's `modules/graybox` (Swift and Kotlin, about 160 lines between them) and call `busy` and `idle` around the work a test should wait for. In a native app, write the same lines yourself, only when launched with the gray box on — on iOS the argument `-MobiumGrayBox YES`, on Android the intent extra `MobiumGrayBox=true`: …"}, {"id": "docs/guides/graybox-tutorial.md#4-turning-the-gray-box-on", "heading": "4. Turning the gray box on", "path": "docs/guides/graybox-tutorial.md", "excerpt": "One key in the test file, beside `app`: ```json { \"app\": \"dev.mobium.mobiumapp\", \"grayBox\": true, \"beforeEach\": [ ``` Each test's launch now turns the library on, and every step waits for the app to say it is idle before finding its target: ``` $ mobium test ok [android · emulator-5554] busy.test.json › a row tapped after a quiet refresh is current (1) (7s) ok [android · emulator-5554] busy.test.json › a row tapped a…"}], "retrieved": [{"id": "docs/guides/graybox-tutorial.md#5-your-own-app", "heading": "5. Your own app", "path": "docs/guides/graybox-tutorial.md", "excerpt": "The library is small, and what it writes is the whole contract. In a React Native app, copy MobiumApp's `modules/graybox` (Swift and Kotlin, about 160 lines between them) and call `busy` and `idle` around the work a test should wait for. In a native app, write the same lines yourself, only when launched with the gray box on — on iOS the argument `-MobiumGrayBox YES`, on Android the intent extra `MobiumGrayBox=true`: …", "gold": true}, {"id": "skills/mobile-check/SKILL.md#mobium-mobile-automation-cli-reference", "heading": "Mobium Mobile Automation — CLI Reference", "path": "skills/mobile-check/SKILL.md", "excerpt": "The `mobium` CLI automates **mobile apps** on Android emulators and phones, and iOS simulators and iPhones. A background daemon keeps the device session alive between commands, so each command is fast after the first. ``` mobium launch com.example.shop && mobium map && mobium tap @e5 && mobium map ``` What the app is built with decides how to reach it: | App type | How | | --- | --- | | Native (Android SDK, Jetpack C…", "gold": false}, {"id": "skills/mobile-check/SKILL.md#hybrid-apps-webviews", "heading": "Hybrid apps (WebViews)", "path": "skills/mobile-check/SKILL.md", "excerpt": "Web content inside an app is a separate context: ```sh mobium contexts # NATIVE_APP, WEBVIEW_com.example mobium context WEBVIEW_com.example # map and tap now work on the page mobium context NATIVE_APP # back to the native shell ``` This works on **both platforms**. Android WebViews must be debuggable (`setWebContentsDebuggingEnabled(true)`) and iOS WKWebViews must be inspectable (`webView.isInspectable = true` on iOS…", "gold": false}, {"id": "skills/mobile-check/SKILL.md#getting-to-the-screen-you-want", "heading": "Getting to the screen you want", "path": "skills/mobile-check/SKILL.md", "excerpt": "- `mobium current` — which app is in the foreground - `mobium state <package|bundle-id>` — any app: not installed, not running, background or foreground - `mobium shake` — shake an emulator or simulator (shake-to-undo, a debug menu); a real phone refuses. Check the screen after: whether the app reacts is its own detector's business - `mobium biometric` — whether a face or finger is enrolled; `enroll` / `unenroll` set…", "gold": false}, {"id": "docs/BACK.md#with-predictive-back-turned-on", "heading": "With predictive back turned on", "path": "docs/BACK.md", "excerpt": "Apps targeting Android 16 and later are moving to predictive back, so on 2026-10-02 MobiumApp was built once with Expo's `predictiveBackGestureEnabled: true` — `android:enableOnBackInvokedCallback=\"true\"` in the manifest, everything else the same — and the probe and `back.sh` run against it: | Device | key, right edge, left edge from a demo | Back from home | | --- | --- | --- | | Pixel 8 Pro, Android 17 | demo → hom…", "gold": false}], "missed": false, "facts": ["Write MOBIUM-GRAYBOX lines (on, busy=<n> tag=<what> at each change of work in flight, lift) to the device log: on iOS os_log subsystem dev.mobium.graybox, on Android logcat tag MobiumGrayBox. ⟦dev.mobium.graybox ; MobiumGrayBox⟧", "Write them only when launched with the gray box on: the argument -MobiumGrayBox YES on iOS, the intent extra MobiumGrayBox=true on Android. ⟦-MobiumGrayBox YES⟧", "In the test file set \"grayBox\": true beside \"app\", so each test's launch turns it on. ⟦\"grayBox\": true⟧"], "concern": "", "check": "Claude's reading: the log prefix, iOS argument and subsystem, Android extra and tag all match device/graybox.go and grayboxstream.go; the test-file key is in tutorial section 4, the native lines in section 5. Verified in: internal/device/graybox.go:69, internal/device/graybox.go:74, internal/device/graybox.go:77, internal/device/grayboxstream.go:77, internal/device/grayboxstream.go:80, internal/testrun/file.go:32."}, {"id": "g059", "kind": "unanswerable", "question": "How do I split my mobium test suite across four CI machines so that each one runs a quarter of the test files?", "tags": ["ci-engineer"], "gold": [], "retrieved": [{"id": "docs/guides/test-runner.md#10-a-page-to-run-tests-from---ui", "heading": "10. A page to run tests from: `--ui`", "path": "docs/guides/test-runner.md", "excerpt": "```sh mobium test --ui --open ``` serves a page on this machine that lists the suite by file, with each test's result on each project. ▶ runs one test, a file, or everything; each step appears with the screen after it as it runs, and **Re-run failed** runs exactly what failed. The files are read again for every run, so a test you just saved is the test that runs. A run from the page is the run `mobium test` makes fro…", "gold": false}, {"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": false}, {"id": "docs/guides/test-runner.md#6-more-than-one-device", "heading": "6. More than one device", "path": "docs/guides/test-runner.md", "excerpt": "Add a project per device. An iOS simulator's id is one Mac's, and a phone's is somebody's, so a project can take its device from the environment, and an unset variable is refused by name before any test runs: ```json { \"testDir\": \"tests\", \"projects\": [ {\"name\": \"android\", \"device\": \"emulator-5554\"}, {\"name\": \"ios\", \"device\": \"${MOBIUM_IOS_DEVICE}\", \"driver\": \"wda\"} ] } ``` ```sh MOBIUM_IOS_DEVICE=<simulator-udid> mob…", "gold": false}, {"id": "tests/README.md#tests", "heading": "Tests", "path": "tests/README.md", "excerpt": "Mobium's own tests of MobiumApp, run by `mobium test` — and the suite that holds the runner to its word. The format is in the [test runner guide](../docs/guides/test-runner.md). ```sh cd tests mobium test --project android # emulator-5554 MOBIUM_IOS_DEVICE=<simulator-udid> mobium test # and an iOS simulator mobium test --reporter list,junit,html && mobium show-report mobium test --ui --open # pick, run and watch on a…", "gold": false}], "missed": false, "facts": [], "concern": "", "check": "Claude's reading: no shard option exists; `grep -ri shard` finds nothing in the code or the docs, and the test command's flags (test.go:234-250) parallelize only across devices on one machine (--workers, one worker per device) or lease grid devices. A retriever will return the multi-device and CI sections. Nearest sections: docs/guides/test-runner.md#6-more-than-one-device, docs/guides/test-runner.md#7-in-ci, docs/guides/test-runner.md#the-commands. Verified in: cmd/mobium/test.go:234."}, {"id": "g060", "kind": "unanswerable", "question": "If I don't pass --timeout to mobium test and the config sets no timeout, how long does each test get before it is stopped?", "tags": ["test-author"], "gold": [], "retrieved": [{"id": "docs/guides/test-runner.md#2-run-it", "heading": "2. Run it", "path": "docs/guides/test-runner.md", "excerpt": "From the directory with the config: ``` $ mobium test ok [android] login.test.json › a wrong password is refused (7.7s) ok [android] login.test.json › the demo account signs in (7.8s) 2 passed (15.5s) ``` Exit status 0. Nothing in the test sleeps: every action waits for its own target ([auto-wait](autowait.md)), and every assertion retries until it holds or its timeout — ten seconds unless the step says otherwise.", "gold": false}, {"id": "CHALLENGES#157", "heading": "157. An iOS background of a minute or more timed out", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** `docs/checks/otp.sh`, sending MobiumApp away for 62 seconds to let its code expire, on the iPhone 17 Pro simulator. `app_background` takes up to 180 seconds, and on iOS it failed at any length past about one minute with \"context deadline exceeded\". WebDriverAgent's `deactivateApp` answers only once the app is back, and every request to it has a sixty-second client timeout. Android backgrounds by pressin…", "gold": false}, {"id": "docs/guides/graybox-tutorial.md#2-it-fails", "heading": "2. It fails", "path": "docs/guides/graybox-tutorial.md", "excerpt": "``` $ mobium test FAIL [android · emulator-5554] busy.test.json › a row tapped after a quiet refresh is current (1) (6.9s) step 3 (app_wait_for): [timeout] step 3 of 3 (app_wait_for) failed: timed out after 3.003s waiting for testid=busyOutcome to contain \": current\" — its text is \"row B, generation 1: stale\"; steps 1-2 ran before it, and nothing after FAIL [android · emulator-5554] busy.test.json › a row tapped afte…", "gold": false}, {"id": "docs/guides/test-runner.md#the-commands", "heading": "The commands", "path": "docs/guides/test-runner.md", "excerpt": "| Command | What it does | | --- | --- | | `mobium test` | runs every `*.test.json` under the config's `testDir`, on every project | | `mobium test tests/login.test.json` | runs one file, or every file under a directory | | `mobium test -g login` | runs the tests whose title — \"file › name\" — matches a regular expression | | `mobium test --last-failed` | runs only the tests that failed last time | | `mobium test --pr…", "gold": false}, {"id": "docs/guides/graybox-tutorial.md#1-the-test", "heading": "1. The test", "path": "docs/guides/graybox-tutorial.md", "excerpt": "The Busy Demo's **Refresh quietly** starts 0.4 to 1.6 seconds of work and leaves the old rows up while it runs; then a new generation of rows replaces them. Tapping a row says whether it was `current` or `stale`. The test taps the refresh, then Row B, and expects the row to be current — five times, each from a fresh app: ``` busy-tests/ mobium.config.json tests/ busy.test.json ``` ```json { \"testDir\": \"tests\", \"proje…", "gold": false}], "missed": false, "facts": [], "concern": "Docs gap: the 60 s default per-test timeout (cmd/mobium/test.go:84, 239) is not stated anywhere in the docs; test-runner.md's commands table could say it.", "check": "Claude's reading: the code's default is 60 s per test (test.go:84 and the flag default at 239), but no corpus section states it: the commands table gives `--timeout 30s` as an example and says the config's timeout is milliseconds, and section 2's \"ten seconds\" is each assertion's timeout, the likely wrong answer. Nearest sections: docs/guides/test-runner.md#the-commands, docs/guides/test-runner.md#2-run-it. Verified in: cmd/mobium/test.go:84, cmd/mobium/test.go:239."}, {"id": "g061", "kind": "fact", "question": "My Charles proxy listens on port 8888 on my Mac. How do I send an Android emulator's app traffic through it with Mobium without looking up the Mac's LAN address?", "tags": ["how-to", "test-author", "new since 7b590a4"], "gold": [{"id": "docs/guides/network.md#5-through-a-proxy", "heading": "5. Through a proxy", "path": "docs/guides/network.md", "excerpt": "`--proxy host:port` points the device's HTTP proxy at a debugging proxy — Charles, Fiddler, mitmproxy, anything that listens on a port — so it sees what the app sends and receives. A proxy on `127.0.0.1` or `localhost` is this machine's: Mobium reverses its port with `adb reverse` before pointing the device at it, so there is no address on the network to find and no firewall in the way. Measured on the emulator on 20…"}], "retrieved": [{"id": "docs/guides/network.md#5-through-a-proxy", "heading": "5. Through a proxy", "path": "docs/guides/network.md", "excerpt": "`--proxy host:port` points the device's HTTP proxy at a debugging proxy — Charles, Fiddler, mitmproxy, anything that listens on a port — so it sees what the app sends and receives. A proxy on `127.0.0.1` or `localhost` is this machine's: Mobium reverses its port with `adb reverse` before pointing the device at it, so there is no address on the network to find and no firewall in the way. Measured on the emulator on 20…", "gold": true}, {"id": "docs/PROXY.md#a-proxy-between-the-app-and-its-servers", "heading": "A proxy between the app and its servers", "path": "docs/PROXY.md", "excerpt": "What it would take for Mobium to route a device's traffic through a debugging proxy, so a test can see, shape and change what an app sends and receives — and to drive Charles, as an opt-in, the way a tester drives it by hand: record a session, throttle, switch Map Local and Rewrite rules on and off. What was measured, and the plan, in the order it should be built. **Status on 2026-10-22.** Step 1 is measured (below),…", "gold": false}, {"id": "docs/PROXY.md#the-shape", "heading": "The shape", "path": "docs/PROXY.md", "excerpt": "Two layers, the second opt-in. - **A proxy, any proxy.** `mobium network --proxy <host:port>` points the device at a proxy and reads it back; `--no-proxy` takes it off; the end of the session puts back what was there, as every network setting is put back. A proxy's root certificate is installed where the device allows it, so HTTPS can be decrypted. This works with Charles, Fiddler, mitmproxy or anything else that lis…", "gold": false}, {"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": false}, {"id": "docs/PROXY.md#what-was-measured-2026-10-20", "heading": "What was measured — 2026-10-20", "path": "docs/PROXY.md", "excerpt": "Charles 5.2.1 headless on the Mac, with a configuration of its own, and the Android 15 emulator. - **The configuration file can be written, not clicked.** Charles writes only what differs from its defaults, so its element names were read from its classes: `proxyConfiguration` holds `port`, `decryptSSL`, `sslLocations` (`locationPatterns` of `locationMatch`, each a `location` and `enabled`) and `macOSXConfiguration` w…", "gold": false}], "missed": false, "facts": ["Run `mobium network --proxy 127.0.0.1:8888` (host:port) to set the device's HTTP proxy. ⟦--proxy⟧", "A proxy on 127.0.0.1 or localhost is the host machine's: Mobium reverses its port with adb reverse before pointing the device at it, so no LAN address or firewall is involved. ⟦adb reverse⟧"], "concern": "", "check": "Claude's reading: network.md section 5 gives the command and the adb reverse behavior; code reverses the port only for a loopback host (IsLoopback) and ParseProxy takes host:port only. PROXY.md describes a planned `--proxy charles` that is not built (ParseProxy would refuse it), so an answer offering it is wrong. Verified in: cmd/mobium/network.go:76, internal/agent/network.go:192, internal/device/proxy.go:134, internal/mobiumdriver/network.go:78."}, {"id": "g062", "kind": "fact", "question": "I removed the emulator's proxy with `adb shell settings delete global http_proxy`, it reads back null, yet my app still tries to connect to 127.0.0.1:8888. Why, and how do I clear it for real?", "tags": ["troubleshooting", "test-author", "new since 7b590a4"], "gold": [{"id": "docs/guides/network.md#5-through-a-proxy", "heading": "5. Through a proxy", "path": "docs/guides/network.md", "excerpt": "`--proxy host:port` points the device's HTTP proxy at a debugging proxy — Charles, Fiddler, mitmproxy, anything that listens on a port — so it sees what the app sends and receives. A proxy on `127.0.0.1` or `localhost` is this machine's: Mobium reverses its port with `adb reverse` before pointing the device at it, so there is no address on the network to find and no firewall in the way. Measured on the emulator on 20…"}], "retrieved": [{"id": "docs/PROXY.md#pointing-each-device-at-it", "heading": "Pointing each device at it", "path": "docs/PROXY.md", "excerpt": "| Device | Proxy | Its certificate | | --- | --- | --- | | Android emulator | `settings put global http_proxy`, read back, and `adb reverse tcp:<port> tcp:<port>` so `127.0.0.1` on the device is the Mac | the user store, trusted only by apps that opt in; the system store needs a writable system image | | Android phone, TV | the same, over USB or Wi-Fi adb, no root | the user store only | | iOS simulator | the Mac's o…", "gold": false}, {"id": "docs/guides/network.md#5-through-a-proxy", "heading": "5. Through a proxy", "path": "docs/guides/network.md", "excerpt": "`--proxy host:port` points the device's HTTP proxy at a debugging proxy — Charles, Fiddler, mitmproxy, anything that listens on a port — so it sees what the app sends and receives. A proxy on `127.0.0.1` or `localhost` is this machine's: Mobium reverses its port with `adb reverse` before pointing the device at it, so there is no address on the network to find and no firewall in the way. Measured on the emulator on 20…", "gold": true}, {"id": "docs/PROXY.md#2---proxy-on-android", "heading": "2. `--proxy` on Android", "path": "docs/PROXY.md", "excerpt": "**The setting, done 2026-10-22** (`docs/guides/network.md`, section 5): set, read back from the keys in force, taken off with `:0` and every key deleted, put back at the session's end; a loopback proxy's port reversed before the device points at it, and only Mobium's reverses removed. A reverse that was there before is left — a test caught the first version taking it as its own. `proxy.sh` fetches a port nothing on t…", "gold": false}, {"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": false}, {"id": "docs/ROADMAP.md#under-consideration", "heading": "Under consideration", "path": "docs/ROADMAP.md", "excerpt": "- **Locators for when there is no ref** (written down 2026-10-12). A ref from `map` lasts one map, so an agent has one and a `mobium test` file does not: a hand-written test has the flat `kind=value` locators — text, label, testid, role, class, path, narrowed by `,role=` — which match one element or are refused. That is right on a form and leaves nothing durable on a list. Every Ice Cubes post has a \"…\" (CHALLENGES 2…", "gold": false}], "missed": false, "facts": ["Android derives global_http_proxy_host and _port from http_proxy, and deleting http_proxy leaves them, and the proxy, in force. ⟦global_http_proxy_host⟧", "`mobium network --no-proxy` takes it off the way that sticks: http_proxy set to :0, then every proxy key deleted. ⟦--no-proxy ; :0⟧"], "concern": "", "check": "Claude's reading: network.md section 5 states both facts; proxy.go writes `:0` then deletes the host, port, exclusion list and PAC keys and reads the proxy in force back. PROXY.md#what-was-measured-2026-10-20 has the same finding at length but no Mobium command. Verified in: internal/device/proxy.go:16, internal/device/proxy.go:69, cmd/mobium/network.go:77."}, {"id": "g063", "kind": "fact", "question": "Can Mobium point my real Pixel's network traffic at a debugging proxy, and can it do the same for an iPhone?", "tags": ["support", "new-user", "new since 7b590a4"], "gold": [{"id": "docs/guides/network.md#what-each-device-can-do", "heading": "What each device can do", "path": "docs/guides/network.md", "excerpt": "| | Offline | Latency and bandwidth | A proxy | | --- | --- | --- | --- | | **Android emulator** | yes | yes | yes | | **Android phone** | yes | no — shaping traffic needs root, which a phone does not give | yes — the same setting, no root (Pixel 8 Pro, Android 17) | | **iOS simulator or iPhone** | no | no — nothing outside iOS controls its network | no | Offline is airplane mode, which any Android device takes. Late…"}], "retrieved": [{"id": "docs/PROXY.md#a-proxy-between-the-app-and-its-servers", "heading": "A proxy between the app and its servers", "path": "docs/PROXY.md", "excerpt": "What it would take for Mobium to route a device's traffic through a debugging proxy, so a test can see, shape and change what an app sends and receives — and to drive Charles, as an opt-in, the way a tester drives it by hand: record a session, throttle, switch Map Local and Rewrite rules on and off. What was measured, and the plan, in the order it should be built. **Status on 2026-10-22.** Step 1 is measured (below),…", "gold": false}, {"id": "docs/guides/network.md#5-through-a-proxy", "heading": "5. Through a proxy", "path": "docs/guides/network.md", "excerpt": "`--proxy host:port` points the device's HTTP proxy at a debugging proxy — Charles, Fiddler, mitmproxy, anything that listens on a port — so it sees what the app sends and receives. A proxy on `127.0.0.1` or `localhost` is this machine's: Mobium reverses its port with `adb reverse` before pointing the device at it, so there is no address on the network to find and no firewall in the way. Measured on the emulator on 20…", "gold": false}, {"id": "docs/PROXY.md#2---proxy-on-android", "heading": "2. `--proxy` on Android", "path": "docs/PROXY.md", "excerpt": "**The setting, done 2026-10-22** (`docs/guides/network.md`, section 5): set, read back from the keys in force, taken off with `:0` and every key deleted, put back at the session's end; a loopback proxy's port reversed before the device points at it, and only Mobium's reverses removed. A reverse that was there before is left — a test caught the first version taking it as its own. `proxy.sh` fetches a port nothing on t…", "gold": false}, {"id": "docs/PROXY.md#what-was-measured-2026-10-20", "heading": "What was measured — 2026-10-20", "path": "docs/PROXY.md", "excerpt": "Charles 5.2.1 headless on the Mac, with a configuration of its own, and the Android 15 emulator. - **The configuration file can be written, not clicked.** Charles writes only what differs from its defaults, so its element names were read from its classes: `proxyConfiguration` holds `port`, `decryptSSL`, `sslLocations` (`locationPatterns` of `locationMatch`, each a `location` and `enabled`) and `macOSXConfiguration` w…", "gold": false}, {"id": "docs/guides/network.md#what-each-device-can-do", "heading": "What each device can do", "path": "docs/guides/network.md", "excerpt": "| | Offline | Latency and bandwidth | A proxy | | --- | --- | --- | --- | | **Android emulator** | yes | yes | yes | | **Android phone** | yes | no — shaping traffic needs root, which a phone does not give | yes — the same setting, no root (Pixel 8 Pro, Android 17) | | **iOS simulator or iPhone** | no | no — nothing outside iOS controls its network | no | Offline is airplane mode, which any Android device takes. Late…", "gold": true}], "missed": false, "facts": ["On an Android phone the proxy works: the same setting as the emulator, with no root needed (measured on a Pixel 8 Pro, Android 17). ⟦no root⟧", "On an iOS simulator or iPhone, Mobium cannot set a proxy (nor offline or shaping); iOS refuses."], "concern": "", "check": "Claude's reading: the table in network.md has a proxy column added after the pin; app_network on an iOS driver has no Networker capability and is refused (network.go:71). PROXY.md plans a Wi-Fi proxy on a real iPhone through Settings (step 5), not built — a right answer says no today. Verified in: internal/device/proxy.go:69, internal/agent/network.go:71, internal/agent/schema.go:2135."}, {"id": "g064", "kind": "fact", "question": "Will Mobium's device proxy capture the HTTP requests of an app written in Flutter?", "tags": ["support", "test-author", "new since 7b590a4"], "gold": [{"id": "docs/PROXY.md#what-a-proxy-cannot-see", "heading": "What a proxy cannot see", "path": "docs/PROXY.md", "excerpt": "Every result names which of these applies rather than reporting an empty session as a quiet app. - **Flutter ignores the system proxy.** Dart's HTTP client reads no proxy setting unless the app gives it one, so a Flutter app's traffic goes around the proxy. - **Android apps trust only system certificates since Android 7**, unless their network security configuration opts in to user ones — debug builds usually, releas…"}], "retrieved": [{"id": "docs/guides/network.md#5-through-a-proxy", "heading": "5. Through a proxy", "path": "docs/guides/network.md", "excerpt": "`--proxy host:port` points the device's HTTP proxy at a debugging proxy — Charles, Fiddler, mitmproxy, anything that listens on a port — so it sees what the app sends and receives. A proxy on `127.0.0.1` or `localhost` is this machine's: Mobium reverses its port with `adb reverse` before pointing the device at it, so there is no address on the network to find and no firewall in the way. Measured on the emulator on 20…", "gold": false}, {"id": "docs/PROXY.md#what-was-measured-2026-10-20", "heading": "What was measured — 2026-10-20", "path": "docs/PROXY.md", "excerpt": "Charles 5.2.1 headless on the Mac, with a configuration of its own, and the Android 15 emulator. - **The configuration file can be written, not clicked.** Charles writes only what differs from its defaults, so its element names were read from its classes: `proxyConfiguration` holds `port`, `decryptSSL`, `sslLocations` (`locationPatterns` of `locationMatch`, each a `location` and `enabled`) and `macOSXConfiguration` w…", "gold": false}, {"id": "docs/PROXY.md#what-a-proxy-cannot-see", "heading": "What a proxy cannot see", "path": "docs/PROXY.md", "excerpt": "Every result names which of these applies rather than reporting an empty session as a quiet app. - **Flutter ignores the system proxy.** Dart's HTTP client reads no proxy setting unless the app gives it one, so a Flutter app's traffic goes around the proxy. - **Android apps trust only system certificates since Android 7**, unless their network security configuration opts in to user ones — debug builds usually, releas…", "gold": true}, {"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": false}], "missed": false, "facts": ["No: Flutter ignores the system proxy — Dart's HTTP client reads no proxy setting unless the app gives it one, so its traffic goes around the proxy. ⟦Dart ; system proxy⟧"], "concern": "", "check": "Claude's reading: Mobium only sets Android's global http_proxy (proxy.go SetProxy), so an app that ignores the system proxy is not covered; the Flutter behavior itself is a platform fact, not in Mobium code. network.md#5-through-a-proxy also says \"Flutter does not\" in one line — reviewer may want it as a second acceptable gold. Verified in: internal/device/proxy.go:69."}, {"id": "g065", "kind": "fact", "question": "Why does Mobium shape the emulator's traffic itself instead of using the emulator console's `network speed` and `network delay` commands?", "tags": ["rationale", "contributor"], "gold": [{"id": "docs/guides/network.md#why-not-the-emulators-own-throttling", "heading": "Why not the emulator's own throttling", "path": "docs/guides/network.md", "excerpt": "The Android emulator's console has `network speed` and `network delay`, and they look made for this. They accept a setting and read it back — and change nothing: on emulator 37.1.11, 2MB at a 1000 kbit/s limit still arrived in 1.1 seconds where 16 were due, and a 500ms delay left a ping at 1ms. So Mobium does not use them; it shapes the traffic itself, and every figure above was measured from the traffic, not the set…"}], "retrieved": [{"id": "docs/guides/network.md#why-not-the-emulators-own-throttling", "heading": "Why not the emulator's own throttling", "path": "docs/guides/network.md", "excerpt": "The Android emulator's console has `network speed` and `network delay`, and they look made for this. They accept a setting and read it back — and change nothing: on emulator 37.1.11, 2MB at a 1000 kbit/s limit still arrived in 1.1 seconds where 16 were due, and a 500ms delay left a ping at 1ms. So Mobium does not use them; it shapes the traffic itself, and every figure above was measured from the traffic, not the set…", "gold": true}, {"id": "skills/mobile-check/SKILL.md#network", "heading": "Network", "path": "skills/mobile-check/SKILL.md", "excerpt": "- `mobium network` — what is in place: online or offline, and any shaping - `mobium network --offline` / `--online` — airplane mode, waited for until the network is really gone or back; an emulator or a real Android phone - `mobium network --latency 300 --download 1600 --upload 750` — shape the traffic, replacing any shaping before; an emulator only (it needs root) - `mobium network --reset` — no shaping, airplane mo…", "gold": false}, {"id": "CHALLENGES#findings-that-were-not-defects", "heading": "Findings that were not defects", "path": "docs/CHALLENGES.md", "excerpt": "Worth recording because each one closed off an approach that looked obvious. - **Predictive back on Android 15 closes a React Native app.** MobiumApp built with predictive back turned on went back to closing on every back from a demo on the Android 15 AVD, `BackHandler` never called, while on Android 17 — the AVD and the Pixel 8 Pro — it went back to its home screen. React Native 0.86 registers the callback that repl…", "gold": false}, {"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": false}, {"id": "docs/guides/network.md#the-commands", "heading": "The commands", "path": "docs/guides/network.md", "excerpt": "| Command | What it does | | --- | --- | | `mobium network` | reads what the device has: online or offline, and any shaping | | `mobium network --offline` | airplane mode on, and waits for the network to go | | `mobium network --online` | airplane mode off, and waits for the network to come back | | `mobium network --latency 300` | adds 300ms to every round trip (emulator) | | `mobium network --download 1600 --upload…", "gold": false}], "missed": false, "facts": ["The console commands accept and read back a setting but change nothing: 2MB at a 1000 kbit/s limit still arrived in 1.1 seconds where 16 were due, and a 500ms delay left a ping at 1ms. ⟦1.1 seconds⟧", "So Mobium shapes the traffic itself (Linux traffic control) and measures from the traffic, not the setting."], "concern": "", "check": "Claude's reading: network.md's section and the comment at device/network.go:18 agree on the measurement (emulator 37.1.11); the code uses `tc` under su. Verified in: internal/device/network.go:18, internal/device/network.go:111."}, {"id": "g066", "kind": "fact", "question": "On iOS the location permission prompt shows Allow Once, Allow While Using App and Don't Allow. What happens if my script runs `mobium alert accept` on it, and how do I choose one of them?", "tags": ["behavior", "test-author"], "gold": [{"id": "skills/mobile-check/SKILL.md#dialogs", "heading": "Dialogs", "path": "skills/mobile-check/SKILL.md", "excerpt": "- `mobium alert` — is a system or app dialog up, what does it say, and what are its buttons - `mobium alert accept` / `dismiss` — yes and no, on a dialog of one or two buttons: a two-button permission prompt is granted by accept and denied by dismiss, in any language. **A dialog of three or more is refused**, naming its buttons — the location prompt has two that grant — and every answer says which button it pressed. …"}], "retrieved": [{"id": "CHALLENGES#305", "heading": "305. `accept` on iOS's location prompt pressed Don't Allow, and said only \"accepted\"", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** reviewing a golden-set question for the docs evaluation — \"which button does `alert accept` press on an iOS permission prompt?\" — whose right answer, Don't Allow, read as a defect rather than an answer. Measured on an iPhone 17 Pro simulator, iOS 26.5, on MobiumApp's Dialog Demo, and on the Android 15 emulator. CHALLENGES 63 and 106 found that accept and dismiss press a button the platform picks, and se…", "gold": false}, {"id": "CHALLENGES#76", "heading": "76. The fix for 71 hid system dialogs from `map`", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** MobiumApp on the iPhone, the same day. The app's location prompt was on screen and `alert` reported it word for word — and `map` listed only the app underneath: Back, the two drafts, \"Ask for location\". Tapping \"Allow While Using App\" answered \"no element matches\". `current` said `dev.mobium.mobiumapp`. It was 71's hint, still in force. `defaultActiveApplication` had been set to MobiumApp by the launch …", "gold": false}, {"id": "CHALLENGES#63", "heading": "63. `accept` denied the permission and `dismiss` granted it", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** checking what the new alert tool actually did, rather than what it was called. On iOS 26.5, from a fresh permission reset each time: | | outcome | | --- | --- | | `app_alert accept` | permission **denied** | | `app_alert dismiss` | permission **granted** | Backwards, and reproducibly so. **The first explanation written here was a guess, and it was wrong in a way worth keeping.** It said accept presses t…", "gold": false}], "missed": true, "facts": ["accept and dismiss only answer a dialog of one or two buttons; a dialog of three or more is refused, naming its buttons, because more than one may mean yes. ⟦three or more⟧", "Press one by caption or position from 1 with `mobium alert --button \"Allow While Using App\"`; captions match in any case with straight or curly quotes. ⟦--button⟧"], "concern": "", "check": "Claude's reading: SKILL.md#dialogs states both; alert.go refuses len(buttons) > 2 with the remedy to use button, and normalizes curly quotes for captions. CHALLENGES#305 is the history (accept pressed Don't Allow) but is not needed for the answer. Verified in: internal/agent/alert.go:201, internal/agent/alert.go:262, internal/agent/alert.go:409, cmd/mobium/alert.go:52."}, {"id": "g067", "kind": "fact", "question": "In a mobium test file, how do I make iOS's offer to save a password after login get answered automatically in every test, and what does that do when the same file runs on Android?", "tags": ["how-to", "test-author"], "gold": [{"id": "docs/guides/test-runner.md#writing-tests", "heading": "Writing tests", "path": "docs/guides/test-runner.md", "excerpt": "- **Find targets with `map` first.** `mobium map` on the screen you are testing gives each element's locator; `testid=` is the one that survives a translation and a redesign. - **Assert with `app_wait_for`**, never a sleep. `--for` in the CLI is `condition` in a step: `visible`, `hidden`, `text` (with `exact`), `value`, `enabled`, `disabled`, `checked`, `unchecked`, `selected`, `unselected`, `focused`, `count`, and `…"}], "retrieved": [{"id": "docs/guides/test-runner.md#writing-tests", "heading": "Writing tests", "path": "docs/guides/test-runner.md", "excerpt": "- **Find targets with `map` first.** `mobium map` on the screen you are testing gives each element's locator; `testid=` is the one that survives a translation and a redesign. - **Assert with `app_wait_for`**, never a sleep. `--for` in the CLI is `condition` in a step: `visible`, `hidden`, `text` (with `exact`), `value`, `enabled`, `disabled`, `checked`, `unchecked`, `selected`, `unselected`, `focused`, `count`, and `…", "gold": true}, {"id": "CHALLENGES#170", "heading": "170. A dialog rule answered in front of an action, not in front of a wait", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** `tests/mobiumapp` run by `mobium test` on the iPhone 15 Plus. \"the demo account signs in, and out\" failed at its wait for the welcome screen, with the failure itself saying that screen was under \"Save Password?\" — the dialog `login.test.json` declares a rule for. A rule (`app_dialogs`) answered a dialog only when an action resolved its target and found the dialog over it. Sign-in is a tap, and iOS raise…", "gold": false}, {"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": false}, {"id": "docs/guides/cli.md#7-several-steps-in-one-call-batch", "heading": "7. Several steps in one call: `batch`", "path": "docs/guides/cli.md", "excerpt": "A known sequence can go as one call — from a file, or `-` for stdin. Every step is checked before the first runs, and it stops at the first failure, with that step's own error: ```json [ {\"name\": \"app_tap\", \"arguments\": {\"target\": \"label=Login Demo\"}}, {\"name\": \"app_fill\", \"arguments\": {\"target\": \"testid=username\", \"text\": \"mobium\"}}, {\"name\": \"app_fill\", \"arguments\": {\"target\": \"testid=password\", \"text\": \"hunter2\"}}…", "gold": false}, {"id": "docs/guides/autowait.md#2-waiting-for-a-control-to-be-enabled", "heading": "2. Waiting for a control to be enabled", "path": "docs/guides/autowait.md", "excerpt": "The Login Demo disables Log In while it signs in. Tap it, and tap it again at once: ``` $ mobium fill testid=username mobium typed \"mobium\" into testid=username $ mobium fill testid=password wrongpass1 typed 10 characters into testid=password, a password field — not echoed $ mobium tap testid=loginBtn tapped testid=loginBtn at (540, 1457) $ mobium wait testid=loginBtn --for disabled testid=loginBtn is disabled after …", "gold": false}], "missed": false, "facts": ["Add an app_dialogs rule in beforeEach: {\"name\": \"app_dialogs\", \"arguments\": {\"when\": \"Save Password\", \"press\": \"Not Now\"}}. ⟦app_dialogs ; beforeEach ; Not Now⟧", "On Android the rule never fires, since that dialog never comes there."], "concern": "", "check": "Claude's reading: test-runner.md 'Writing tests' gives the exact step; dialogs.go matches a rule when the dialog text contains `when`, ignoring case, and presses the captioned button. SKILL.md#dialogs shows the CLI form (`mobium dialogs --when ... --press ...`) but not the test-file form. Verified in: internal/agent/dialogs.go:56, internal/agent/dialogs.go:105, internal/agent/dialogs.go:116."}, {"id": "g068", "kind": "fact", "question": "My Android app posts a notification and I need my test to tap it. `mobium map` doesn't show it — what do I do?", "tags": ["how-to", "test-author"], "gold": [{"id": "skills/mobile-check/SKILL.md#interruptions-and-hardware-buttons", "heading": "Interruptions and hardware buttons", "path": "skills/mobile-check/SKILL.md", "excerpt": "```sh mobium press back # primary navigation on Android; says where it went mobium press back --gesture # the swipe in from the edge; the only back on iOS mobium press home # says the launcher came forward mobium lock lock # a state, not a toggle mobium call ring # then accept, or hang mobium sms \"your code is 123456\" mobium timezone Asia/Tokyo mobium notifications # what is in the shade? mobium notifications --post …"}], "retrieved": [{"id": "CHALLENGES#155", "heading": "155. A notification banner hid the app under it on iOS", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** MobiumApp's OTP Demo on the iPhone 17 Pro simulator, iOS 26.5, reading the outcome right after the app posted its code as a notification. While the banner was up — about five seconds — every read answered with SpringBoard: `current` named it, `text testid=otpOutcome` found nothing, and `map` listed the banner and nothing of the app behind it, which was still in front and still taking touches. WebDriverA…", "gold": false}, {"id": "docs/guides/test-runner.md#writing-tests", "heading": "Writing tests", "path": "docs/guides/test-runner.md", "excerpt": "- **Find targets with `map` first.** `mobium map` on the screen you are testing gives each element's locator; `testid=` is the one that survives a translation and a redesign. - **Assert with `app_wait_for`**, never a sleep. `--for` in the CLI is `condition` in a step: `visible`, `hidden`, `text` (with `exact`), `value`, `enabled`, `disabled`, `checked`, `unchecked`, `selected`, `unselected`, `focused`, `count`, and `…", "gold": false}, {"id": "skills/mobile-check/SKILL.md#when-things-fail", "heading": "When things fail", "path": "skills/mobile-check/SKILL.md", "excerpt": "Mobium's errors say what to do; read them rather than retrying blindly. Every failure also carries a **code**, so you can act on the kind without parsing the sentence: `--json` prints it (`\"code\": \"no_such_element\"`, with a `remedy` and `details`), and the exit status groups it: | Exit | Codes | What to do | | --- | --- | --- | | 2 | `invalid_argument` | fix the command; retrying it unchanged cannot help | | 3 | `no_…", "gold": false}, {"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": false}, {"id": "docs/ROADMAP.md#under-consideration", "heading": "Under consideration", "path": "docs/ROADMAP.md", "excerpt": "- **Locators for when there is no ref** (written down 2026-10-12). A ref from `map` lasts one map, so an agent has one and a `mobium test` file does not: a hand-written test has the flat `kind=value` locators — text, label, testid, role, class, path, narrowed by `,role=` — which match one element or are refused. That is right on a form and leaves nothing durable on a list. Every Ice Cubes post has a \"…\" (CHALLENGES 2…", "gold": false}], "missed": true, "facts": ["A notification cannot be tapped until the shade is open: run `mobium notifications --shade open`, then `map`, then tap it. ⟦--shade open⟧", "Close the shade when finished, or every later locator fails against the panel covering the app."], "concern": "", "check": "Claude's reading: SKILL.md states it; adb.go runs `cmd statusbar expand-notifications` for open, and the tool description says opening or closing the shade discards the last map's refs. Verified in: cmd/mobium/notifications.go:42, internal/device/adb.go:1548, internal/agent/schema.go:983."}, {"id": "g069", "kind": "fact", "question": "I want one test to run with VoiceOver on, on a real iPhone, without leaving the phone with VoiceOver on afterward. How do I do that with Mobium?", "tags": ["how-to", "test-author", "new since 7b590a4"], "gold": [{"id": "docs/ACCESSIBILITY.md#5-a-screen-reader-as-a-setting-built", "heading": "5. A screen reader as a setting — built", "path": "docs/ACCESSIBILITY.md", "excerpt": "`mobium accessibility screen_reader on` — TalkBack on Android and VoiceOver on an iPhone on iOS 27 — confirmed by reading back, and put back when the session ends, as the other settings are. It makes \"run this test with the screen reader on\" a line in a test file. As built: - **Android:** TalkBack's service added to the enabled ones, the others kept, and `accessibility_enabled` on. Confirmed by Android binding TalkBa…"}], "retrieved": [{"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": false}, {"id": "docs/ACCESSIBILITY.md#5-a-screen-reader-as-a-setting-built", "heading": "5. A screen reader as a setting — built", "path": "docs/ACCESSIBILITY.md", "excerpt": "`mobium accessibility screen_reader on` — TalkBack on Android and VoiceOver on an iPhone on iOS 27 — confirmed by reading back, and put back when the session ends, as the other settings are. It makes \"run this test with the screen reader on\" a line in a test file. As built: - **Android:** TalkBack's service added to the enabled ones, the others kept, and `accessibility_enabled` on. Confirmed by Android binding TalkBa…", "gold": true}, {"id": "docs/ACCESSIBILITY.md#voiceover-on-a-real-iphone-2026-10-20", "heading": "VoiceOver on a real iPhone — 2026-10-20", "path": "docs/ACCESSIBILITY.md", "excerpt": "On the iPhone 15 Plus, iOS 27.0.1, through WebDriverAgent 16.12.8 rebuilt with Xcode 27.1, called directly over HTTP. VoiceOver was off before, and read back off after every run. - **The runner has to be built with Xcode 27.** WebDriverAgent's `/wda/voiceOver/enable`, `/disable`, `/enabled`, `/move` and `/currentSpeech` reach XCUIAutomation's VoiceOver service, which Xcode 27's has and 26.6's does not. The phone's ru…", "gold": false}, {"id": "docs/SETUP.md#with-a-screen-reader-on", "heading": "With a screen reader on", "path": "docs/SETUP.md", "excerpt": "Android's test-automation connection silences every other accessibility service while it is open, unless it is opened not to. So on a device with TalkBack — or VoiceView, on a Fire TV — on, a read of the screen takes the screen reader away for as long as it runs, and an app that publishes its contents only to a screen reader stops publishing them (CHALLENGES 208). Both drivers leave the screen reader running. The def…", "gold": false}], "missed": false, "facts": ["`mobium accessibility screen_reader on` (app_accessibility, setting screen_reader) turns VoiceOver on an iPhone on iOS 27, confirmed by reading back. ⟦screen_reader on ; iOS 27⟧", "It is put back as found when the session ends; on a phone the session's restore is the only safe way to turn it on. ⟦put back when the session ends⟧"], "concern": "", "check": "Claude's reading: ACCESSIBILITY.md step 5 and the code agree: VoiceOver via WebDriverAgent's enable/disable, undo run at session end; simulators and Apple TV are refused (axsettings.go:93). Verified in: internal/agent/schema.go:1624, internal/mobiumdriver/axsettings.go:89, internal/agent/accessibility.go:18, internal/agent/accessibility.go:134."}, {"id": "g070", "kind": "fact", "question": "With VoiceOver turned on on an iPhone, what does `mobium tap` actually do, and what happens if my test tries to swipe?", "tags": ["behavior", "test-author", "new since 7b590a4"], "gold": [{"id": "docs/ACCESSIBILITY.md#1-a-tap-with-voiceover-on-lands-or-is-refused-built-243", "heading": "1. A tap with VoiceOver on lands, or is refused — built, #243", "path": "docs/ACCESSIBILITY.md", "excerpt": "The defect above, fixed before anything is built on VoiceOver, since every later step drives a screen with it on. As built: VoiceOver is asked about before every touch, since it costs milliseconds and a person can turn it on mid-session; tap, `check`, an alert's button and a dialog rule touch, read the cursor back, and double-tap; typing focuses the field that way; every other touch is refused naming VoiceOver; a pho…"}], "retrieved": [{"id": "CHALLENGES#348", "heading": "348. With VoiceOver on, a tap moved its cursor and was reported done", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** measuring what WebDriverAgent's VoiceOver routes give, on the iPhone 15 Plus on iOS 27.0.1, for a plan of what Mobium could do for people who use a screen reader. With VoiceOver on, a touch is not a tap: it moves VoiceOver's cursor to what it touches, as a person's single tap does, and a double tap anywhere activates what the cursor is on. So on MobiumApp `tap \"label=Pro\"` answered `tapped label=Pro` an…", "gold": false}, {"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": false}, {"id": "docs/ACCESSIBILITY.md#voiceover-on-a-real-iphone-2026-10-20", "heading": "VoiceOver on a real iPhone — 2026-10-20", "path": "docs/ACCESSIBILITY.md", "excerpt": "On the iPhone 15 Plus, iOS 27.0.1, through WebDriverAgent 16.12.8 rebuilt with Xcode 27.1, called directly over HTTP. VoiceOver was off before, and read back off after every run. - **The runner has to be built with Xcode 27.** WebDriverAgent's `/wda/voiceOver/enable`, `/disable`, `/enabled`, `/move` and `/currentSpeech` reach XCUIAutomation's VoiceOver service, which Xcode 27's has and 26.6's does not. The phone's ru…", "gold": false}, {"id": "docs/ACCESSIBILITY.md#5-a-screen-reader-as-a-setting-built", "heading": "5. A screen reader as a setting — built", "path": "docs/ACCESSIBILITY.md", "excerpt": "`mobium accessibility screen_reader on` — TalkBack on Android and VoiceOver on an iPhone on iOS 27 — confirmed by reading back, and put back when the session ends, as the other settings are. It makes \"run this test with the screen reader on\" a line in a test file. As built: - **Android:** TalkBack's service added to the enabled ones, the others kept, and `accessibility_enabled` on. Confirmed by Android binding TalkBa…", "gold": false}, {"id": "docs/ACCESSIBILITY.md#1-a-tap-with-voiceover-on-lands-or-is-refused-built-243", "heading": "1. A tap with VoiceOver on lands, or is refused — built, #243", "path": "docs/ACCESSIBILITY.md", "excerpt": "The defect above, fixed before anything is built on VoiceOver, since every later step drives a screen with it on. As built: VoiceOver is asked about before every touch, since it costs milliseconds and a person can turn it on mid-session; tap, `check`, an alert's button and a dialog rule touch, read the cursor back, and double-tap; typing focuses the field that way; every other touch is refused naming VoiceOver; a pho…", "gold": true}], "missed": false, "facts": ["A tap touches the target to move VoiceOver's cursor, reads the cursor back, and double-taps to activate it (also for check, an alert's button and a dialog rule). ⟦double-tap⟧", "Every other touch, such as a swipe, is refused naming VoiceOver. ⟦refused naming VoiceOver⟧"], "concern": "", "check": "Claude's reading: ACCESSIBILITY.md step 1 matches screenreader.go touch() (FocusAt, compare spoken name, ActivateFocused) and voiceOverGuard refusing other touches. A cursor landing elsewhere is refused (screenreader.go:35); SETUP.md#with-a-screen-reader-on says the same in brief. Verified in: internal/agent/screenreader.go:23, internal/mobiumdriver/voiceover.go:111, internal/mobiumdriver/voiceover.go:120."}, {"id": "g071", "kind": "fact", "question": "`mobium speech` on my Android emulator with TalkBack on refuses and says nothing is logged. What do I have to change?", "tags": ["troubleshooting", "test-author", "new since 7b590a4"], "gold": [{"id": "docs/ACCESSIBILITY.md#2-hear-the-screen-reader-appspeech-built", "heading": "2. Hear the screen reader: `app_speech` — built", "path": "docs/ACCESSIBILITY.md", "excerpt": "`mobium speech` and `app_speech` in all five clients: what the screen reader says about the element its cursor is on; with a target, the cursor put on it first; with `walk`, a move forward at a time in the screen reader's own order until it goes no further, comes back round, or `limit` moves are made. Each sentence is beside the element it was said about, its locator, and whether `map` lists it — a heading, a caption…"}], "retrieved": [{"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": false}, {"id": "CHALLENGES#348", "heading": "348. With VoiceOver on, a tap moved its cursor and was reported done", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** measuring what WebDriverAgent's VoiceOver routes give, on the iPhone 15 Plus on iOS 27.0.1, for a plan of what Mobium could do for people who use a screen reader. With VoiceOver on, a touch is not a tap: it moves VoiceOver's cursor to what it touches, as a person's single tap does, and a double tap anywhere activates what the cursor is on. So on MobiumApp `tap \"label=Pro\"` answered `tapped label=Pro` an…", "gold": false}, {"id": "docs/ACCESSIBILITY.md#2-hear-the-screen-reader-appspeech-built", "heading": "2. Hear the screen reader: `app_speech` — built", "path": "docs/ACCESSIBILITY.md", "excerpt": "`mobium speech` and `app_speech` in all five clients: what the screen reader says about the element its cursor is on; with a target, the cursor put on it first; with `walk`, a move forward at a time in the screen reader's own order until it goes no further, comes back round, or `limit` moves are made. Each sentence is beside the element it was said about, its locator, and whether `map` lists it — a heading, a caption…", "gold": true}, {"id": "CHALLENGES#284", "heading": "284. Two audio remedies said to restart with a command that restarts nothing", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** making the emulator's control port refuse, on purpose — the token in its discovery file changed. The refusal was clear, and its remedy was \"restart the emulator with `mobium boot`\"; so was the remedy for an emulator with no control port at all. `mobium boot` on an emulator that is running answers \"mobium-test was already running, as emulator-5554\" and changes nothing, so the remedy, followed, left the e…", "gold": false}], "missed": false, "facts": ["TalkBack's sentence is read from its log, which holds it only with TalkBack's Developer settings' Log output level at VERBOSE. ⟦VERBOSE ; Log output level⟧", "Mobium does not set that level itself — it is TalkBack's own preference — and refuses, naming it, while nothing is logged."], "concern": "", "check": "Claude's reading: ACCESSIBILITY.md step 2 and talkback.go's ErrTalkBackQuiet agree (remedy: Advanced settings > Developer settings > Log output level VERBOSE). The doc also warns verbose logging puts everything TalkBack says in the device log. Verified in: internal/device/talkback.go:31, internal/device/talkback.go:250."}, {"id": "g072", "kind": "fact", "question": "How can I check what TalkBack announces right after my test taps an 'Add to cart' button that updates a live region?", "tags": ["how-to", "test-author", "new since 7b590a4"], "gold": [{"id": "docs/ACCESSIBILITY.md#2-hear-the-screen-reader-appspeech-built", "heading": "2. Hear the screen reader: `app_speech` — built", "path": "docs/ACCESSIBILITY.md", "excerpt": "`mobium speech` and `app_speech` in all five clients: what the screen reader says about the element its cursor is on; with a target, the cursor put on it first; with `walk`, a move forward at a time in the screen reader's own order until it goes no further, comes back round, or `limit` moves are made. Each sentence is beside the element it was said about, its locator, and whether `map` lists it — a heading, a caption…"}], "retrieved": [{"id": "docs/ACCESSIBILITY.md#2-hear-the-screen-reader-appspeech-built", "heading": "2. Hear the screen reader: `app_speech` — built", "path": "docs/ACCESSIBILITY.md", "excerpt": "`mobium speech` and `app_speech` in all five clients: what the screen reader says about the element its cursor is on; with a target, the cursor put on it first; with `walk`, a move forward at a time in the screen reader's own order until it goes no further, comes back round, or `limit` moves are made. Each sentence is beside the element it was said about, its locator, and whether `map` lists it — a heading, a caption…", "gold": true}, {"id": "docs/ACCESSIBILITY.md#talkback-2026-10-05", "heading": "TalkBack — 2026-10-05", "path": "docs/ACCESSIBILITY.md", "excerpt": "Android's test-automation connection silenced every other accessibility service while it was open, so a read of the screen turned TalkBack off for as long as it ran. Both drivers now leave it running (CHALLENGES 208), and with TalkBack on, taps, scrolls and typing land, because Mobium's touches are injected rather than explored — the opposite of VoiceOver above. `docs/checks/screen-reader.sh` holds it. What TalkBack …", "gold": false}, {"id": "CHALLENGES#352", "heading": "352. A check's restore that failed stopped every restore after it, and TalkBack stayed on a phone", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** `speech.sh` on the Pixel 8 Pro (ACCESSIBILITY.md, step 2). TalkBack 17.1 answered the keyboard `app_speech` connects with a dialog, \"New keymap available\", which the emulator's TalkBack never raised. It sat over TalkBack's own settings, so the exit handler putting TalkBack's log output level back could not find the row, and called the check's `fail` — which exits. `lib.sh` ran each handler with `eval`, …", "gold": false}], "missed": false, "facts": ["Run `mobium speech --listen start` before the action and `mobium speech --listen stop` after it; the stop answers with every sentence said in between. ⟦--listen start ; --listen stop⟧", "It must start before the action because a live region's change was said about 0.4 seconds after the tap, before a later call could arrive. ⟦0.4 seconds⟧"], "concern": "", "check": "Claude's reading: ACCESSIBILITY.md step 2 'Listening' describes it; speech.go refuses listen together with a target or walk. On Android each sentence carries a cause (focus, announcement, change); on an iPhone VoiceOver is polled and has none. Verified in: cmd/mobium/speech.go:53, internal/agent/speech.go:39, internal/agent/speech.go:742."}, {"id": "g073", "kind": "fact", "question": "Why does `mobium assistant \"Send a message to Alex saying I'm late\"` get refused when `mobium assistant \"Open Calculator\"` works?", "tags": ["behavior", "agent-builder", "new since 7b590a4"], "gold": [{"id": "docs/ACCESSIBILITY.md#6-voice-assistants-appassistant-built-for-android-and-the-iphone", "heading": "6. Voice assistants: `app_assistant` — built for Android and the iPhone", "path": "docs/ACCESSIBILITY.md", "excerpt": "A tool that asks the platform's assistant in text and answers with what came back and what is in front afterward, for the task-based test above. Its result always says the request was typed, not spoken (`typed`). As built (`mobium assistant \"Open Calculator\" --app com.google.android.calculator`): - **Gemini and Google Assistant**: the assist key opens them; Google Assistant's Keyboard button, or Gemini's field, takes…"}], "retrieved": [{"id": "docs/ACCESSIBILITY.md#6-voice-assistants-appassistant-built-for-android-and-the-iphone", "heading": "6. Voice assistants: `app_assistant` — built for Android and the iPhone", "path": "docs/ACCESSIBILITY.md", "excerpt": "A tool that asks the platform's assistant in text and answers with what came back and what is in front afterward, for the task-based test above. Its result always says the request was typed, not spoken (`typed`). As built (`mobium assistant \"Open Calculator\" --app com.google.android.calculator`): - **Gemini and Google Assistant**: the assist key opens them; Google Assistant's Keyboard button, or Gemini's field, takes…", "gold": true}, {"id": "CHALLENGES#354", "heading": "354. Siri opened the app, and a read during the hand-off said it had not", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** `assistant.sh` on the iPhone 15 Plus (ACCESSIBILITY.md, step 6), which once in four runs reported \"Open MobiumApp did not reach dev.mobium.mobiumapp: com.apple.springboard in front\", while a request by hand and two whole runs after it reached the app. It looked like a cold Siri — a first request failing was what the simulator (351) and the emulator's Google Assistant had done — and it was not: timed by …", "gold": false}, {"id": "skills/mobile-check/SKILL.md#dialogs", "heading": "Dialogs", "path": "skills/mobile-check/SKILL.md", "excerpt": "- `mobium alert` — is a system or app dialog up, what does it say, and what are its buttons - `mobium alert accept` / `dismiss` — yes and no, on a dialog of one or two buttons: a two-button permission prompt is granted by accept and denied by dismiss, in any language. **A dialog of three or more is refused**, naming its buttons — the location prompt has two that grant — and every answer says which button it pressed. …", "gold": false}, {"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": false}], "missed": false, "facts": ["A request that acts for the device owner (call, text, message, send, email, pay, buy, order, book, post, share, delete, transfer) is refused unless the app it is for is named with --app. ⟦names the app / --app⟧"], "concern": "", "check": "Claude's reading: the doc's verb list and the code's sideEffects regex agree (code also has dial, mail, purchase, tweet, venmo, matched as the first verb after an optional greeting). With --app, Mobium reports whether that app came forward (`reached`). Verified in: internal/agent/assistant.go:41, internal/agent/assistant.go:112, cmd/mobium/assistant.go:43."}, {"id": "g074", "kind": "fact", "question": "What do I need on my Mac to record and assert the sounds my app plays on an iOS simulator in a mobium test?", "tags": ["how-to", "test-author", "new since 7b590a4"], "gold": [{"id": "docs/guides/test-runner.md#11-what-the-app-played-audio", "heading": "11. What the app played: `audio`", "path": "docs/guides/test-runner.md", "excerpt": "A capture starts as a step and is asserted at its stop: `expect` is the sounds to hear, in order, each a pitch with an optional length, and `[]` is silence. ```json {\"name\": \"the sequence is heard in order\", \"steps\": [ {\"audio\": {\"action\": \"start\"}}, {\"tap\": \"testid=audioSequence\"}, {\"wait_for\": {\"target\": \"text=finished:\", \"timeout_ms\": 10000}}, {\"audio\": {\"action\": \"stop\", \"path\": \"mobium-report/sequence.wav\", \"exp…"}], "retrieved": [{"id": "docs/guides/test-runner.md#11-what-the-app-played-audio", "heading": "11. What the app played: `audio`", "path": "docs/guides/test-runner.md", "excerpt": "A capture starts as a step and is asserted at its stop: `expect` is the sounds to hear, in order, each a pitch with an optional length, and `[]` is silence. ```json {\"name\": \"the sequence is heard in order\", \"steps\": [ {\"audio\": {\"action\": \"start\"}}, {\"tap\": \"testid=audioSequence\"}, {\"wait_for\": {\"target\": \"text=finished:\", \"timeout_ms\": 10000}}, {\"audio\": {\"action\": \"stop\", \"path\": \"mobium-report/sequence.wav\", \"exp…", "gold": true}, {"id": "docs/ROADMAP.md#under-consideration", "heading": "Under consideration", "path": "docs/ROADMAP.md", "excerpt": "- **Locators for when there is no ref** (written down 2026-10-12). A ref from `map` lasts one map, so an agent has one and a `mobium test` file does not: a hand-written test has the flat `kind=value` locators — text, label, testid, role, class, path, narrowed by `,role=` — which match one element or are refused. That is right on a form and leaves nothing durable on a list. Every Ice Cubes post has a \"…\" (CHALLENGES 2…", "gold": false}, {"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": false}], "missed": false, "facts": ["macOS's System Audio Recording must be allowed for the terminal or app that runs mobium (System Settings › Privacy & Security › Screen & System Audio Recording); without it the stop is refused, naming it. ⟦System Audio Recording⟧", "The capture is of the app alone through a process tap on the Mac, whose helper is built with Xcode's swiftc the first time (about two seconds) and kept. ⟦process tap ; swiftc⟧"], "concern": "", "check": "Claude's reading: section 11 of test-runner.md (part 2) and simaudio.go agree on the permission refusal and swiftc helper. Simulator audio is #263, after the pin. Verified in: internal/device/simaudio.go:28, internal/device/simaudio.go:54, internal/device/simaudio.go:75, internal/device/simaudio.go:246."}, {"id": "g075", "kind": "multi", "question": "I set `mobium network --proxy` to Charles on an Android emulator; plain HTTP shows up in Charles but my app's HTTPS calls don't appear decrypted. What is going on?", "tags": ["troubleshooting", "test-author", "new since 7b590a4"], "gold": [{"id": "docs/guides/network.md#5-through-a-proxy", "heading": "5. Through a proxy", "path": "docs/guides/network.md", "excerpt": "`--proxy host:port` points the device's HTTP proxy at a debugging proxy — Charles, Fiddler, mitmproxy, anything that listens on a port — so it sees what the app sends and receives. A proxy on `127.0.0.1` or `localhost` is this machine's: Mobium reverses its port with `adb reverse` before pointing the device at it, so there is no address on the network to find and no firewall in the way. Measured on the emulator on 20…"}, {"id": "docs/PROXY.md#what-a-proxy-cannot-see", "heading": "What a proxy cannot see", "path": "docs/PROXY.md", "excerpt": "Every result names which of these applies rather than reporting an empty session as a quiet app. - **Flutter ignores the system proxy.** Dart's HTTP client reads no proxy setting unless the app gives it one, so a Flutter app's traffic goes around the proxy. - **Android apps trust only system certificates since Android 7**, unless their network security configuration opts in to user ones — debug builds usually, releas…"}], "retrieved": [{"id": "docs/guides/network.md#5-through-a-proxy", "heading": "5. Through a proxy", "path": "docs/guides/network.md", "excerpt": "`--proxy host:port` points the device's HTTP proxy at a debugging proxy — Charles, Fiddler, mitmproxy, anything that listens on a port — so it sees what the app sends and receives. A proxy on `127.0.0.1` or `localhost` is this machine's: Mobium reverses its port with `adb reverse` before pointing the device at it, so there is no address on the network to find and no firewall in the way. Measured on the emulator on 20…", "gold": true}, {"id": "docs/PROXY.md#the-shape", "heading": "The shape", "path": "docs/PROXY.md", "excerpt": "Two layers, the second opt-in. - **A proxy, any proxy.** `mobium network --proxy <host:port>` points the device at a proxy and reads it back; `--no-proxy` takes it off; the end of the session puts back what was there, as every network setting is put back. A proxy's root certificate is installed where the device allows it, so HTTPS can be decrypted. This works with Charles, Fiddler, mitmproxy or anything else that lis…", "gold": false}, {"id": "docs/PROXY.md#a-proxy-between-the-app-and-its-servers", "heading": "A proxy between the app and its servers", "path": "docs/PROXY.md", "excerpt": "What it would take for Mobium to route a device's traffic through a debugging proxy, so a test can see, shape and change what an app sends and receives — and to drive Charles, as an opt-in, the way a tester drives it by hand: record a session, throttle, switch Map Local and Rewrite rules on and off. What was measured, and the plan, in the order it should be built. **Status on 2026-10-22.** Step 1 is measured (below),…", "gold": false}, {"id": "docs/PROXY.md#what-was-measured-2026-10-20", "heading": "What was measured — 2026-10-20", "path": "docs/PROXY.md", "excerpt": "Charles 5.2.1 headless on the Mac, with a configuration of its own, and the Android 15 emulator. - **The configuration file can be written, not clicked.** Charles writes only what differs from its defaults, so its element names were read from its classes: `proxyConfiguration` holds `port`, `decryptSSL`, `sslLocations` (`locationPatterns` of `locationMatch`, each a `location` and `enabled`) and `macOSXConfiguration` w…", "gold": false}], "missed": false, "facts": ["HTTPS also needs the proxy's certificate trusted on the device; the proxy setting alone does not do it. ⟦certificate trusted⟧", "Since Android 7 apps trust only system certificates unless their network security configuration opts in to user ones (debug builds usually, release builds rarely), so their HTTPS stays encrypted. ⟦Android 7 ; network security configuration⟧", "An app with certificate pinning refuses the proxy's certificate whatever store it is in. ⟦pinning⟧"], "concern": "", "check": "Claude's reading: network.md#5 says HTTPS needs the certificate and points to PROXY.md, whose 'cannot see' section gives the trust and pinning reasons. Mobium does not install the certificate yet (PROXY.md status: 'Left of step 2: the certificate'); no code installs one, so an answer claiming Mobium installs it is wrong. Verified in: internal/device/proxy.go:69, internal/agent/network.go:112."}, {"id": "g076", "kind": "multi", "question": "My test taps a button right after a voice assistant was triggered. On an iPhone the tap just takes a few seconds longer, but on Android it fails straight away with device_not_ready. Why the difference, and how do I get past it on Android?", "tags": ["behavior", "test-author", "new since 7b590a4"], "gold": [{"id": "CHALLENGES#349", "heading": "349. A tap behind Siri's panel found nothing, and said to map again", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** measuring Siri on the iPhone 15 Plus, iOS 27.0.1, for the assistive-technology plan (`docs/ACCESSIBILITY.md`), asking only \"What time is it\" and sums. Siri's panel over MobiumApp's Form Demo stayed 8.2 to 8.3 seconds, three times in three, and while it was up `current` said SpringBoard and `map` listed neither the app nor Siri's answer: WebDriverAgent reads SpringBoard then, and the app under the panel …"}, {"id": "CHALLENGES#350", "heading": "350. A tap behind Gemini's overlay found nothing, and said to map again", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** measuring Gemini for the assistive-technology plan, after Siri's panel (349). On the Pixel 8 Pro, Android 17, signed in, the assist key opens Gemini's floating overlay from the Google app (17.66; there is no Gemini app of its own); on the Android 15 emulator, signed out, the same key opens Google Assistant's panel. While either is up, UiAutomator2 reads its window alone, the app under it absent: a tap o…"}], "retrieved": [{"id": "docs/ACCESSIBILITY.md#voiceover-on-a-real-iphone-2026-10-20", "heading": "VoiceOver on a real iPhone — 2026-10-20", "path": "docs/ACCESSIBILITY.md", "excerpt": "On the iPhone 15 Plus, iOS 27.0.1, through WebDriverAgent 16.12.8 rebuilt with Xcode 27.1, called directly over HTTP. VoiceOver was off before, and read back off after every run. - **The runner has to be built with Xcode 27.** WebDriverAgent's `/wda/voiceOver/enable`, `/disable`, `/enabled`, `/move` and `/currentSpeech` reach XCUIAutomation's VoiceOver service, which Xcode 27's has and 26.6's does not. The phone's ru…", "gold": false}, {"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": false}, {"id": "CHALLENGES#348", "heading": "348. With VoiceOver on, a tap moved its cursor and was reported done", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** measuring what WebDriverAgent's VoiceOver routes give, on the iPhone 15 Plus on iOS 27.0.1, for a plan of what Mobium could do for people who use a screen reader. With VoiceOver on, a touch is not a tap: it moves VoiceOver's cursor to what it touches, as a person's single tap does, and a double tap anywhere activates what the cursor is on. So on MobiumApp `tap \"label=Pro\"` answered `tapped label=Pro` an…", "gold": false}, {"id": "CHALLENGES#112", "heading": "112. A tap on a target sliding in gave up as it arrived", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** `docs/checks/autowait.sh`, written to test auto-wait on purpose, on its first run: on the Pixel 7 AVD, a tap on the Motion Demo's honoring target straight after Replay failed with `is still moving after 2s`. The target slides in over two seconds with an ease-out, so its last pixels creep into place right up to the end, and the settle budget was two seconds. It had never failed because it never saw the m…", "gold": false}], "missed": true, "facts": ["On iOS a target behind Siri's panel waits up to twelve seconds for the panel to go, since it closes by itself about eight seconds after Siri answers; a panel that stays is refused as device_not_ready naming Siri.", "On Android, Gemini's or Google Assistant's overlay does not go by itself, so a target behind it is refused at once, naming the assistant. ⟦refused at once⟧", "Back closes the overlay with the app intact, after which the tap lands. ⟦back closes⟧"], "concern": "", "check": "Claude's reading: CHALLENGES 349 and 350 each give one platform; handlers.go siriPanelTimeout is 12s and the assistant refusal follows at 1758. Gold is CHALLENGES-only; ACCESSIBILITY.md's Gemini section mentions back closing it but not Siri's wait. Verified in: internal/agent/handlers.go:1714, internal/agent/handlers.go:1738, internal/uitree/cover.go:430."}, {"id": "g077", "kind": "multi", "question": "If a mobium test turns TalkBack on through the accessibility screen_reader setting and takes the Android emulator offline, is the emulator left that way after the run?", "tags": ["behavior", "ci-engineer", "new since 7b590a4"], "gold": [{"id": "docs/guides/network.md#4-in-a-test", "heading": "4. In a test", "path": "docs/guides/network.md", "excerpt": "`app_network` is a step like any other in a [`mobium test`](test-runner.md) file, and its answer can be expected on: ```json { \"app\": \"dev.mobium.mobiumapp\", \"beforeEach\": [ {\"name\": \"app_network\", \"arguments\": {\"reset\": true}, \"description\": \"every test starts online and unshaped, whatever the last one left\"} ], \"tests\": [ { \"name\": \"the device goes offline, and comes back\", \"steps\": [ {\"name\": \"app_network\", \"argum…"}, {"id": "docs/ACCESSIBILITY.md#5-a-screen-reader-as-a-setting-built", "heading": "5. A screen reader as a setting — built", "path": "docs/ACCESSIBILITY.md", "excerpt": "`mobium accessibility screen_reader on` — TalkBack on Android and VoiceOver on an iPhone on iOS 27 — confirmed by reading back, and put back when the session ends, as the other settings are. It makes \"run this test with the screen reader on\" a line in a test file. As built: - **Android:** TalkBack's service added to the enabled ones, the others kept, and `accessibility_enabled` on. Confirmed by Android binding TalkBa…"}], "retrieved": [{"id": "docs/ACCESSIBILITY.md#5-a-screen-reader-as-a-setting-built", "heading": "5. A screen reader as a setting — built", "path": "docs/ACCESSIBILITY.md", "excerpt": "`mobium accessibility screen_reader on` — TalkBack on Android and VoiceOver on an iPhone on iOS 27 — confirmed by reading back, and put back when the session ends, as the other settings are. It makes \"run this test with the screen reader on\" a line in a test file. As built: - **Android:** TalkBack's service added to the enabled ones, the others kept, and `accessibility_enabled` on. Confirmed by Android binding TalkBa…", "gold": true}, {"id": "docs/ACCESSIBILITY.md#talkback-2026-10-05", "heading": "TalkBack — 2026-10-05", "path": "docs/ACCESSIBILITY.md", "excerpt": "Android's test-automation connection silenced every other accessibility service while it was open, so a read of the screen turned TalkBack off for as long as it ran. Both drivers now leave it running (CHALLENGES 208), and with TalkBack on, taps, scrolls and typing land, because Mobium's touches are injected rather than explored — the opposite of VoiceOver above. `docs/checks/screen-reader.sh` holds it. What TalkBack …", "gold": false}, {"id": "docs/SETUP.md#with-a-screen-reader-on", "heading": "With a screen reader on", "path": "docs/SETUP.md", "excerpt": "Android's test-automation connection silences every other accessibility service while it is open, unless it is opened not to. So on a device with TalkBack — or VoiceView, on a Fire TV — on, a read of the screen takes the screen reader away for as long as it runs, and an app that publishes its contents only to a screen reader stops publishing them (CHALLENGES 208). Both drivers leave the screen reader running. The def…", "gold": false}, {"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": false}, {"id": "CHALLENGES#208", "heading": "208. Every read silenced the device's screen reader", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** reading Prime Video on a Fire TV, which publishes nothing but one surface to `map`, to see whether it publishes more while Amazon's screen reader, VoiceView, is on. Every read of the screen — `uiautomator dump` and the UiAutomator2 server alike — unbound VoiceView for as long as it ran: `dumpsys accessibility` listed it before the read and not during it, and touch exploration went off. Android's test-au…", "gold": false}], "missed": false, "facts": ["No for the network: a test run ends each project's session, and the end of a session puts the network back as the session found it (airplane mode off, no shaping). ⟦as the session found it⟧", "No for TalkBack: the screen_reader setting is put back when the session ends, both keys restored exactly, and accessibility_enabled put back again once TalkBack has gone. ⟦put back when the session ends ; accessibility_enabled⟧"], "concern": "", "check": "Claude's reading: network.md section 4 covers the network restore and ACCESSIBILITY.md step 5 the TalkBack undo; code restores both at session end (restoreNetwork, restoreAccessibility). network.md still recommends a beforeEach reset to keep one test's network from reaching the next within a run. Verified in: internal/agent/network.go:295, internal/agent/accessibility.go:134, internal/device/axsettings.go:716, internal/device/axsettings.go:736."}, {"id": "g078", "kind": "multi", "question": "On Android I want every run to see my app's notification permission prompt again — even after someone tapped Don't allow twice — and have the test answer it with Allow. Which Mobium commands do that?", "tags": ["how-to", "test-author"], "gold": [{"id": "skills/mobile-check/SKILL.md#permissions", "heading": "Permissions", "path": "skills/mobile-check/SKILL.md", "excerpt": "A first-launch permission dialog will stop a flow dead. Grant before you start rather than trying to tap through it: - `mobium grant com.example.shop all` — everything the app declares - `mobium grant com.example.shop camera location` — just these - `mobium revoke com.example.shop location` — test the app without it - `mobium reset-permissions com.example.shop` — that app back to prompting, \"don't ask again\" included…"}, {"id": "skills/mobile-check/SKILL.md#dialogs", "heading": "Dialogs", "path": "skills/mobile-check/SKILL.md", "excerpt": "- `mobium alert` — is a system or app dialog up, what does it say, and what are its buttons - `mobium alert accept` / `dismiss` — yes and no, on a dialog of one or two buttons: a two-button permission prompt is granted by accept and denied by dismiss, in any language. **A dialog of three or more is refused**, naming its buttons — the location prompt has two that grant — and every answer says which button it pressed. …"}], "retrieved": [{"id": "skills/mobile-check/SKILL.md#permissions", "heading": "Permissions", "path": "skills/mobile-check/SKILL.md", "excerpt": "A first-launch permission dialog will stop a flow dead. Grant before you start rather than trying to tap through it: - `mobium grant com.example.shop all` — everything the app declares - `mobium grant com.example.shop camera location` — just these - `mobium revoke com.example.shop location` — test the app without it - `mobium reset-permissions com.example.shop` — that app back to prompting, \"don't ask again\" included…", "gold": true}, {"id": "CHALLENGES#findings-that-were-not-defects", "heading": "Findings that were not defects", "path": "docs/CHALLENGES.md", "excerpt": "Worth recording because each one closed off an approach that looked obvious. - **Predictive back on Android 15 closes a React Native app.** MobiumApp built with predictive back turned on went back to closing on every back from a demo on the Android 15 AVD, `BackHandler` never called, while on Android 17 — the AVD and the Pixel 8 Pro — it went back to its home screen. React Native 0.86 registers the callback that repl…", "gold": false}, {"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": false}, {"id": "CHALLENGES#151", "heading": "151. A per-app permission reset that could not see what it failed to clear", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** running `mobium-app.sh` after `dialogs.sh` on the Pixel 7 AVD, the first time both reset MobiumApp's permissions alone. The location check failed: the app had approximate location only, and the reset had said it put every permission back to asking. Android prints a permission flag it has no name for as a number, and after a person chooses approximate location the line ends `|524288]`. The pattern read t…", "gold": false}, {"id": "CHALLENGES#328", "heading": "328. A dialog that came up mid-scroll was blamed on the list", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** turning a client script's trace back into a test (the round-trip probe, mobiumdev/mobium-roundtrip), on the Android 15 emulator. MobiumApp's Dialog Demo asks for the camera; Android's prompt comes a moment after the tap, and only while the permission is undecided. A test that declared a rule for the prompt — `when` \"take pictures\", `press` \"While using the app\" — then scrolled up to the outcome line fai…", "gold": false}], "missed": false, "facts": ["`mobium reset-permissions <app>` puts that app back to prompting, \"don't ask again\" included. ⟦reset-permissions ; ask again⟧", "`mobium alert accept` answers a two-button permission prompt with yes, granting it, in any language. ⟦alert accept⟧"], "concern": "", "check": "Claude's reading: SKILL.md's Permissions and Dialogs sections each give one half; permreset.go revokes and clears USER_SET/USER_FIXED, and alert accept presses the yes button on a dialog of two. The tool description adds that revoking a granted permission on Android stops the app — not in the gold, not needed. Verified in: internal/agent/permissions.go:350, internal/device/permreset.go:112, internal/agent/alert.go:212, internal/agent/alert.go:429."}, {"id": "g079", "kind": "unanswerable", "question": "How much does a Charles license cost if I want to use it with Mobium's proxy support?", "tags": ["test-author", "new since 7b590a4"], "gold": [], "retrieved": [{"id": "docs/PROXY.md#4-charles-as-an-opt-in", "heading": "4. Charles as an opt-in", "path": "docs/PROXY.md", "excerpt": "`--proxy charles`: headless start with a configuration Mobium writes — the macOS proxy off, the Web Interface on, Auto Save into the test's report folder — or an existing Charles found; recording, throttling and tool switches through the Web Interface, each read back from its status line; the session converted to HAR beside the test's report. Listening on every interface is said, or bound where Charles allows.", "gold": false}, {"id": "docs/PROXY.md#the-shape", "heading": "The shape", "path": "docs/PROXY.md", "excerpt": "Two layers, the second opt-in. - **A proxy, any proxy.** `mobium network --proxy <host:port>` points the device at a proxy and reads it back; `--no-proxy` takes it off; the end of the session puts back what was there, as every network setting is put back. A proxy's root certificate is installed where the device allows it, so HTTPS can be decrypted. This works with Charles, Fiddler, mitmproxy or anything else that lis…", "gold": false}, {"id": "docs/PROXY.md#a-proxy-between-the-app-and-its-servers", "heading": "A proxy between the app and its servers", "path": "docs/PROXY.md", "excerpt": "What it would take for Mobium to route a device's traffic through a debugging proxy, so a test can see, shape and change what an app sends and receives — and to drive Charles, as an opt-in, the way a tester drives it by hand: record a session, throttle, switch Map Local and Rewrite rules on and off. What was measured, and the plan, in the order it should be built. **Status on 2026-10-22.** Step 1 is measured (below),…", "gold": false}, {"id": "docs/PROXY.md#what-was-measured-2026-10-20", "heading": "What was measured — 2026-10-20", "path": "docs/PROXY.md", "excerpt": "Charles 5.2.1 headless on the Mac, with a configuration of its own, and the Android 15 emulator. - **The configuration file can be written, not clicked.** Charles writes only what differs from its defaults, so its element names were read from its classes: `proxyConfiguration` holds `port`, `decryptSSL`, `sslLocations` (`locationPatterns` of `locationMatch`, each a `location` and `enabled`) and `macOSXConfiguration` w…", "gold": false}, {"id": "docs/PROXY.md#2---proxy-on-android", "heading": "2. `--proxy` on Android", "path": "docs/PROXY.md", "excerpt": "**The setting, done 2026-10-22** (`docs/guides/network.md`, section 5): set, read back from the keys in force, taken off with `:0` and every key deleted, put back at the session's end; a loopback proxy's port reversed before the device points at it, and only Mobium's reverses removed. A reverse that was there before is left — a test caught the first version taking it as its own. `proxy.sh` fetches a port nothing on t…", "gold": false}], "missed": false, "facts": [], "concern": "", "check": "Claude's reading: searched the corpus and code for license, price and subscription: PROXY.md only says Charles is never installed or required, mitmproxy needs no license and Fiddler Everywhere is by subscription; no price is stated anywhere. Nearest sections: docs/PROXY.md#4-charles-as-an-opt-in, docs/PROXY.md#6-fiddler-and-mitmproxy."}, {"id": "g080", "kind": "unanswerable", "question": "How do I make the Android emulator drop 5% of packets with `mobium network`, to test a flaky connection?", "tags": ["test-author"], "gold": [], "retrieved": [{"id": "docs/checks/README.md#running-several-at-once", "heading": "Running several at once", "path": "docs/checks/README.md", "excerpt": "Every check sources [lib.sh](lib.sh), which keeps it from reaching into another: - **A daemon of its own** (`MOBIUM_SESSION`), stopped when the check ends. Checks once shared one: a check that ended on the `uiautomator` backend handed it to every check after, and one run's `daemon stop` ended another device's trace. A session the caller set, as a grid run's or `mobium test`'s, is kept. - **One check per device.** `ch…", "gold": false}, {"id": "docs/guides/network.md#4-in-a-test", "heading": "4. In a test", "path": "docs/guides/network.md", "excerpt": "`app_network` is a step like any other in a [`mobium test`](test-runner.md) file, and its answer can be expected on: ```json { \"app\": \"dev.mobium.mobiumapp\", \"beforeEach\": [ {\"name\": \"app_network\", \"arguments\": {\"reset\": true}, \"description\": \"every test starts online and unshaped, whatever the last one left\"} ], \"tests\": [ { \"name\": \"the device goes offline, and comes back\", \"steps\": [ {\"name\": \"app_network\", \"argum…", "gold": false}, {"id": "docs/guides/graybox-tutorial.md#2-it-fails", "heading": "2. It fails", "path": "docs/guides/graybox-tutorial.md", "excerpt": "``` $ mobium test FAIL [android · emulator-5554] busy.test.json › a row tapped after a quiet refresh is current (1) (6.9s) step 3 (app_wait_for): [timeout] step 3 of 3 (app_wait_for) failed: timed out after 3.003s waiting for testid=busyOutcome to contain \": current\" — its text is \"row B, generation 1: stale\"; steps 1-2 ran before it, and nothing after FAIL [android · emulator-5554] busy.test.json › a row tapped afte…", "gold": false}, {"id": "docs/guides/network.md#why-not-the-emulators-own-throttling", "heading": "Why not the emulator's own throttling", "path": "docs/guides/network.md", "excerpt": "The Android emulator's console has `network speed` and `network delay`, and they look made for this. They accept a setting and read it back — and change nothing: on emulator 37.1.11, 2MB at a 1000 kbit/s limit still arrived in 1.1 seconds where 16 were due, and a 500ms delay left a ping at 1ms. So Mobium does not use them; it shapes the traffic itself, and every figure above was measured from the traffic, not the set…", "gold": false}, {"id": "docs/guides/graybox-tutorial.md#4-turning-the-gray-box-on", "heading": "4. Turning the gray box on", "path": "docs/guides/graybox-tutorial.md", "excerpt": "One key in the test file, beside `app`: ```json { \"app\": \"dev.mobium.mobiumapp\", \"grayBox\": true, \"beforeEach\": [ ``` Each test's launch now turns the library on, and every step waits for the app to say it is idle before finding its target: ``` $ mobium test ok [android · emulator-5554] busy.test.json › a row tapped after a quiet refresh is current (1) (7s) ok [android · emulator-5554] busy.test.json › a row tapped a…", "gold": false}], "missed": false, "facts": [], "concern": "", "check": "Claude's reading: mobium network has offline/online, latency, download, upload, proxy, no-proxy and reset (cmd/mobium/network.go:71-78) and the tc shaping in device/network.go uses netem delay and token buckets only; no doc or code mentions packet loss. A retriever will bring back the slow-network and commands sections. Nearest sections: docs/guides/network.md#3-a-slow-network, docs/guides/network.md#the-commands."}, {"id": "g081", "kind": "fact", "question": "I use Claude Code. How do I give my agent Mobium's tools, and make iOS the platform it drives by default?", "tags": ["how-to", "agent-builder"], "gold": [{"id": "docs/guides/mcp.md#1-connect-it", "heading": "1. Connect it", "path": "docs/guides/mcp.md", "excerpt": "In Claude Code: ```sh claude mcp add mobium -- mobium mcp ``` With more than one device, pin one — `mobium mcp --device emulator-5554` — or let the agent pass `device` to each call. `--driver wda` makes iOS the default. Other MCP clients take the same server in their JSON configuration, under `mcpServers`: ```json { \"mcpServers\": { \"mobium\": { \"command\": \"mobium\", \"args\": [\"mcp\", \"--device\", \"emulator-5554\"] } } } ``…"}], "retrieved": [{"id": "docs/guides/mcp.md#1-connect-it", "heading": "1. Connect it", "path": "docs/guides/mcp.md", "excerpt": "In Claude Code: ```sh claude mcp add mobium -- mobium mcp ``` With more than one device, pin one — `mobium mcp --device emulator-5554` — or let the agent pass `device` to each call. `--driver wda` makes iOS the default. Other MCP clients take the same server in their JSON configuration, under `mcpServers`: ```json { \"mcpServers\": { \"mobium\": { \"command\": \"mobium\", \"args\": [\"mcp\", \"--device\", \"emulator-5554\"] } } } ``…", "gold": true}, {"id": "docs/guides/mcp.md#2-an-agent-at-work", "heading": "2. An agent at work", "path": "docs/guides/mcp.md", "excerpt": "Claude Code, non-interactively, with Mobium's server and nothing else allowed: ```sh claude -p \"Use the mobium tools. On the Android emulator, open the app dev.mobium.mobiumapp, go to its Login Demo, sign in with username mobium and password wrongpass1, and tell me exactly what the app says. Keep it short.\" \\ --mcp-config mobium.json --strict-mcp-config --allowedTools mcp__mobium ``` The calls it made, in order, each…", "gold": false}, {"id": "docs/guides/mcp.md#mcp-mobium-as-an-agents-tools", "heading": "MCP: Mobium as an agent's tools", "path": "docs/guides/mcp.md", "excerpt": "`mobium mcp` serves every one of Mobium's tools over the Model Context Protocol, on stdio, so an agent — Claude Code, or any MCP client — drives devices with the same tools the command line and the language clients use. This guide is how to connect one, what it sees, and how its answers and failures come back. Everything below is what ran on 2026-09-28 against [MobiumApp](https://github.com/mobiumdev/mobium-app) on a…", "gold": false}, {"id": "docs/quickstart/mcp.md#1-what-you-need", "heading": "1. What you need", "path": "docs/quickstart/mcp.md", "excerpt": "An agent that speaks MCP — Claude Code, or any MCP client — to drive devices with Mobium's tools. The program on this page plays the client's part by hand, to show exactly what goes over the wire; it needs Python 3.9 or later and nothing beyond its standard library.", "gold": false}, {"id": "CLAUDE.md#rules", "heading": "Rules", "path": "CLAUDE.md", "excerpt": "- Run `make ci` before committing. After adding a tool, a flag or a schema property, run `make api flags` and add it everywhere — CLI, MCP schema, all five clients (CONTRIBUTING.md, \"Adding a tool, a flag or an error\") - Every error has a code: `mobiumerr.New(mobiumerr.<Code>, ...)`, never a bare `fmt.Errorf` - The CLI implements no behavior; it calls a tool. Behavior lives in `internal/agent` - After rebuilding, `mo…", "gold": false}], "missed": false, "facts": ["Register the server with `claude mcp add mobium -- mobium mcp`. ⟦claude mcp add mobium⟧", "Passing `--driver wda` to `mobium mcp` makes iOS the default. ⟦--driver wda⟧"], "concern": "", "check": "Claude's reading: the command and the --driver flag are in the MCP guide's section 1; mcp_cmd.go's help text names the same registration, and it passes the global --driver to SetBackend, so `mobium mcp --driver wda` sets the server's default backend. Verified in: cmd/mobium/mcp_cmd.go:17, cmd/mobium/mcp_cmd.go:29."}, {"id": "g082", "kind": "fact", "question": "I put Mobium into my desktop MCP client's mcpServers config with \"command\": \"mobium\", but the server never starts, even though mobium runs fine in my terminal. What is wrong?", "tags": ["troubleshooting", "agent-builder"], "gold": [{"id": "docs/guides/mcp.md#1-connect-it", "heading": "1. Connect it", "path": "docs/guides/mcp.md", "excerpt": "In Claude Code: ```sh claude mcp add mobium -- mobium mcp ``` With more than one device, pin one — `mobium mcp --device emulator-5554` — or let the agent pass `device` to each call. `--driver wda` makes iOS the default. Other MCP clients take the same server in their JSON configuration, under `mcpServers`: ```json { \"mcpServers\": { \"mobium\": { \"command\": \"mobium\", \"args\": [\"mcp\", \"--device\", \"emulator-5554\"] } } } ``…"}], "retrieved": [{"id": "docs/guides/mcp.md#1-connect-it", "heading": "1. Connect it", "path": "docs/guides/mcp.md", "excerpt": "In Claude Code: ```sh claude mcp add mobium -- mobium mcp ``` With more than one device, pin one — `mobium mcp --device emulator-5554` — or let the agent pass `device` to each call. `--driver wda` makes iOS the default. Other MCP clients take the same server in their JSON configuration, under `mcpServers`: ```json { \"mcpServers\": { \"mobium\": { \"command\": \"mobium\", \"args\": [\"mcp\", \"--device\", \"emulator-5554\"] } } } ``…", "gold": true}, {"id": "docs/quickstart/mcp.md#2-connect-an-agent", "heading": "2. Connect an agent", "path": "docs/quickstart/mcp.md", "excerpt": "`mobium mcp` is an MCP server on stdio, so there is nothing to install beyond `mobium` itself. Register it with your agent — in Claude Code: ```sh claude mcp add mobium -- mobium mcp ``` Other clients take the same command in their `mcpServers` configuration; [the MCP guide](../guides/mcp.md#1-connect-it) has the JSON. From then on, ask the agent for what you want done on the device, and it calls the tools below itse…", "gold": false}, {"id": "packaging/mcp/README.md#mcp-packaging", "heading": "MCP packaging", "path": "packaging/mcp/README.md", "excerpt": "What puts Mobium's MCP server — `mobium mcp` — into the [MCP Registry](https://registry.modelcontextprotocol.io) and into clients that install MCP bundles, such as Claude Desktop. | File | What it is | | --- | --- | | [manifest.json](manifest.json) | The MCPB manifest, a template: the version and the tool list are filled in at build time | | [launcher.sh](launcher.sh) | The bundle's entry point, `server/mobium`: a bu…", "gold": false}, {"id": "docs/guides/mcp.md#6-sessions-and-sharing-a-device", "heading": "6. Sessions, and sharing a device", "path": "docs/guides/mcp.md", "excerpt": "`mobium mcp` runs the tools in its own process: the editor's MCP connection is the long-lived thing, and it holds its own device sessions, with the agent's refs. The command line and the language clients share a daemon instead. A device's automation server holds one session at a time, so an agent's MCP server and a `mobium` command driving **the same device at the same time** take it from each other — each recovers, …", "gold": false}, {"id": "docs/guides/mcp.md#mcp-mobium-as-an-agents-tools", "heading": "MCP: Mobium as an agent's tools", "path": "docs/guides/mcp.md", "excerpt": "`mobium mcp` serves every one of Mobium's tools over the Model Context Protocol, on stdio, so an agent — Claude Code, or any MCP client — drives devices with the same tools the command line and the language clients use. This guide is how to connect one, what it sees, and how its answers and failures come back. Everything below is what ran on 2026-09-28 against [MobiumApp](https://github.com/mobiumdev/mobium-app) on a…", "gold": false}], "missed": false, "facts": ["The client starts the server with its own PATH, so `command` needs mobium's full path when mobium is not on the PATH the client starts with. ⟦full path⟧"], "concern": "", "check": "Claude's reading: the guide's section 1 says `command` needs mobium's full path if it is not on the PATH the client starts with; nothing in Mobium's code is involved, since the client launches the process, so verified_in only points at the command being launched. Verified in: cmd/mobium/mcp_cmd.go:11."}, {"id": "g083", "kind": "fact", "question": "When one of Mobium's tools fails over MCP, does my client get a JSON-RPC error, and what in the reply should my agent decide on?", "tags": ["behavior", "agent-builder"], "gold": [{"id": "docs/guides/mcp.md#5-failures", "heading": "5. Failures", "path": "docs/guides/mcp.md", "excerpt": "A tool that fails answers with `isError: true` — never a protocol error, which is kept for a malformed request — and the failure as data: a code, the message, a remedy that works, and whether retrying could help: ``` >>> {\"jsonrpc\": \"2.0\", \"id\": 5, \"method\": \"tools/call\", \"params\": {\"name\": \"app_tap\", \"arguments\": {\"target\": \"testid=noSuchButton\"}}} <<< { \"jsonrpc\": \"2.0\", \"id\": 5, \"result\": { \"content\": [ { \"type\": …"}], "retrieved": [{"id": "CHALLENGES#121", "heading": "121. The clients hung, crashed and leaked on an ordinary bad day", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** driving each client's real connection against a stand-in `mobium pipe` on a real subprocess, before the .NET, Java, Python and JavaScript clients went public, and then checking the one case that mattered most against the real pipe. Nothing here needed a device; all of it would have reached users. Five clients, written against one protocol, each had its own subset:", "gold": false}, {"id": "docs/quickstart/mcp.md#notes", "heading": "Notes", "path": "docs/quickstart/mcp.md", "excerpt": "- The server holds one session per device for as long as it runs. An agent's client ends it by closing the server's stdin when the agent exits, which also puts back anything the session changed. - A tool that fails answers with `isError` and a code in `structuredContent`, never a JSON-RPC error: the agent reads the explanation and decides what to do. [The MCP guide](../guides/mcp.md) shows an agent at work, the hands…", "gold": false}, {"id": "docs/guides/mcp.md#mcp-mobium-as-an-agents-tools", "heading": "MCP: Mobium as an agent's tools", "path": "docs/guides/mcp.md", "excerpt": "`mobium mcp` serves every one of Mobium's tools over the Model Context Protocol, on stdio, so an agent — Claude Code, or any MCP client — drives devices with the same tools the command line and the language clients use. This guide is how to connect one, what it sees, and how its answers and failures come back. Everything below is what ran on 2026-09-28 against [MobiumApp](https://github.com/mobiumdev/mobium-app) on a…", "gold": false}, {"id": "CHALLENGES#91", "heading": "91. Every client raised its base exception for every failure", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** `docs/checks/clients.sh`, the first end-to-end run of all five clients against a device, written for the release checklist on 2026-09-25. Its one deliberate failure — a tap on a locator that matches nothing — came back as `MobiumError`, `MobiumException` and a bare Go error in all five, never as the `no_such_element` type each client maps that code to. The code never reached them. Clients spawn `mobium …", "gold": false}, {"id": "CONTRIBUTING.md#adding-a-tool-a-flag-or-an-error", "heading": "Adding a tool, a flag or an error", "path": "CONTRIBUTING.md", "excerpt": "- **A tool** goes everywhere at once: the CLI, the MCP schema and all five clients. `internal/apisurface` fails the build otherwise; a deliberate gap is declared there with a reason. Run `make api` to regenerate [docs/API.md](docs/API.md). - **A flag or schema property** is the same rule one level down: every argument a tool declares must be settable from the CLI, and every key a command sends must be one the tool de…", "gold": false}], "missed": true, "facts": ["A failed tool answers with a normal result marked `isError: true`, never a protocol error, which is kept for a malformed request. ⟦isError⟧", "The structured half carries a code, the message, a remedy and whether retrying could help; the agent should decide by the code and read the remedy. ⟦retryable⟧"], "concern": "", "check": "Claude's reading: server.go's CallTool returns ErrorResult (isError true, structuredContent from mobiumerr.PayloadOf) for any tool failure and a JSON-RPC error only for unparseable params, as the guide's section 5 says. Verified in: internal/agent/server.go:163, internal/agent/server.go:188, internal/mobiumerr/mobiumerr.go:183."}, {"id": "g084", "kind": "fact", "question": "Why does `mobium mcp` run the tools inside its own process instead of going through the daemon the way the language clients do?", "tags": ["rationale", "contributor"], "gold": [{"id": "docs/ARCHITECTURE.md#the-whole-system", "heading": "The whole system", "path": "docs/ARCHITECTURE.md", "excerpt": "```mermaid flowchart TB subgraph doors[\"Front doors\"] cli[\"CLI<br/>mobium map, mobium tap @e5\"] clients[\"Language clients<br/>Python · JavaScript · Go · Java · .NET\"] mcp[\"MCP client<br/>an agent\"] test[\"mobium test<br/>JSON test files · --ui page\"] inspect[\"mobium inspect<br/>a page showing the screen\"] end pipe[\"mobium pipe<br/>JSON-RPC on stdio\"] mcpcmd[\"mobium mcp<br/>MCP on stdio, in-process\"] daemon[\"Daemon<br/…"}], "retrieved": [{"id": "docs/guides/mcp.md#6-sessions-and-sharing-a-device", "heading": "6. Sessions, and sharing a device", "path": "docs/guides/mcp.md", "excerpt": "`mobium mcp` runs the tools in its own process: the editor's MCP connection is the long-lived thing, and it holds its own device sessions, with the agent's refs. The command line and the language clients share a daemon instead. A device's automation server holds one session at a time, so an agent's MCP server and a `mobium` command driving **the same device at the same time** take it from each other — each recovers, …", "gold": false}, {"id": "docs/guides/mcp.md#which-front-door", "heading": "Which front door", "path": "docs/guides/mcp.md", "excerpt": "| | Command line | MCP | Language clients | | --- | --- | --- | --- | | For | a person, a shell script, CI | an agent | a program or a test suite | | Runs as | `mobium <command>` through the daemon | `mobium mcp`, in its own process | `mobium pipe`, spawned by the client, through the daemon | | Answers | text, or `--json` | `content` and `structuredContent` | typed results and exceptions | The same 71 tools behind ea…", "gold": false}, {"id": "CHALLENGES#7", "heading": "7. Client sessions collided with the CLI's", "path": "docs/CHALLENGES.md", "excerpt": "**Step 6. Found by:** running the first Python client against a live device. The client spawned `mobium mcp`, which runs handlers in-process. That started a second UiAutomator2 instrumentation on the same device, took over the device-side server, and left the daemon holding a session id the server no longer knew. Both UiAutomator2 and WebDriverAgent hold exactly **one session per device**. Fixed by adding `mobium pip…", "gold": false}, {"id": "docs/guides/cli.md#the-command-line", "heading": "The command line", "path": "docs/guides/cli.md", "excerpt": "`mobium` is one binary, and every command is one call to one of Mobium's tools — the same tools an MCP client and the five language clients call, so the command line cannot do something they cannot. This guide is how the commands fit together: the loop, sessions and the daemon, the flags every command takes, reading answers from a script, and exit statuses. Every command and every line of output below is what `mobium…", "gold": false}, {"id": "docs/guides/mcp.md#mcp-mobium-as-an-agents-tools", "heading": "MCP: Mobium as an agent's tools", "path": "docs/guides/mcp.md", "excerpt": "`mobium mcp` serves every one of Mobium's tools over the Model Context Protocol, on stdio, so an agent — Claude Code, or any MCP client — drives devices with the same tools the command line and the language clients use. This guide is how to connect one, what it sees, and how its answers and failures come back. Everything below is what ran on 2026-09-28 against [MobiumApp](https://github.com/mobiumdev/mobium-app) on a…", "gold": false}], "missed": true, "facts": ["The MCP server runs the tool layer in-process because an MCP client already holds a long-lived connection of its own. ⟦long-lived connection⟧", "The clients go through the daemon (via `mobium pipe`) because a device-side server holds one session at a time, so a client with its own session would invalidate the CLI's. ⟦one session at a time ; mobium pipe⟧"], "concern": "", "check": "Claude's reading: both reasons are the bullets under ARCHITECTURE's diagram (part ~2 of the section); mcp_cmd.go's comment gives the same reason for running agent.NewServer in-process. Verified in: cmd/mobium/mcp_cmd.go:22, cmd/mobium/pipe.go."}, {"id": "g085", "kind": "fact", "question": "What happens if my agent's MCP server and a `mobium` command in my terminal drive the same phone at the same time?", "tags": ["behavior", "agent-builder"], "gold": [{"id": "docs/guides/mcp.md#6-sessions-and-sharing-a-device", "heading": "6. Sessions, and sharing a device", "path": "docs/guides/mcp.md", "excerpt": "`mobium mcp` runs the tools in its own process: the editor's MCP connection is the long-lived thing, and it holds its own device sessions, with the agent's refs. The command line and the language clients share a daemon instead. A device's automation server holds one session at a time, so an agent's MCP server and a `mobium` command driving **the same device at the same time** take it from each other — each recovers, …"}], "retrieved": [{"id": "docs/guides/mcp.md#6-sessions-and-sharing-a-device", "heading": "6. Sessions, and sharing a device", "path": "docs/guides/mcp.md", "excerpt": "`mobium mcp` runs the tools in its own process: the editor's MCP connection is the long-lived thing, and it holds its own device sessions, with the agent's refs. The command line and the language clients share a daemon instead. A device's automation server holds one session at a time, so an agent's MCP server and a `mobium` command driving **the same device at the same time** take it from each other — each recovers, …", "gold": true}, {"id": "docs/quickstart/mcp.md#2-connect-an-agent", "heading": "2. Connect an agent", "path": "docs/quickstart/mcp.md", "excerpt": "`mobium mcp` is an MCP server on stdio, so there is nothing to install beyond `mobium` itself. Register it with your agent — in Claude Code: ```sh claude mcp add mobium -- mobium mcp ``` Other clients take the same command in their `mcpServers` configuration; [the MCP guide](../guides/mcp.md#1-connect-it) has the JSON. From then on, ask the agent for what you want done on the device, and it calls the tools below itse…", "gold": false}, {"id": "docs/guides/mcp.md#1-connect-it", "heading": "1. Connect it", "path": "docs/guides/mcp.md", "excerpt": "In Claude Code: ```sh claude mcp add mobium -- mobium mcp ``` With more than one device, pin one — `mobium mcp --device emulator-5554` — or let the agent pass `device` to each call. `--driver wda` makes iOS the default. Other MCP clients take the same server in their JSON configuration, under `mcpServers`: ```json { \"mcpServers\": { \"mobium\": { \"command\": \"mobium\", \"args\": [\"mcp\", \"--device\", \"emulator-5554\"] } } } ``…", "gold": false}, {"id": "docs/guides/mcp.md#mcp-mobium-as-an-agents-tools", "heading": "MCP: Mobium as an agent's tools", "path": "docs/guides/mcp.md", "excerpt": "`mobium mcp` serves every one of Mobium's tools over the Model Context Protocol, on stdio, so an agent — Claude Code, or any MCP client — drives devices with the same tools the command line and the language clients use. This guide is how to connect one, what it sees, and how its answers and failures come back. Everything below is what ran on 2026-09-28 against [MobiumApp](https://github.com/mobiumdev/mobium-app) on a…", "gold": false}, {"id": "README.md#front-doors", "heading": "Front doors", "path": "README.md", "excerpt": "The CLI does not implement behavior. It calls the same tools an MCP client calls, so the surfaces cannot drift: ```mermaid flowchart LR cli[\"CLI\"] --> daemon clients[\"Python · JS · Go · Java · .NET\"] --> pipe[\"mobium pipe\"] --> daemon mcp[\"MCP client\"] --> mcpcmd[\"mobium mcp\"] daemon[\"daemon<br/>sessions, @refs\"] --> agent mcpcmd --> agent[\"internal/agent<br/>every tool, written once\"] agent --> driver[\"internal/mobi…", "gold": false}], "missed": false, "facts": ["A device's automation server holds one session at a time, so the two take it from each other; each recovers, but neither is reliable. ⟦one session at a time⟧", "Give each its own device, or take turns. ⟦take turns⟧"], "concern": "", "check": "Claude's reading: section 6 of the MCP guide states this; the code confirms the MCP server keeps its own sessions in-process (mcp_cmd.go) while the CLI's are in the daemon, so nothing arbitrates between them. The collision itself is a device-side fact I did not reproduce. Verified in: cmd/mobium/mcp_cmd.go:22, internal/agent/session.go."}, {"id": "g086", "kind": "fact", "question": "I wrote a driver script, and `mobium map --driver mything` answers that there is no built-in backend by that name. How does Mobium look for third-party drivers?", "tags": ["troubleshooting", "driver-author"], "gold": [{"id": "examples/drivers/PROTOCOL.md#discovery", "heading": "Discovery", "path": "examples/drivers/PROTOCOL.md", "excerpt": "`--driver roku` looks for a built-in backend of that name first, then for an executable named **`mobium-driver-roku`** on `PATH`. Git and kubectl both do this, it needs no registry, no config file and no install step beyond putting a file somewhere, and it makes the failure legible: \"no built-in backend named roku, and no `mobium-driver-roku` on your PATH\". `MOBIUM_DRIVER_<NAME>` overrides the path for one backend, w…"}], "retrieved": [{"id": "examples/drivers/README.md#the-smallest-driver-that-works", "heading": "The smallest driver that works", "path": "examples/drivers/README.md", "excerpt": "Three methods are mandatory: `snapshot`, `screenshot` and `tap`. Plus `initialize`, which says who you are. ```python #!/usr/bin/env python3 import json, sys def handle(method, params): if method == \"initialize\": return {\"protocolVersion\": \"1\", \"name\": \"my-thing\", \"capabilities\": []} if method == \"snapshot\": return {\"class\": \"Screen\", \"bounds\": [0, 0, 400, 800], \"children\": [ {\"class\": \"Button\", \"text\": \"Go\", \"bounds…", "gold": false}, {"id": "examples/drivers/PROTOCOL.md#discovery", "heading": "Discovery", "path": "examples/drivers/PROTOCOL.md", "excerpt": "`--driver roku` looks for a built-in backend of that name first, then for an executable named **`mobium-driver-roku`** on `PATH`. Git and kubectl both do this, it needs no registry, no config file and no install step beyond putting a file somewhere, and it makes the failure legible: \"no built-in backend named roku, and no `mobium-driver-roku` on your PATH\". `MOBIUM_DRIVER_<NAME>` overrides the path for one backend, w…", "gold": true}, {"id": "examples/drivers/README.md#developing-without-installing", "heading": "Developing without installing", "path": "examples/drivers/README.md", "excerpt": "``` MOBIUM_DRIVER_MYTHING=./mobium-driver-mything mobium map --driver mything ``` `mobium doctor` lists every `mobium-driver-*` it can find on your `PATH`, so \"did it install\" has an answer that is not \"run it and see\".", "gold": false}, {"id": "examples/drivers/README.md#the-reference-driver", "heading": "The reference driver", "path": "examples/drivers/README.md", "excerpt": "[`mobium-driver-adb`](mobium-driver-adb) is a complete, working driver in ~350 lines of Python with no dependencies. It drives Android through plain `adb` — deliberately the same ground Mobium's own `--driver uiautomator` covers, so its output can be diffed against a known-good implementation on the same screen. That diff is how you tell a driver that works from one that returns something plausible, and it is exactly…", "gold": false}, {"id": "README.md#drivers-for-other-platforms", "heading": "Drivers for other platforms", "path": "README.md", "excerpt": "Anything Mobium does not drive itself — a TV, a desktop app, a platform nobody has written yet — is a **driver**: an executable named `mobium-driver-<name>` on your `PATH`, in any language, speaking JSON-RPC on stdio. ```sh mobium map --driver roku ``` A driver needs three methods to be useful — `snapshot`, `screenshot` and `tap` — and inherits locators, `@ref`s, waiting, scrolling, the CLI, MCP and all five clients.…", "gold": false}], "missed": false, "facts": ["`--driver mything` looks for a built-in backend first, then for an executable named `mobium-driver-mything` on PATH. ⟦mobium-driver-⟧", "`MOBIUM_DRIVER_<NAME>` overrides the path for one backend, for developing a driver without installing it. ⟦MOBIUM_DRIVER_⟧", "`mobium doctor` lists the drivers it can find. ⟦mobium doctor⟧"], "concern": "internal/mobiumdriver/external.go:116-121: the refusal says that after setting MOBIUM_DRIVER_<NAME> you must run `mobium daemon stop`, because the daemon is what looks for drivers and a running one keeps the environment it started with. Neither PROTOCOL.md#discovery nor README.md#developing-without-installing says so, so following the docs with a daemon already running still fails.", "check": "Claude's reading: FindDriver checks MOBIUM_DRIVER_<NAME> (dashes and dots become underscores), then exec.LookPath(\"mobium-driver-\"+name), and refuses with the message the docs quote. See the concern: the code's refusal adds a step the docs leave out. Verified in: internal/mobiumdriver/external.go:102, internal/mobiumdriver/external.go:106, internal/mobiumdriver/external.go:114."}, {"id": "g087", "kind": "fact", "question": "My third-party driver leaves `text` out of its capabilities. What happens when someone runs `mobium type` against it?", "tags": ["behavior", "driver-author"], "gold": [{"id": "examples/drivers/PROTOCOL.md#handshake", "heading": "Handshake", "path": "examples/drivers/PROTOCOL.md", "excerpt": "Mobium calls `initialize` first and sends nothing else until it answers: ```json {\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\", \"params\":{\"protocolVersion\":\"1\",\"device\":\"<the --device string, verbatim>\"}} ``` The driver replies with its name and what it can do: ```json {\"jsonrpc\":\"2.0\",\"id\":1,\"result\":{ \"protocolVersion\":\"1\", \"name\":\"roku/ecp\", \"capabilities\":[\"gestures\",\"text\",\"apps\",\"appearance\",\"inventory\", \"permi…"}], "retrieved": [{"id": "skills/mobile-check/SKILL.md#choosing-a-device-or-backend", "heading": "Choosing a device or backend", "path": "skills/mobile-check/SKILL.md", "excerpt": "- `--device <serial>` — when more than one device is running - `--driver uiautomator` — Android without installing anything (slower, and it cannot type) - `--driver wda` — iOS simulators and iPhones - `--driver <anything else>` — a third-party driver the user installed, as an executable named `mobium-driver-<name>`. `mobium doctor` lists the ones it can find. Such a driver may not support everything: if it refuses so…", "gold": false}, {"id": "docs/RELEASE-CHECKLIST.md#third-party-drivers", "heading": "Third-party drivers", "path": "docs/RELEASE-CHECKLIST.md", "excerpt": "The extension point is a published protocol, so a break here is a break in somebody else's code that we cannot see. - [ ] `examples/drivers/mobium-driver-adb` still imports nothing but the Python standard library. If a reference driver needs anything from this repository, the extension point is not open - [ ] `examples/drivers/PROTOCOL.md`'s method table matches what `internal/mobiumdriver` actually sends, field for …", "gold": false}, {"id": "examples/drivers/README.md#the-reference-driver", "heading": "The reference driver", "path": "examples/drivers/README.md", "excerpt": "[`mobium-driver-adb`](mobium-driver-adb) is a complete, working driver in ~350 lines of Python with no dependencies. It drives Android through plain `adb` — deliberately the same ground Mobium's own `--driver uiautomator` covers, so its output can be diffed against a known-good implementation on the same screen. That diff is how you tell a driver that works from one that returns something plausible, and it is exactly…", "gold": false}, {"id": "examples/drivers/PROTOCOL.md#handshake", "heading": "Handshake", "path": "examples/drivers/PROTOCOL.md", "excerpt": "Mobium calls `initialize` first and sends nothing else until it answers: ```json {\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\", \"params\":{\"protocolVersion\":\"1\",\"device\":\"<the --device string, verbatim>\"}} ``` The driver replies with its name and what it can do: ```json {\"jsonrpc\":\"2.0\",\"id\":1,\"result\":{ \"protocolVersion\":\"1\", \"name\":\"roku/ecp\", \"capabilities\":[\"gestures\",\"text\",\"apps\",\"appearance\",\"inventory\", \"permi…", "gold": true}, {"id": "CHALLENGES#92", "heading": "92. The advice for a missing driver could not work with a daemon running", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** `docs/checks/external-driver.sh` in the release batch, which failed at once with \"no mobium-driver-adb on your PATH\" — while exporting `MOBIUM_DRIVER_ADB` three lines earlier. The daemon looks a driver up, in the environment it started with; one left running by an earlier command never sees a variable set afterwards. The check had always been run first, on a fresh daemon. And the product's error gave th…", "gold": false}], "missed": false, "facts": ["Mobium wires up only the capabilities a driver names, so it never asks the driver to type. ⟦only the capabilities named⟧", "The command is refused and the user is told to use a different backend, rather than the driver being asked and failing. ⟦different backend⟧"], "concern": "internal/agent/handlers.go:2214: the refusal for any backend without text entry says \"use the uiautomator2 backend (`--driver uiautomator2`, the default)\" — a remedy that cannot work for a non-Android driver such as a TV, against CONTRIBUTING's rule that a remedy must be one that can work.", "check": "Claude's reading: external.go keeps only known advertised capabilities, AsTextEntry requires CapText, and handlers.go refuses with code unsupported. The refusal's wording is worth a look (concern). Verified in: internal/mobiumdriver/external.go:202, internal/mobiumdriver/capability.go:106, internal/agent/handlers.go:2214."}, {"id": "g088", "kind": "fact", "question": "My driver for a TV with a D-pad marks the node holding input focus as `focused` in its snapshot. What does Mobium do with it?", "tags": ["behavior", "driver-author", "new since 7b590a4"], "gold": [{"id": "examples/drivers/PROTOCOL.md#the-hierarchy", "heading": "The hierarchy", "path": "examples/drivers/PROTOCOL.md", "excerpt": "`snapshot` returns one node, recursively, in the shape of `uitree.WireNode` ([../../internal/uitree/wire.go](../../internal/uitree/wire.go)): ```json {\"class\":\"Button\",\"text\":\"7\",\"testid\":\"com.example:id/digit_7\", \"bounds\":[0,0,100,50],\"clickable\":true, \"children\":[]} ``` Every field is optional except `bounds`, which is `[x1,y1,x2,y2]`. The driver sends **only what the platform told it**. `depth`, `index`, `path` an…"}], "retrieved": [{"id": "CHALLENGES#355", "heading": "355. A TV's map did not say which tile select would press", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** the Fire TV and Apple TV entries in ROADMAP, then MobiumTV's home screen on the Android TV emulator and the Apple TV simulator. A TV is driven by focus: the D-pad moves it and select presses what has it. Both platforms report it on the node — Android's `focused`, and iOS's since 297 — and a D-pad press already read it back (\"focus moved to Focus or Select\"). But `map` built its entries without it, so af…", "gold": false}, {"id": "examples/drivers/PROTOCOL.md#the-hierarchy", "heading": "The hierarchy", "path": "examples/drivers/PROTOCOL.md", "excerpt": "`snapshot` returns one node, recursively, in the shape of `uitree.WireNode` ([../../internal/uitree/wire.go](../../internal/uitree/wire.go)): ```json {\"class\":\"Button\",\"text\":\"7\",\"testid\":\"com.example:id/digit_7\", \"bounds\":[0,0,100,50],\"clickable\":true, \"children\":[]} ``` Every field is optional except `bounds`, which is `[x1,y1,x2,y2]`. The driver sends **only what the platform told it**. `depth`, `index`, `path` an…", "gold": true}, {"id": "docs/ROADMAP.md#under-consideration", "heading": "Under consideration", "path": "docs/ROADMAP.md", "excerpt": "- **Locators for when there is no ref** (written down 2026-10-12). A ref from `map` lasts one map, so an agent has one and a `mobium test` file does not: a hand-written test has the flat `kind=value` locators — text, label, testid, role, class, path, narrowed by `,role=` — which match one element or are refused. That is right on a form and leaves nothing durable on a list. Every Ice Cubes post has a \"…\" (CHALLENGES 2…", "gold": false}, {"id": "CHALLENGES#297", "heading": "297. An Apple TV's focus was in the tree and never read", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** the same session. WebDriverAgent marks the element with focus `focused=\"true\"` on tvOS, and the iOS parser read every attribute but that one, so every D-pad press answered \"nothing on screen reports focus, so where it went cannot be read\" while the app's own line said `Focused: Tile 1`. The parser now reads it, and a press reports where focus went, as on a Fire TV. The other readers of `Focused` ask And…", "gold": false}], "missed": false, "facts": ["`map` shows the node's state as `(button, focused)`. ⟦(button, focused)⟧", "On a device with a D-pad it is what select will press and how a D-pad press is read back, so a TV driver should send it. ⟦D-pad⟧"], "concern": "", "check": "Claude's reading: WireNode.Focused is carried into the node (wire.go) and map appends the \"focused\" state (snapshot.go). The paragraph was added to PROTOCOL.md after 7b590a4 (#259, CHALLENGES 355). Verified in: internal/uitree/wire.go:43, internal/uitree/wire.go:133, internal/uitree/snapshot.go:80, internal/agent/mapdiff.go:184."}, {"id": "g089", "kind": "fact", "question": "How do I make Mobium find my Python driver script on Windows, where there is no shebang line or execute bit?", "tags": ["how-to", "driver-author", "new since 7b590a4"], "gold": [{"id": "examples/drivers/README.md#the-smallest-driver-that-works", "heading": "The smallest driver that works", "path": "examples/drivers/README.md", "excerpt": "Three methods are mandatory: `snapshot`, `screenshot` and `tap`. Plus `initialize`, which says who you are. ```python #!/usr/bin/env python3 import json, sys def handle(method, params): if method == \"initialize\": return {\"protocolVersion\": \"1\", \"name\": \"my-thing\", \"capabilities\": []} if method == \"snapshot\": return {\"class\": \"Screen\", \"bounds\": [0, 0, 400, 800], \"children\": [ {\"class\": \"Button\", \"text\": \"Go\", \"bounds…"}], "retrieved": [{"id": "examples/drivers/README.md#the-smallest-driver-that-works", "heading": "The smallest driver that works", "path": "examples/drivers/README.md", "excerpt": "Three methods are mandatory: `snapshot`, `screenshot` and `tap`. Plus `initialize`, which says who you are. ```python #!/usr/bin/env python3 import json, sys def handle(method, params): if method == \"initialize\": return {\"protocolVersion\": \"1\", \"name\": \"my-thing\", \"capabilities\": []} if method == \"snapshot\": return {\"class\": \"Screen\", \"bounds\": [0, 0, 400, 800], \"children\": [ {\"class\": \"Button\", \"text\": \"Go\", \"bounds…", "gold": true}, {"id": "docs/WINDOWS.md#the-execcommand-audit-2026-09-25", "heading": "The `exec.Command` audit — 2026-09-25", "path": "docs/WINDOWS.md", "excerpt": "Every `exec.Command`, `exec.CommandContext` and `exec.LookPath` outside the clients was read for `.exe` resolution and for paths with spaces. Unverified, like everything else here. - **Spaces and backslashes in arguments are fine.** Go builds the Windows command line with `syscall.EscapeArg`, which quotes for the parsing `adb.exe` does, and nothing is run through `cmd.exe`, so `%` and `^` mean nothing. `adb shell` ar…", "gold": false}, {"id": "examples/drivers/README.md#the-reference-driver", "heading": "The reference driver", "path": "examples/drivers/README.md", "excerpt": "[`mobium-driver-adb`](mobium-driver-adb) is a complete, working driver in ~350 lines of Python with no dependencies. It drives Android through plain `adb` — deliberately the same ground Mobium's own `--driver uiautomator` covers, so its output can be diffed against a known-good implementation on the same screen. That diff is how you tell a driver that works from one that returns something plausible, and it is exactly…", "gold": false}, {"id": "README.md#drivers-for-other-platforms", "heading": "Drivers for other platforms", "path": "README.md", "excerpt": "Anything Mobium does not drive itself — a TV, a desktop app, a platform nobody has written yet — is a **driver**: an executable named `mobium-driver-<name>` on your `PATH`, in any language, speaking JSON-RPC on stdio. ```sh mobium map --driver roku ``` A driver needs three methods to be useful — `snapshot`, `screenshot` and `tap` — and inherits locators, `@ref`s, waiting, scrolling, the CLI, MCP and all five clients.…", "gold": false}], "missed": false, "facts": ["Name it `mobium-driver-mything.exe`, or give the script a wrapper named `mobium-driver-mything.cmd` containing `@python \"%~dp0mobium-driver-mything.py\"`. ⟦mobium-driver-mything.cmd⟧", "Anything listed in PATHEXT is found the same way, and `mobium doctor` reports the driver as `mything` either way. ⟦PATHEXT⟧", "It was run on Windows 11 on 2026-10-22: the reference driver through such a wrapper mapped the same 11 elements as the built-in backend. ⟦Windows 11⟧"], "concern": "", "check": "Claude's reading: the lookup is exec.LookPath(\"mobium-driver-\"+name), which honors PATHEXT on Windows; the Windows 11 run sentence replaced \"not yet run there\" after 7b590a4 (#270). Verified in: internal/mobiumdriver/external.go:114."}, {"id": "g090", "kind": "fact", "question": "How do I install Mobium's agent skill into my coding agent?", "tags": ["how-to", "agent-builder"], "gold": [{"id": "README.md#front-doors", "heading": "Front doors", "path": "README.md", "excerpt": "The CLI does not implement behavior. It calls the same tools an MCP client calls, so the surfaces cannot drift: ```mermaid flowchart LR cli[\"CLI\"] --> daemon clients[\"Python · JS · Go · Java · .NET\"] --> pipe[\"mobium pipe\"] --> daemon mcp[\"MCP client\"] --> mcpcmd[\"mobium mcp\"] daemon[\"daemon<br/>sessions, @refs\"] --> agent mcpcmd --> agent[\"internal/agent<br/>every tool, written once\"] agent --> driver[\"internal/mobi…"}], "retrieved": [{"id": "docs/quickstart/mcp.md#2-connect-an-agent", "heading": "2. Connect an agent", "path": "docs/quickstart/mcp.md", "excerpt": "`mobium mcp` is an MCP server on stdio, so there is nothing to install beyond `mobium` itself. Register it with your agent — in Claude Code: ```sh claude mcp add mobium -- mobium mcp ``` Other clients take the same command in their `mcpServers` configuration; [the MCP guide](../guides/mcp.md#1-connect-it) has the JSON. From then on, ask the agent for what you want done on the device, and it calls the tools below itse…", "gold": false}, {"id": "README.md#front-doors", "heading": "Front doors", "path": "README.md", "excerpt": "The CLI does not implement behavior. It calls the same tools an MCP client calls, so the surfaces cannot drift: ```mermaid flowchart LR cli[\"CLI\"] --> daemon clients[\"Python · JS · Go · Java · .NET\"] --> pipe[\"mobium pipe\"] --> daemon mcp[\"MCP client\"] --> mcpcmd[\"mobium mcp\"] daemon[\"daemon<br/>sessions, @refs\"] --> agent mcpcmd --> agent[\"internal/agent<br/>every tool, written once\"] agent --> driver[\"internal/mobi…", "gold": true}, {"id": "docs/guides/mcp.md#2-an-agent-at-work", "heading": "2. An agent at work", "path": "docs/guides/mcp.md", "excerpt": "Claude Code, non-interactively, with Mobium's server and nothing else allowed: ```sh claude -p \"Use the mobium tools. On the Android emulator, open the app dev.mobium.mobiumapp, go to its Login Demo, sign in with username mobium and password wrongpass1, and tell me exactly what the app says. Keep it short.\" \\ --mcp-config mobium.json --strict-mcp-config --allowedTools mcp__mobium ``` The calls it made, in order, each…", "gold": false}, {"id": "docs/guides/mcp.md#mcp-mobium-as-an-agents-tools", "heading": "MCP: Mobium as an agent's tools", "path": "docs/guides/mcp.md", "excerpt": "`mobium mcp` serves every one of Mobium's tools over the Model Context Protocol, on stdio, so an agent — Claude Code, or any MCP client — drives devices with the same tools the command line and the language clients use. This guide is how to connect one, what it sees, and how its answers and failures come back. Everything below is what ran on 2026-09-28 against [MobiumApp](https://github.com/mobiumdev/mobium-app) on a…", "gold": false}, {"id": "docs/quickstart/README.md#1-install-mobium", "heading": "1. Install mobium", "path": "docs/quickstart/README.md", "excerpt": "Until the first release there are no prebuilt binaries: mobium installs with **Go 1.24 or later** ([go.dev/dl](https://go.dev/dl/)), and needs nothing else. ```sh go install github.com/mobiumdev/mobium/cmd/mobium@latest mobium --version ``` It lands in `$(go env GOPATH)/bin`; make sure that is on your `PATH`. Each client page says how to install that client. Python (with `git`) and Go install straight from GitHub tod…", "gold": false}], "missed": false, "facts": ["Run `npx skills add mobiumdev/mobium --skill mobile-check`. ⟦npx skills add mobiumdev/mobium ; mobile-check⟧"], "concern": "", "check": "Claude's reading: the command is in README's Front doors (part ~2); the skill it installs is skills/mobile-check/SKILL.md with name mobile-check. The npx installer is outside the repo and was not run. Verified in: skills/mobile-check/SKILL.md:2."}, {"id": "g091", "kind": "fact", "question": "With Mobium's Python client, how do I make sure the device session is ended even when my script raises an exception partway?", "tags": ["how-to", "test-author"], "gold": [{"id": "docs/quickstart/python.md#notes", "heading": "Notes", "path": "docs/quickstart/python.md", "excerpt": "- `with start(...) as device:` quits when the block ends, even on an exception. Without `with`, call `device.quit()` yourself — in a `finally`. - `connect()` still exists: it opens a connection without touching the device, and its `close()` leaves the session open for whoever started it. - With more than one device of the session's platform running — two Android devices, or two among the booted simulators and attache…"}], "retrieved": [{"id": "docs/quickstart/python.md#notes", "heading": "Notes", "path": "docs/quickstart/python.md", "excerpt": "- `with start(...) as device:` quits when the block ends, even on an exception. Without `with`, call `device.quit()` yourself — in a `finally`. - `connect()` still exists: it opens a connection without touching the device, and its `close()` leaves the session open for whoever started it. - With more than one device of the session's platform running — two Android devices, or two among the booted simulators and attache…", "gold": true}, {"id": "docs/SHUTDOWN.md#a-clients-sessions-end-with-it", "heading": "A client's sessions end with it", "path": "docs/SHUTDOWN.md", "excerpt": "A session a client opened with `start()` ends when the client goes, whether it called `quit()`, returned without it, crashed or was killed: `mobium pipe` ends the sessions its client started, and only those. `close()` is the way to leave one open on purpose. So a test run that dies half-way no longer leaves a device session behind for the next one to trip over (defect 130). A pipe still running after its client is re…", "gold": false}, {"id": "CHALLENGES#130", "heading": "130. A client that went away left its session open", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** reading what happens to a session when its client exits, then measuring it on the iPhone 17 Pro simulator. Nothing tied a session to the client that started it. A script that returned without `quit()`, or crashed, closed its pipe exactly as `close()` does, and the pipe returned with the session still open on the device until the daemon went idle for 30 minutes. Ctrl-C was worse: it reaches the whole pro…", "gold": false}, {"id": "docs/quickstart/dotnet.md#notes", "heading": "Notes", "path": "docs/quickstart/dotnet.md", "excerpt": "- A `using` block around `Start()` quits when it ends, even on an exception. Around `Connect()` it only closes the connection. - With more than one device of the session's platform running — two Android devices, or two among the booted simulators and attached iPhones — `start` refuses to guess and lists them. One Android device and one iOS device are not ambiguous: the platform picks. Name one with `MOBIUM_DEVICE=<se…", "gold": false}, {"id": "docs/quickstart/javascript.md#notes", "heading": "Notes", "path": "docs/quickstart/javascript.md", "excerpt": "- Put `quit()` in a `finally`, as the example does, so an error part-way still ends the session. A second `quit()` does nothing. - `connect()` still exists: it opens a connection without touching the device, and its `close()` leaves the session open. - With more than one device of the session's platform running — two Android devices, or two among the booted simulators and attached iPhones — `start` refuses to guess a…", "gold": false}], "missed": false, "facts": ["Use `with start(...) as device:`, which quits when the block ends, even on an exception. ⟦with start⟧", "Without `with`, call `device.quit()` yourself in a `finally`. ⟦finally⟧"], "concern": "", "check": "Claude's reading: Device.__exit__ calls quit() for a device from start() and only close() for one from connect(); quit() is idempotent, so an explicit quit plus a with block is fine. Verified in: clients/python/mobium/_device.py:182, clients/python/mobium/_device.py:211."}, {"id": "g092", "kind": "fact", "question": "The .NET client is not on NuGet yet. How do I add it to my project?", "tags": ["how-to", "test-author"], "gold": [{"id": "docs/quickstart/dotnet.md#2-install-the-client", "heading": "2. Install the client", "path": "docs/quickstart/dotnet.md", "excerpt": "Not on NuGet yet. Until the first release it installs from a local package built from a clone; after it, `dotnet add package Mobium` needs nothing else. ```sh git clone https://github.com/mobiumdev/mobium.git ~/mobium dotnet pack ~/mobium/clients/dotnet/Mobium -o ~/mobium-packages dotnet new console -o quickstart && cd quickstart dotnet add package Mobium --version 0.1.0 --source ~/mobium-packages ```"}], "retrieved": [{"id": "docs/quickstart/dotnet.md#2-install-the-client", "heading": "2. Install the client", "path": "docs/quickstart/dotnet.md", "excerpt": "Not on NuGet yet. Until the first release it installs from a local package built from a clone; after it, `dotnet add package Mobium` needs nothing else. ```sh git clone https://github.com/mobiumdev/mobium.git ~/mobium dotnet pack ~/mobium/clients/dotnet/Mobium -o ~/mobium-packages dotnet new console -o quickstart && cd quickstart dotnet add package Mobium --version 0.1.0 --source ~/mobium-packages ```", "gold": true}, {"id": "CHALLENGES#150", "heading": "150. The .NET package could not be built from a clone", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** following the quick start on a fresh Linux machine, which clones the repository as the .NET page says to: `dotnet pack` failed with `NU5019: File not found: .../Mobium/icon.png`. The package's icon was added with the package metadata (#11), and `.gitignore` ignores every `*.png`, because screenshots land in the tree constantly during device work — so the icon was never committed. Every check that packed…", "gold": false}, {"id": "docs/quickstart/javascript.md#2-install-the-client", "heading": "2. Install the client", "path": "docs/quickstart/javascript.md", "excerpt": "Not on npm yet, and npm cannot install a package from a folder inside a repository, so until the first release it installs from a clone. After the release this becomes `npm install mobium`. ```sh git clone https://github.com/mobiumdev/mobium.git ~/mobium mkdir quickstart && cd quickstart npm init -y npm install ~/mobium/clients/javascript ```", "gold": false}, {"id": "docs/quickstart/java.md#2-install-the-client", "heading": "2. Install the client", "path": "docs/quickstart/java.md", "excerpt": "Not on Maven Central yet. Until the first release it installs into your local Maven repository from a clone; after it, the dependency below resolves from Central with no clone at all. ```sh git clone https://github.com/mobiumdev/mobium.git ~/mobium cd ~/mobium/clients/java && ./mvnw install -DskipTests && cd - mkdir quickstart && cd quickstart ```", "gold": false}, {"id": "docs/quickstart/README.md#1-install-mobium", "heading": "1. Install mobium", "path": "docs/quickstart/README.md", "excerpt": "Until the first release there are no prebuilt binaries: mobium installs with **Go 1.24 or later** ([go.dev/dl](https://go.dev/dl/)), and needs nothing else. ```sh go install github.com/mobiumdev/mobium/cmd/mobium@latest mobium --version ``` It lands in `$(go env GOPATH)/bin`; make sure that is on your `PATH`. Each client page says how to install that client. Python (with `git`) and Go install straight from GitHub tod…", "gold": false}], "missed": false, "facts": ["Clone the repository and build a local package with `dotnet pack` from clients/dotnet/Mobium into a folder. ⟦dotnet pack⟧", "Add it with `dotnet add package Mobium --version 0.1.0 --source <that folder>`. ⟦--source⟧"], "concern": "", "check": "Claude's reading: the csproj's PackageId is Mobium and Version 0.1.0, matching the quickstart's `--version 0.1.0`. Verified in: clients/dotnet/Mobium/Mobium.csproj:29, clients/dotnet/Mobium/Mobium.csproj:30."}, {"id": "g093", "kind": "fact", "question": "Why would a pull request that adds a separate implementation of some behavior just for the MCP server be pushed back on in Mobium?", "tags": ["rationale", "contributor"], "gold": [{"id": "CONTRIBUTING.md#the-design-rule", "heading": "The design rule", "path": "CONTRIBUTING.md", "excerpt": "***Mutatis mutandis*** — the same argument carried into a new domain, changing only what must change. When something needs to work on a second platform, through a second front door or via a third-party backend, the answer is the existing thing with the necessary changes, not a parallel implementation. A change that duplicates a layer is almost always the wrong one. [docs/PHILOSOPHY.md](docs/PHILOSOPHY.md) has where t…"}], "retrieved": [{"id": "README.md#front-doors", "heading": "Front doors", "path": "README.md", "excerpt": "The CLI does not implement behavior. It calls the same tools an MCP client calls, so the surfaces cannot drift: ```mermaid flowchart LR cli[\"CLI\"] --> daemon clients[\"Python · JS · Go · Java · .NET\"] --> pipe[\"mobium pipe\"] --> daemon mcp[\"MCP client\"] --> mcpcmd[\"mobium mcp\"] daemon[\"daemon<br/>sessions, @refs\"] --> agent mcpcmd --> agent[\"internal/agent<br/>every tool, written once\"] agent --> driver[\"internal/mobi…", "gold": false}, {"id": "packaging/mcp/README.md#mcp-packaging", "heading": "MCP packaging", "path": "packaging/mcp/README.md", "excerpt": "What puts Mobium's MCP server — `mobium mcp` — into the [MCP Registry](https://registry.modelcontextprotocol.io) and into clients that install MCP bundles, such as Claude Desktop. | File | What it is | | --- | --- | | [manifest.json](manifest.json) | The MCPB manifest, a template: the version and the tool list are filled in at build time | | [launcher.sh](launcher.sh) | The bundle's entry point, `server/mobium`: a bu…", "gold": false}, {"id": "docs/DEVELOPMENT.md#7-send-a-pull-request", "heading": "7. Send a pull request", "path": "docs/DEVELOPMENT.md", "excerpt": "`main` is protected. A change reaches it through a pull request that has been reviewed and whose **Build, vet and test** check passes. Two more jobs run on Windows: one runs the .NET client's tests, and `go-windows` runs both Go modules' tests, the named-pipe daemon transport's, and a smoke test of the built `mobium.exe`. History stays linear: pull requests are squash-merged, merge commits are off, force-pushes to `m…", "gold": false}, {"id": "docs/ARCHITECTURE.md#the-whole-system", "heading": "The whole system", "path": "docs/ARCHITECTURE.md", "excerpt": "```mermaid flowchart TB subgraph doors[\"Front doors\"] cli[\"CLI<br/>mobium map, mobium tap @e5\"] clients[\"Language clients<br/>Python · JavaScript · Go · Java · .NET\"] mcp[\"MCP client<br/>an agent\"] test[\"mobium test<br/>JSON test files · --ui page\"] inspect[\"mobium inspect<br/>a page showing the screen\"] end pipe[\"mobium pipe<br/>JSON-RPC on stdio\"] mcpcmd[\"mobium mcp<br/>MCP on stdio, in-process\"] daemon[\"Daemon<br/…", "gold": false}, {"id": "CLAUDE.md#rules", "heading": "Rules", "path": "CLAUDE.md", "excerpt": "- Run `make ci` before committing. After adding a tool, a flag or a schema property, run `make api flags` and add it everywhere — CLI, MCP schema, all five clients (CONTRIBUTING.md, \"Adding a tool, a flag or an error\") - Every error has a code: `mobiumerr.New(mobiumerr.<Code>, ...)`, never a bare `fmt.Errorf` - The CLI implements no behavior; it calls a tool. Behavior lives in `internal/agent` - After rebuilding, `mo…", "gold": false}], "missed": true, "facts": ["Mobium's design rule, mutatis mutandis, is to carry the existing thing with only the necessary changes, not a parallel implementation; a change that duplicates a layer is almost always the wrong one. ⟦Mutatis mutandis ; duplicates a layer⟧", "Behavior lives in internal/agent and the CLI only parses flags and calls a tool by name, so the MCP surface and every client get it too. ⟦internal/agent⟧"], "concern": "", "check": "Claude's reading: CONTRIBUTING's design rule says both; the code matches — `mobium mcp` serves agent.NewServer, the same tool layer the daemon dispatches to, and apisurface fails the build on drift between front doors. Verified in: cmd/mobium/mcp_cmd.go:25, internal/apisurface/surface_test.go:50."}, {"id": "g094", "kind": "fact", "question": "I'm driving a real Android phone on the office Wi-Fi with Mobium's default driver. Can others on that network get at the phone while my session is open, and what does Mobium offer instead?", "tags": ["behavior", "test-author"], "gold": [{"id": "docs/upstream/uiautomator2-server-binds-every-interface.md#what-mobium-does-meanwhile", "heading": "What Mobium does meanwhile", "path": "docs/upstream/uiautomator2-server-binds-every-interface.md", "excerpt": "Mobium installs the release APK, pinned by checksum, and cannot bind it. When a session opens on a real Android phone with this server, its answer says so — the server answers on the phone's network until the session ends — and names `--driver uiautomator`, which drives the phone through `uiautomator dump` over adb and listens on nothing: measured on the Pixel 8 Pro, a dump session added no listening socket where thi…"}], "retrieved": [{"id": "CHALLENGES#154", "heading": "154. A real Android phone's UiAutomator2 server answered anyone on its Wi-Fi", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** the threat model's open item, measured on the Pixel 8 Pro, Android 17, on the same Wi-Fi as the Mac. The UiAutomator2 server listens on every interface of the phone — `*:6790`, and its MJPEG stream on `*:7810` — and from the Mac, over Wi-Fi rather than adb, `/status` answered \"ready to accept commands\" and the stream answered too: while a session ran, anything on the network could read the screen and dr…", "gold": false}, {"id": "docs/upstream/uiautomator2-server-binds-every-interface.md#what-mobium-does-meanwhile", "heading": "What Mobium does meanwhile", "path": "docs/upstream/uiautomator2-server-binds-every-interface.md", "excerpt": "Mobium installs the release APK, pinned by checksum, and cannot bind it. When a session opens on a real Android phone with this server, its answer says so — the server answers on the phone's network until the session ends — and names `--driver uiautomator`, which drives the phone through `uiautomator dump` over adb and listens on nothing: measured on the Pixel 8 Pro, a dump session added no listening socket where thi…", "gold": true}, {"id": "docs/upstream/uiautomator2-server-binds-every-interface.md#summary", "heading": "Summary", "path": "docs/upstream/uiautomator2-server-binds-every-interface.md", "excerpt": "The UiAutomator2 server and its MJPEG stream listen on every interface of the device, and nothing chooses otherwise. On a real phone on Wi-Fi, anyone on the same network can read the screen and drive the phone while the server runs — tap, type, open apps — with no credential, since the protocol has none. A client that reaches the server through `adb forward` does not need that, since adb connects to the device's loop…", "gold": false}, {"id": "examples/drivers/README.md#the-reference-driver", "heading": "The reference driver", "path": "examples/drivers/README.md", "excerpt": "[`mobium-driver-adb`](mobium-driver-adb) is a complete, working driver in ~350 lines of Python with no dependencies. It drives Android through plain `adb` — deliberately the same ground Mobium's own `--driver uiautomator` covers, so its output can be diffed against a known-good implementation on the same screen. That diff is how you tell a driver that works from one that returns something plausible, and it is exactly…", "gold": false}, {"id": "CHALLENGES#153", "heading": "153. A real iPhone's WebDriverAgent answered anyone on its Wi-Fi", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** the threat model's open item, measured on the iPhone 15 Plus: the runner's `/status`, which reports the phone's Wi-Fi address, was asked again at that address from the Mac, over the network rather than the cable.", "gold": false}], "missed": false, "facts": ["Yes: the session's answer says the UiAutomator2 server answers on the phone's network until the session ends. ⟦phone's network⟧", "It names `--driver uiautomator`, which drives the phone through `uiautomator dump` over adb and listens on nothing. ⟦--driver uiautomator ; listens on nothing⟧"], "concern": "", "check": "Claude's reading: sessionExposure returns the warning only for the uiautomator2 backend on a non-emulator device; its text also says the uiautomator driver reads at about 2 s a screen and cannot type, which this section does not mention. Verified in: internal/agent/session.go:31, internal/agent/session.go:373."}, {"id": "g095", "kind": "multi", "question": "The MCP guide shows `tools/list` answering 71 tools, but `mobium mcp` lists 75 for me. Is my install wrong?", "tags": ["troubleshooting", "agent-builder", "new since 7b590a4"], "gold": [{"id": "docs/API.md#the-numbers", "heading": "The numbers", "path": "docs/API.md", "excerpt": "| | | | --- | --- | | Tools | **75** | | CLI commands registered | 84 | | …visible in `mobium --help` | 83 | | …hidden | 1 (pipe) | | Command constructors in source | 90 (includes `daemon start`, `stop`, `status`) | | Client libraries | 5 | Those three command counts differ on purpose, and the arithmetic is asserted by a test: registered = visible + hidden, and the constructor count is higher again because `daemon` h…"}, {"id": "docs/guides/mcp.md#mcp-mobium-as-an-agents-tools", "heading": "MCP: Mobium as an agent's tools", "path": "docs/guides/mcp.md", "excerpt": "`mobium mcp` serves every one of Mobium's tools over the Model Context Protocol, on stdio, so an agent — Claude Code, or any MCP client — drives devices with the same tools the command line and the language clients use. This guide is how to connect one, what it sees, and how its answers and failures come back. Everything below is what ran on 2026-09-28 against [MobiumApp](https://github.com/mobiumdev/mobium-app) on a…"}], "retrieved": [{"id": "docs/guides/mcp.md#which-front-door", "heading": "Which front door", "path": "docs/guides/mcp.md", "excerpt": "| | Command line | MCP | Language clients | | --- | --- | --- | --- | | For | a person, a shell script, CI | an agent | a program or a test suite | | Runs as | `mobium <command>` through the daemon | `mobium mcp`, in its own process | `mobium pipe`, spawned by the client, through the daemon | | Answers | text, or `--json` | `content` and `structuredContent` | typed results and exceptions | The same 71 tools behind ea…", "gold": false}, {"id": "docs/guides/mcp.md#mcp-mobium-as-an-agents-tools", "heading": "MCP: Mobium as an agent's tools", "path": "docs/guides/mcp.md", "excerpt": "`mobium mcp` serves every one of Mobium's tools over the Model Context Protocol, on stdio, so an agent — Claude Code, or any MCP client — drives devices with the same tools the command line and the language clients use. This guide is how to connect one, what it sees, and how its answers and failures come back. Everything below is what ran on 2026-09-28 against [MobiumApp](https://github.com/mobiumdev/mobium-app) on a…", "gold": true}, {"id": "docs/WINDOWS.md#what-is-expected-to-work-already", "heading": "What is expected to work already", "path": "docs/WINDOWS.md", "excerpt": "Never run against a device on Windows — that is the point of this exercise — but these have no platform-specific code: - the tool layer, the driver interface, the tree parser, locators and refs - `adb` discovery and every Android command, including port forwarding - the UiAutomator2 backend, its APK download and checksum verification - WebView contexts over CDP - **`mobium mcp`**, which runs the tool layer in-process…", "gold": false}, {"id": "docs/quickstart/mcp.md#2-connect-an-agent", "heading": "2. Connect an agent", "path": "docs/quickstart/mcp.md", "excerpt": "`mobium mcp` is an MCP server on stdio, so there is nothing to install beyond `mobium` itself. Register it with your agent — in Claude Code: ```sh claude mcp add mobium -- mobium mcp ``` Other clients take the same command in their `mcpServers` configuration; [the MCP guide](../guides/mcp.md#1-connect-it) has the JSON. From then on, ask the agent for what you want done on the device, and it calls the tools below itse…", "gold": false}, {"id": "docs/guides/cli.md#the-command-line", "heading": "The command line", "path": "docs/guides/cli.md", "excerpt": "`mobium` is one binary, and every command is one call to one of Mobium's tools — the same tools an MCP client and the five language clients call, so the command line cannot do something they cannot. This guide is how the commands fit together: the loop, sessions and the daemon, the flags every command takes, reading answers from a script, and exit statuses. Every command and every line of output below is what `mobium…", "gold": false}], "missed": false, "facts": ["No: the generated tool surface in API.md counts 75 tools today. ⟦75⟧", "The guide's transcripts are from a run on 2026-09-28, and its full tool list is the generated API.md."], "concern": "docs/guides/mcp.md:126 and :296 and docs/quickstart/mcp.md:134 and :166 still say 71 tools; the code (internal/agent/schema.go) has 75, and API.md said 73 at the pin. The guide and quickstart are stale.", "check": "Claude's reading: schema.go defines 75 app_ tools; app_speech and app_assistant were added after 7b590a4 (73 at the pin). A right answer needs API.md for the count and the guide's intro for why its number is older. Verified in: internal/agent/schema.go:1966, internal/agent/schema.go:2007, docs/api/surface.json."}, {"id": "g096", "kind": "multi", "question": "My driver should let Mobium scroll and use scroll-to. What do I have to advertise and implement?", "tags": ["how-to", "driver-author"], "gold": [{"id": "examples/drivers/README.md#capabilities", "heading": "Capabilities", "path": "examples/drivers/README.md", "excerpt": "`snapshot`, `screenshot` and `tap` are mandatory. Everything else is opt-in: | Capability | Methods | What you unlock | |---|---|---| | `gestures` | `swipe`, `longPress` | scrolling, `scroll-to`, long press | | `text` | `setText`, `clear` | typing into a named element | | `apps` | `launch`, `terminate`, `install`, `openUrl` | app lifecycle and deep links | | `appearance` | `appearance`, `setAppearance` | light/dark |…"}, {"id": "examples/drivers/PROTOCOL.md#methods", "heading": "Methods", "path": "examples/drivers/PROTOCOL.md", "excerpt": "| Method | Params | Result | Capability | |---|---|---|---| | `initialize` | `protocolVersion`, `device` | `protocolVersion`, `name`, `capabilities` | — | | `snapshot` | — | a wire node (see below) | — | | `screenshot` | — | `{\"png\":\"<base64>\"}` | — | | `tap` | `x`, `y` | `{}` | — | | `swipe` | `x1`,`y1`,`x2`,`y2`,`durationMs` | `{}` | `gestures` | | `longPress` | `x`,`y`,`durationMs` | `{}` | `gestures` | | `setText…"}], "retrieved": [{"id": "skills/mobile-check/SKILL.md#reaching-things-below-the-fold", "heading": "Reaching things below the fold", "path": "skills/mobile-check/SKILL.md", "excerpt": "`mobium map` only sees what is currently on screen. Tap, type and long-press already scroll to a target that is not, so most of the time nothing extra is needed — reach for `scroll-to` to look without acting, or to go back up: - `mobium scroll-to \"text=Sign out\"` — bring it into view and get a ref - `mobium scroll-to \"text=Network & internet\" --direction up` Vertical lists only. For a horizontal pager or carousel use…", "gold": false}, {"id": "CHALLENGES#if-you-are-seeing-something-odd-start-here", "heading": "If you are seeing something odd, start here", "path": "docs/CHALLENGES.md", "excerpt": "Symptom first, because that is what you have. Every row points at the entry with the evidence. | What you are seeing | What it usually is | | --- | --- | | A command \"succeeded\" and nothing changed | Nothing here reports failure by exit code. `pm grant`, `simctl privacy`, `am start`, `adb uninstall` and `uiautomator dump` each fail differently — 25, 26, 27, 30 | | An element is on screen but a locator says it is not …", "gold": false}, {"id": "examples/drivers/README.md#the-reference-driver", "heading": "The reference driver", "path": "examples/drivers/README.md", "excerpt": "[`mobium-driver-adb`](mobium-driver-adb) is a complete, working driver in ~350 lines of Python with no dependencies. It drives Android through plain `adb` — deliberately the same ground Mobium's own `--driver uiautomator` covers, so its output can be diffed against a known-good implementation on the same screen. That diff is how you tell a driver that works from one that returns something plausible, and it is exactly…", "gold": false}, {"id": "skills/mobile-check/SKILL.md#when-things-fail", "heading": "When things fail", "path": "skills/mobile-check/SKILL.md", "excerpt": "Mobium's errors say what to do; read them rather than retrying blindly. Every failure also carries a **code**, so you can act on the kind without parsing the sentence: `--json` prints it (`\"code\": \"no_such_element\"`, with a `remedy` and `details`), and the exit status groups it: | Exit | Codes | What to do | | --- | --- | --- | | 2 | `invalid_argument` | fix the command; retrying it unchanged cannot help | | 3 | `no_…", "gold": false}, {"id": "CHALLENGES#169", "heading": "169. scroll-to stopped with its target a sliver at the edge", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** the documentation site's picture of `mobium scroll-to \"label=Card 8\" --direction right` on MobiumApp's Pager Demo, on an Android 15 emulator — the answer said Card 8 was on screen, and the picture showed Card 7 with 101 pixels of Card 8 at the edge. `app_scroll_to` stops when its target is wholly inside its scroll container, and on Android that test can never fail once any of the target is in: a child's…", "gold": false}], "missed": true, "facts": ["Advertise the `gestures` capability in the initialize reply; it unlocks scrolling, scroll-to and long press.", "Implement `swipe` taking x1, y1, x2, y2 and durationMs (and `longPress` taking x, y, durationMs), in device pixels. ⟦durationMs⟧"], "concern": "", "check": "Claude's reading: README's capabilities table maps gestures to swipe and longPress and what they unlock; PROTOCOL's methods table has the parameters, which External.Swipe and LongPress send exactly. Verified in: internal/mobiumdriver/external.go:318, internal/mobiumdriver/external.go:324."}, {"id": "g097", "kind": "multi", "question": "I want two agents, each driving its own Android emulator through Mobium's MCP server at the same time. How do I set them up so they don't get in each other's way?", "tags": ["how-to", "agent-builder"], "gold": [{"id": "docs/guides/mcp.md#1-connect-it", "heading": "1. Connect it", "path": "docs/guides/mcp.md", "excerpt": "In Claude Code: ```sh claude mcp add mobium -- mobium mcp ``` With more than one device, pin one — `mobium mcp --device emulator-5554` — or let the agent pass `device` to each call. `--driver wda` makes iOS the default. Other MCP clients take the same server in their JSON configuration, under `mcpServers`: ```json { \"mcpServers\": { \"mobium\": { \"command\": \"mobium\", \"args\": [\"mcp\", \"--device\", \"emulator-5554\"] } } } ``…"}, {"id": "docs/guides/mcp.md#6-sessions-and-sharing-a-device", "heading": "6. Sessions, and sharing a device", "path": "docs/guides/mcp.md", "excerpt": "`mobium mcp` runs the tools in its own process: the editor's MCP connection is the long-lived thing, and it holds its own device sessions, with the agent's refs. The command line and the language clients share a daemon instead. A device's automation server holds one session at a time, so an agent's MCP server and a `mobium` command driving **the same device at the same time** take it from each other — each recovers, …"}], "retrieved": [{"id": "docs/guides/mcp.md#6-sessions-and-sharing-a-device", "heading": "6. Sessions, and sharing a device", "path": "docs/guides/mcp.md", "excerpt": "`mobium mcp` runs the tools in its own process: the editor's MCP connection is the long-lived thing, and it holds its own device sessions, with the agent's refs. The command line and the language clients share a daemon instead. A device's automation server holds one session at a time, so an agent's MCP server and a `mobium` command driving **the same device at the same time** take it from each other — each recovers, …", "gold": true}, {"id": "docs/guides/mcp.md#1-connect-it", "heading": "1. Connect it", "path": "docs/guides/mcp.md", "excerpt": "In Claude Code: ```sh claude mcp add mobium -- mobium mcp ``` With more than one device, pin one — `mobium mcp --device emulator-5554` — or let the agent pass `device` to each call. `--driver wda` makes iOS the default. Other MCP clients take the same server in their JSON configuration, under `mcpServers`: ```json { \"mcpServers\": { \"mobium\": { \"command\": \"mobium\", \"args\": [\"mcp\", \"--device\", \"emulator-5554\"] } } } ``…", "gold": true}, {"id": "docs/SETUP.md#parallel-runs", "heading": "Parallel runs", "path": "docs/SETUP.md", "excerpt": "**Give each run that drives a device at the same time as another its own daemon.** One daemon serves one call at a time, across every device it holds, so two runs sharing one go at the pace of the slower device. Measured on 2026-09-27, 15 `map` calls on each of an Android 15 emulator and an iPhone 17 Pro simulator at once: | | the emulator's 15 calls | | --- | --- | | alone | 0.3s | | sharing a daemon with the simula…", "gold": false}, {"id": "docs/guides/mcp.md#mcp-mobium-as-an-agents-tools", "heading": "MCP: Mobium as an agent's tools", "path": "docs/guides/mcp.md", "excerpt": "`mobium mcp` serves every one of Mobium's tools over the Model Context Protocol, on stdio, so an agent — Claude Code, or any MCP client — drives devices with the same tools the command line and the language clients use. This guide is how to connect one, what it sees, and how its answers and failures come back. Everything below is what ran on 2026-09-28 against [MobiumApp](https://github.com/mobiumdev/mobium-app) on a…", "gold": false}, {"id": "docs/quickstart/mcp.md#2-connect-an-agent", "heading": "2. Connect an agent", "path": "docs/quickstart/mcp.md", "excerpt": "`mobium mcp` is an MCP server on stdio, so there is nothing to install beyond `mobium` itself. Register it with your agent — in Claude Code: ```sh claude mcp add mobium -- mobium mcp ``` Other clients take the same command in their `mcpServers` configuration; [the MCP guide](../guides/mcp.md#1-connect-it) has the JSON. From then on, ask the agent for what you want done on the device, and it calls the tools below itse…", "gold": false}], "missed": false, "facts": ["Pin each server to its own device, e.g. `mobium mcp --device emulator-5554` in each client's configuration. ⟦--device emulator-5554⟧", "Each `mobium mcp` runs the tools in its own process with its own device sessions, and a device's automation server holds one session at a time, so each agent needs its own device. ⟦one session at a time ; its own process⟧"], "concern": "", "check": "Claude's reading: SetDefaultDevice is set from the global --device in mcp_cmd.go; that two servers on two different devices work together is implied by section 6 rather than stated as a run, which a reviewer may want to weigh. Verified in: cmd/mobium/mcp_cmd.go:26, internal/agent/server.go."}, {"id": "g098", "kind": "multi", "question": "Can I put Mobium into a read-only mode so my agent can look at the screen but never act on the device?", "tags": ["support", "agent-builder"], "gold": [{"id": "docs/THREAT-MODEL.md#the-llm-top-10", "heading": "The LLM Top 10", "path": "docs/THREAT-MODEL.md", "excerpt": "| Risk | Here | Done | Open | | --- | --- | --- | --- | | **LLM01 Prompt injection** | Screen text is the classic indirect path: an app or page shows \"ignore your task and uninstall…\", and the agent reads it in `map` or `text` | Labels are bounded and cleaned, so one label cannot carry a page of instructions | Results mark which content came from the device, so an agent or its harness can treat it as data. An agent e…"}, {"id": "docs/guides/mcp.md#3-what-a-client-sees", "heading": "3. What a client sees", "path": "docs/guides/mcp.md", "excerpt": "The handshake, as sent and answered: ``` >>> {\"jsonrpc\": \"2.0\", \"id\": 1, \"method\": \"initialize\", \"params\": {\"protocolVersion\": \"2024-11-05\", \"capabilities\": {}, \"clientInfo\": {\"name\": \"probe\", \"version\": \"1\"}}} <<< { \"jsonrpc\": \"2.0\", \"id\": 1, \"result\": { \"protocolVersion\": \"2024-11-05\", \"capabilities\": { \"tools\": {} }, \"serverInfo\": { \"name\": \"mobium\", \"version\": \"0.1.0-dev\" } } } ``` `tools/list` answered with 71 t…"}], "retrieved": [{"id": "docs/THREAT-MODEL.md#what-it-is-for-this-purpose", "heading": "What it is, for this purpose", "path": "docs/THREAT-MODEL.md", "excerpt": "- **Mobium does not run a model.** It is the hands of one: an agent, or a script, calls tools; Mobium acts on a device and reports what it saw. - **Everything it reports comes from apps it does not control.** `map` labels, `text`, `source`, WebView `eval` results, notifications, device logs, crash reports, the clipboard. Any app or page can put text there, including text written to be read by an agent as an instructi…", "gold": false}, {"id": "docs/SETUP.md#with-a-screen-reader-on", "heading": "With a screen reader on", "path": "docs/SETUP.md", "excerpt": "Android's test-automation connection silences every other accessibility service while it is open, unless it is opened not to. So on a device with TalkBack — or VoiceView, on a Fire TV — on, a read of the screen takes the screen reader away for as long as it runs, and an app that publishes its contents only to a screen reader stops publishing them (CHALLENGES 208). Both drivers leave the screen reader running. The def…", "gold": false}, {"id": "CHALLENGES#109", "heading": "109. On Android, a screen in motion could only be read once it stopped", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** the confetti on MobiumApp's Motion Demo, which exists to put a screen in continuous motion on purpose. The first read during a three-second burst took 3.75s and read the burst as over; a `find` during a slower one took 11s, and the piece it aimed at had fallen off the screen by then. iOS read the same burst in 0.56s, mid-fall. Mobium never set UiAutomator2's `waitForIdleTimeout`, so the server's default…", "gold": false}, {"id": "CHALLENGES#208", "heading": "208. Every read silenced the device's screen reader", "path": "docs/CHALLENGES.md", "excerpt": "**Found by:** reading Prime Video on a Fire TV, which publishes nothing but one surface to `map`, to see whether it publishes more while Amazon's screen reader, VoiceView, is on. Every read of the screen — `uiautomator dump` and the UiAutomator2 server alike — unbound VoiceView for as long as it ran: `dumpsys accessibility` listed it before the read and not during it, and touch exploration went off. Android's test-au…", "gold": false}, {"id": "docs/SETUP.md#slower-and-one-stall-to-know-about", "heading": "Slower, and one stall to know about", "path": "docs/SETUP.md", "excerpt": "A phone reads a screen in about 2 seconds for Settings and 6 for the home screen, against a fraction of a second on a simulator; a screenshot takes 0.5s. Prefer `map` to `screenshot` for the same reason as on Android. **The first read after switching apps can stall for a minute and return the app you just left** ([CHALLENGES 71](CHALLENGES.md)). Mobium prevents it for the switches it makes itself — `launch` and `pres…", "gold": false}], "missed": true, "facts": ["Not in Mobium itself: a read-only mode Mobium enforces, and a tool allowlist, are listed as open. ⟦read-only mode⟧", "Every MCP tool carries `readOnlyHint`, true only for the tools that only read (`app_map`, `app_text`, `app_state` and the like), so the agent's harness can allow only reads. ⟦readOnlyHint⟧"], "concern": "", "check": "Claude's reading: readonly.go lists 19 read-only tools and schema.go sets readOnlyHint from it; `mobium mcp` has no read-only flag. Unrelated defect seen while checking: app_network's new `proxy` argument is missing from readUnless in readonly.go, so IsReadCall treats a proxy-setting call as a read for the test runner's expect. Verified in: internal/agent/readonly.go:13, internal/agent/schema.go:2243, cmd/mobium/mcp_cmd.go:11."}, {"id": "g099", "kind": "unanswerable", "question": "How many tool calls per minute will Mobium's MCP server accept before it starts throttling my agent?", "tags": ["agent-builder"], "gold": [], "retrieved": [{"id": "README.md#front-doors", "heading": "Front doors", "path": "README.md", "excerpt": "The CLI does not implement behavior. It calls the same tools an MCP client calls, so the surfaces cannot drift: ```mermaid flowchart LR cli[\"CLI\"] --> daemon clients[\"Python · JS · Go · Java · .NET\"] --> pipe[\"mobium pipe\"] --> daemon mcp[\"MCP client\"] --> mcpcmd[\"mobium mcp\"] daemon[\"daemon<br/>sessions, @refs\"] --> agent mcpcmd --> agent[\"internal/agent<br/>every tool, written once\"] agent --> driver[\"internal/mobi…", "gold": false}, {"id": "docs/quickstart/mcp.md#3-the-code", "heading": "3. The code", "path": "docs/quickstart/mcp.md", "excerpt": "Save this as `quickstart.py` — it is [examples/mcp/quickstart.py](examples/mcp/quickstart.py). The calls an agent makes, made by a script instead: start the server, open with the handshake, then one `tools/call` per step. Every tool is an `app_` name with JSON arguments, and every answer has text to read and, for most, `structuredContent` to use as data. ```python \"\"\"Mobium quick start over MCP: start a session, driv…", "gold": false}, {"id": "docs/guides/mcp.md#6-sessions-and-sharing-a-device", "heading": "6. Sessions, and sharing a device", "path": "docs/guides/mcp.md", "excerpt": "`mobium mcp` runs the tools in its own process: the editor's MCP connection is the long-lived thing, and it holds its own device sessions, with the agent's refs. The command line and the language clients share a daemon instead. A device's automation server holds one session at a time, so an agent's MCP server and a `mobium` command driving **the same device at the same time** take it from each other — each recovers, …", "gold": false}, {"id": "docs/guides/mcp.md#mcp-mobium-as-an-agents-tools", "heading": "MCP: Mobium as an agent's tools", "path": "docs/guides/mcp.md", "excerpt": "`mobium mcp` serves every one of Mobium's tools over the Model Context Protocol, on stdio, so an agent — Claude Code, or any MCP client — drives devices with the same tools the command line and the language clients use. This guide is how to connect one, what it sees, and how its answers and failures come back. Everything below is what ran on 2026-09-28 against [MobiumApp](https://github.com/mobiumdev/mobium-app) on a…", "gold": false}, {"id": "docs/quickstart/mcp.md#2-connect-an-agent", "heading": "2. Connect an agent", "path": "docs/quickstart/mcp.md", "excerpt": "`mobium mcp` is an MCP server on stdio, so there is nothing to install beyond `mobium` itself. Register it with your agent — in Claude Code: ```sh claude mcp add mobium -- mobium mcp ``` Other clients take the same command in their `mcpServers` configuration; [the MCP guide](../guides/mcp.md#1-connect-it) has the JSON. From then on, ask the agent for what you want done on the device, and it calls the tools below itse…", "gold": false}], "missed": false, "facts": [], "concern": "", "check": "Claude's reading: no rate limit is stated anywhere in the corpus, and the code has none (grep for rate limit or throttle in internal/agent and cmd/mobium finds only Android's crash-record limit); the threat model's unbounded-consumption row lists per-call timeouts, batches of at most 100 steps and backgrounding of at most 180 s, which a retriever will bring back. Nearest sections: docs/THREAT-MODEL.md#the-llm-top-10, docs/guides/mcp.md#6-sessions-and-sharing-a-device. Verified in: internal/agent/server.go:43."}, {"id": "g100", "kind": "unanswerable", "question": "When will Mobium's Python client be published on PyPI so I can just run pip install mobium?", "tags": ["test-author"], "gold": [], "retrieved": [{"id": "docs/quickstart/python.md#2-install-the-client", "heading": "2. Install the client", "path": "docs/quickstart/python.md", "excerpt": "Not on PyPI yet — pip installs it straight from GitHub, which needs `git` on your `PATH`. After the first release this becomes `pip install mobium`. ```sh mkdir quickstart && cd quickstart python3 -m venv .venv .venv/bin/pip install \"mobium @ git+https://github.com/mobiumdev/mobium.git#subdirectory=clients/python\" ```", "gold": false}, {"id": "docs/DEVELOPMENT.md#5-work-on-a-client", "heading": "5. Work on a client", "path": "docs/DEVELOPMENT.md", "excerpt": "Each client's tests start a fake `mobium` and need no device: | Client | Its tests | Run a program against it from this clone | | --- | --- | --- | | Python | `make clients` | `pip install ./clients/python` in a virtualenv | | JavaScript | `make clients` | `npm install ./clients/javascript` | | Go | `make test` | `go mod edit -replace=github.com/mobiumdev/mobium/clients/go=<path to this clone>/clients/go` in your mod…", "gold": false}, {"id": "docs/quickstart/README.md#1-install-mobium", "heading": "1. Install mobium", "path": "docs/quickstart/README.md", "excerpt": "Until the first release there are no prebuilt binaries: mobium installs with **Go 1.24 or later** ([go.dev/dl](https://go.dev/dl/)), and needs nothing else. ```sh go install github.com/mobiumdev/mobium/cmd/mobium@latest mobium --version ``` It lands in `$(go env GOPATH)/bin`; make sure that is on your `PATH`. Each client page says how to install that client. Python (with `git`) and Go install straight from GitHub tod…", "gold": false}, {"id": "docs/ROADMAP.md#under-consideration", "heading": "Under consideration", "path": "docs/ROADMAP.md", "excerpt": "- **Locators for when there is no ref** (written down 2026-10-12). A ref from `map` lasts one map, so an agent has one and a `mobium test` file does not: a hand-written test has the flat `kind=value` locators — text, label, testid, role, class, path, narrowed by `,role=` — which match one element or are refused. That is right on a form and leaves nothing durable on a list. Every Ice Cubes post has a \"…\" (CHALLENGES 2…", "gold": false}, {"id": "docs/guides/test-runner.md#quick-start-mobium-test", "heading": "Quick start: `mobium test`", "path": "docs/guides/test-runner.md", "excerpt": "From an empty directory to a test suite that runs on a device, fails with evidence, retries, and leaves a report CI can publish. Every command and every line of output below is what `mobium test` printed on 2026-09-28 — section 8 on 2026-09-29 — against [MobiumApp](https://github.com/mobiumdev/mobium-app) on an Android 15 emulator. Where a path to a report is shortened, it says so. Before this guide: [the quick start…", "gold": false}], "missed": false, "facts": [], "concern": "", "check": "Claude's reading: the quickstart says only that `pip install mobium` works after the first release, and the roadmap lists the registry accounts to set up; no date for the first release or the PyPI publish is given anywhere in the corpus. Nearest sections: docs/quickstart/python.md#2-install-the-client, docs/ROADMAP.md#next. Verified in: clients/python."}], "pins": {}};
 const KIND = {fact:"Single fact", multi:"Two sections", unanswerable:"Not in the docs"};
 const reviews = {};          // id -> stored decision
 const drafts = {};           // id -> unsaved text while typing