System Dialogs
Device language. Permission buttons (allow, deny, allow once, allow while using) are resolved by role, in the device’s language:
tap "Don't Allow" in system dialogfinds “Nicht erlauben” on a German device. On iOS the labels are a table for the 55 locales of the iOS 26.5 runtime, read from the system’s own localization strings (the App Tracking Transparency decline is included). Android works in any language on the stock permission controller’s dialogs (OEM permission screens without those ids are not covered), matched by their language-independent resource ids. 27 of those iOS languages were also measured on real simulators: English, German, French, Spanish, Italian, Portuguese (BR), Dutch, Swedish, Danish, Norwegian (Bokmål), Finnish, Polish, Czech, Turkish, Russian, Ukrainian, Greek, Hebrew, Arabic, Hindi, Thai, Vietnamese, Indonesian, Japanese, Korean, Chinese (Simplified and Traditional). OK, cancel, not now, open and close are known only in English: in another language, use the exact label. An exact label always wins over a role. Matching also folds case, accents and typographic apostrophes (Don’t Allow=don't allow).
Notifications on iOS. The system keeps the Allow / Don’t Allow decision per app for good, and
simctlhas no command to reset it.deny permission "notifications"therefore reinstalls the app (from a copy of its own bundle) when the app is not running: it asks first, as a clear does, because the reinstall deletes the app’s data (its keychain items are kept), so the next launch asks again. With the app running it answers the alert. In a parallel or composite run it needs--yes.simctl privacy reset allleaves the decision as it was (measured on a simulator). Use it inbefore each testafterkill the appfor first-run permission tests.
Some UI is not part of your Flutter app: iOS permission alerts, the StoreKit Sign in to Apple Account sheet, Android’s permission dialogs. They are drawn by the operating system, so the on-device Dart agent can neither see nor tap them. FlutterProbe drives them from outside the app:
| Platform | How | Needs |
|---|---|---|
| iOS simulator | a small XCUITest runner (“iOS driver”) that reads SpringBoard’s accessibility tree | macOS with Xcode |
| Android emulator / device | uiautomator dump + adb input |
adb, and no other UI-automation tool running |
Physical iOS devices are not supported (an XCUITest runner there needs code signing). The feature is optional: a normal test run never starts the driver.
ProbeScript steps
Section titled “ProbeScript steps”tap "Allow" in system dialogtap "OK" in system dialog "Apple Account" # optional title filtertype "$PROBE_SANDBOX_PASSWORD" into system field "Password"see system dialog "Sign in to Apple Account"don't see system dialog "Notifications"wait for system dialog "Notifications" appears # or: disappearsdismiss system dialogsign in sandbox testertap "Allow" in system dialog optional- Button and field matching is case-insensitive, exact first and then “contains”, and treats
’and'as the same, sotap "Don't Allow"matches iOS’s “Don’t Allow”. - Title filter: an optional second string narrows to a dialog whose text contains it. Without one, the first system dialog is used.
dismiss system dialogtaps the first of Cancel, Don’t Allow, Not Now, Close, Dismiss, Later, No Thanks, Ask App Not to Track (the decline button of the App Tracking Transparency alert, in the 55 iOS locales of the iOS 26.5 runtime). It does nothing (and passes) when no dialog is showing.tap "Don't Allow"on the App Tracking Transparency alert taps its decline button (“Ask App Not to Track”, or its translation). Both have the deny role, so this is the intended match: the decline is the deny button of that alert.- Notifications and the tracking alert.
allow permission "notifications"anddeny permission "notifications"never answer the App Tracking Transparency alert. While that alert is on screen they skip the notification alert, and if it is still showing when they stop waiting they print a warning and change nothing. optionalon any step turns “no dialog showed up” into a warning instead of a failure, which keeps flows idempotent.- Failures say what is showing:
... (showing: "Allow Notifications?" [Allow | Don’t Allow]).
The iOS share sheet
Section titled “The iOS share sheet”When your app opens the standard share sheet (UIActivityViewController, for example from a Flutter share action),
the sheet covers the app but is drawn by a system process. On an iOS simulator list, see, wait, tap and
dismiss handle it like any other system dialog:
probe system-dialog list# • <the shared item's caption, or "Share sheet"># buttons: <share targets and actions, e.g. Copy | Save to Files | ...>probe system-dialog see --title "Share sheet"probe system-dialog tap "Copy"probe system-dialog dismisssee system dialog "Share sheet"dismiss system dialog- Detection needs the app’s bundle id, so the driver can look inside that app: it is taken from
project.appinprobe.yaml(or--app <bundle-id>onprobe system-dialog). Without it only SpringBoard’s alerts and system service sheets are seen, andlistsays “No system dialog is showing.” - Title: the shared item’s caption shown at the top of the sheet. The text
Share sheetalways matches, whatever is shared, sosee system dialog "Share sheet"is a stable check. - Buttons are the sheet’s Close button (on iOS versions that draw one) plus every share target and action in it
(
Copy,Save to Files, an installed app’s name, …). Labels are the device’s, so they follow the simulator’s language. dismisstaps Close if the sheet has one; otherwise it taps the dimmed area above the sheet and, if the sheet is still there, swipes it down. It does nothing when no sheet is showing.- Alerts and the other system dialogs behave exactly as before.
Secrets
Section titled “Secrets”type "..." into system field "..." takes the text from an environment variable ($NAME or ${NAME}) or a
literal. Because a literal could be a password too, everything typed into a system field is masked: the step is
shown as type "****" into system field "Password" in output and reports, and the value is scrubbed from any error
text. A missing or empty variable fails the step by name, never by value. Values are sent only to the local driver
on loopback.
StoreKit sandbox sign-in
Section titled “StoreKit sandbox sign-in”A fresh simulator asks to sign in to the App Store the first time your app touches StoreKit. Provision a sandbox tester once; the account lives in the simulator’s data and survives app reinstalls.
sign in sandbox testerIt waits briefly (about 5 s) for the sheet, types PROBE_SANDBOX_USER and PROBE_SANDBOX_PASSWORD, taps OK and
waits for the sheet to close. If no sheet appears it does nothing, so it is safe at the start of every test. If
the sheet stays open, it fails with a hint to check the tester credentials.
The same thing, with no test file and no Flutter app (handy for provisioning a CI simulator):
export PROBE_SANDBOX_USER='tester@example.com'export PROBE_SANDBOX_PASSWORD='...' # from your secret store; never on the command lineprobe system-dialog sign-in-sandbox --device <simulator-udid>Notification permission
Section titled “Notification permission”iOS has no simctl service for notifications, so allow permission "notifications" and
probe test --grant notifications answer the system alert instead: the first taps Allow if the alert is up
within a few seconds (a no-op if the permission was already decided), the second keeps a watcher running that taps
Allow whenever the alert appears during the run. deny permission "notifications" taps Don’t Allow.
The probe system-dialog command
Section titled “The probe system-dialog command”probe system-dialog list # titles, buttons and fields of what is showingprobe system-dialog see --title Notifications # exit 0 if showing, 1 if notprobe system-dialog tap "Allow"probe system-dialog wait --title Notifications --gone --timeout 10sprobe system-dialog dismissprobe system-dialog type --field Password --env PROBE_SANDBOX_PASSWORD # or --stdinprobe system-dialog sign-in-sandbox--device <udid-or-serial> picks the target (default: the only booted/connected device). --app <bundle-id> names
the app whose share sheet to look for (default: project.app), and --driver-port sets the iOS driver port (below). The value for type is
accepted from --env NAME or --stdin only, never as an argument, so it cannot show up in ps or shell history.
The iOS driver
Section titled “The iOS driver”The runner is built in CI on every release and attached as probe-ios-driver.zip. The first use on a machine
downloads it into ~/.probe/ios-driver/<version>/; you can do it ahead of time:
probe ios-driver installprobe ios-driver status --device <udid>probe ios-driver stop --device <udid> # normally not neededprobe starts it with xcodebuild test-without-building on the simulator (about 5 seconds, once per run), talks
to it over a loopback-only HTTP port (derived from the simulator’s UDID unless you set one), and stops it when the run ends. If the CLI
dies, the runner stops itself after a safety timeout.
Choosing the driver port
Section titled “Choosing the driver port”By default each simulator gets a loopback port derived from its UDID (48790 to 48989). If your CI reserves port ranges per test lane, pin it:
agent: driver_port: 49100 # 1024-65535probe test tests/ --driver-port 49100probe system-dialog list --driver-port 49100probe ios-driver status --device <udid> --driver-port 49100The flag wins over agent.driver_port; with neither, the derived port is used. Values outside 1024-65535 are
rejected before anything starts. One port serves one simulator, so use it for single-device runs; parallel runs
(--parallel, --composite-device) keep the derived per-simulator ports.
| Variable | Purpose |
|---|---|
PROBE_IOS_DRIVER_DIR |
use a runner build from this directory (e.g. one you built with make ios-driver) |
PROBE_HOME |
move ~/.probe |
PROBE_DRIVER_APPS |
extra bundle ids whose UI counts as a system dialog (comma-separated) |
PROBE_ANDROID_DIALOG_PACKAGES |
extra Android packages to treat as system dialogs |
To build the runner yourself: brew install xcodegen && make ios-driver (produces bin/probe-ios-driver.zip; the
source is in ios-driver/).
Troubleshooting
Section titled “Troubleshooting”wait for system dialog appearstimes out (Android) — the message now says what the device reports instead of leaving you to guess: the focused window (package/activity), the grant state of the permission the dialog is about (mapped from words in the title, such as “notifications” or “camera”; without a title, the app’s denied runtime permissions), and a hint. When the focused window is the app itself and the permission is denied, the app never asked: “no system dialog was requested”, which is an app or flow problem, not a driver one (for example a build mode that skips the request). When another window has the focus, checkPROBE_ANDROID_DIALOG_PACKAGES. The same text is added toprobe system-dialog wait. iOS reports the dialogs that are showing, as before.- “no system dialog found” — run
probe system-dialog listwhile the dialog is up. If it is empty, the dialog belongs to a process the driver does not look at: find its bundle id and setPROBE_DRIVER_APPS. - “the simulator’s accessibility service is not responding” (xcodebuild exit 65, “Timed out waiting for AX loaded notification”) — the XCUITest runner could not start because the simulator’s accessibility service is wedged, which can happen after another UI-test tool used the same simulator. Without this message the failure shows up later as unrelated step timeouts. Restart only the test simulator (
xcrun simctl shutdown <udid> && xcrun simctl boot <udid>) and rerun; run the Probe lane before other UI-test tools on that simulator, or restart it between them. The driver now reports this directly, both when it fails to start and when it stops during a run. - “needs Xcode” — install Xcode and run
sudo xcode-select -s /Applications/Xcode.app. - Android: “uiautomator … killed” — only one UI-automation client can run per device. Stop Maestro’s driver or another uiautomator session on that device.
- Android typing —
adb shell input texttypes ASCII only. Spaces and shell characters (& ; $ ' ") in the value are handled; emoji and non-Latin text are not. - Cloud devices and physical iOS — not supported; the steps fail with a message saying so.
Compared with Maestro
Section titled “Compared with Maestro”Maestro drives the same dialogs through its own on-device driver. FlutterProbe’s version is deliberately narrower: dialogs only (not arbitrary native UI on iOS), simulators only on iOS, and an explicit secrets model. For Flutter UI you keep using the normal ProbeScript steps, which are far faster than accessibility-tree driving.