Appium

Appium

Use the repo-local machine session only. Do not create temporary WDIO debug specs for ad hoc inspection.

Start the session

Prefer the root make target:

make appium-explore-session IOS_DEVICE_NAME="<device-name>"

Important:

• In Codex, request elevated access before running the Appium explorer, install targets, or related device-discovery commands. These flows depend on xcrun device services, WebDriverAgent/Appium startup, and real-device interaction that the sandbox cannot reliably access.
• Do not assume the make target can auto-discover the device inside the sandbox. If you need the connected phone, run the command with elevated access from the start.
• When invoking repo make targets, keep the command prefix stable as make <target> ... and put any make variable overrides after the target, for example make appium-explore-session APP_INSTALL=0 SHOW_XCODE_LOG=0. Avoid shell-style env prefixes like APP_INSTALL=0 make ..., because they create unnecessary sandbox permission prompt variants.

Notes:

• This installs the current workspace build by default. Use this for reviews of current changes, startup behavior, cold-start behavior, notification handling, and other recent code changes.
• Use APP_FLAVOR=family when the primary app under test should be Blokada Family. The default primary flavor is Blokada 6.
• A session started with the default flavor only freshly installs Blokada 6. app.targets may still list family if Family is already on the device, but that is a reused install unless you also ran a fresh APP_FLAVOR=family session in the same turn.
• Use APP_INSTALL=0 only when you already installed the current workspace build in the same turn, or when you have high confidence the installed app still matches the code you want to inspect.
• APP_BUNDLE_ID may override the primary bundle id, but if it does not match the intended flavor, set APP_FLAVOR explicitly so the install target stays correct.
• IOS_DEVICE_NAME is the normal device selector for the current iOS flow.
• IOS_UDID is a low-level fallback only.
• Interactive sessions must preserve the device's current Auto-Correction and Predictive settings. Do not add Settings navigation to the tests for this; keep the fix in the Appium/WDA layer.
• Real-device sessions should normally reuse an existing WebDriverAgent if one is healthy. End the active session cleanly, but reserve a full device-side WDA kill for explicit recovery such as APPIUM_WDA_HARD_RESET=1.
• If you do not expect to continue testing immediately, always shut the session down before you step away. Do not leave a device sitting in automation mode with the Automation Running banner visible.
• Appium does not manage iOS auto-lock for us. Before a long session, set Auto-Lock to Never or the longest available value and keep the device unlocked before starting.
• The process stays open and accepts JSONL commands on stdin.

Simulator mode (mocked builds)

The same explorer drives an iOS Simulator running a Mocked / FamilyMocked build, not just a physical device. Use this when verifying mocked-scheme work (make run-{six,family}-mocked) where there is no real tunnel and no connected phone. Opt in with IOS_USE_SIM=1; the harness then resolves the per-worktree sim from make -C ios sim-status, uses simulator capabilities (Appium-managed WDA, no signing identity), and skips the devicectl device-discovery the physical path needs. None of the "request elevated access" / connected-iPhone notes above apply in sim mode.

# interactive JSONL session against the per-worktree mocked sim
IOS_USE_SIM=1 make appium-explore-session
# family flavor
IOS_USE_SIM=1 APP_FLAVOR=family make appium-explore-session
# reuse an already-installed/running mocked build, skip rebuild+reinstall
IOS_USE_SIM=1 APP_INSTALL=0 make appium-explore-session

Prerequisites and gotchas:

• make run-{six,family}-mocked must have created the sim first; appium-explore-session does not provision it.
• sim-status derives the sim name from SIM_BASE (default iPhone 17). If you created the sim with a non-default base, pass the same SIM_BASE here or the UDID will not resolve, e.g. IOS_USE_SIM=1 SIM_BASE="iPhone 15" make appium-explore-session.
• Run from the repo root (the target cds into automation/appium/wdio itself); do not run it from inside wdio/.
• See ios/SIMULATOR.md ("Appium targeting") for the full sim flow and a raw appium --udid ... fallback.

Drive the session

Send one JSON object per line to stdin. Wait for the terminal done or error event before sending the next command.

Request shape:

{"id":"1","command":"ui.summary","args":{}}

Response lifecycle:

• ack
• optional result
• terminal done or error

Use these commands:

• session.status
• session.shutdown
• app.targets
• app.launch
• app.activate
• app.terminate
• app.state
• ui.summary
• ui.inspect
• ui.tree
• ui.labels
• ui.read
• ui.tap
• ui.type
• ui.focusSearch
• ui.search
• ui.back
• ui.swipe
• ui.scroll
• ui.wait
• ui.exists
• ui.attr
• ui.source
• ui.screenshot

Default workflow

Use this sequence unless the task requires something else:

1. Request elevated access first so device discovery, install, Appium, and WebDriverAgent can talk to the connected iPhone.
2. Start with a fresh install by default so the app on device matches the current workspace.
3. Send session.status to confirm the session and app state.
4. If the app version/build on device is not clearly tied to the current workspace, stop and reinstall instead of trusting the existing install. For example: if you start a fresh six session and then switch to family, treat that Family app as untrusted unless you separately ran make appium-explore-session APP_FLAVOR=family.
5. Use app.targets when you need to switch between six, family, and iOS Settings without restarting the session.
6. Use app.activate with args.target, for example six, family, or settings.
7. Use ui.summary as the fast default inspection command while navigating the current foreground app. It now reports the verified foreground target and active app metadata instead of trusting app state alone.
8. Use ui.inspect when you need bounded structure details. By default it includes labels, a tree summary, and a structured visible-element list.
9. Use ui.read to normalize common element attributes such as value, enabled, visible, and switch-like boolean state.
10. Use ui.focusSearch, ui.search, ui.back, ui.swipe, and ui.scroll for dynamic system-app exploration without creating a temporary static spec.
11. Use ui.screenshot or ui.source only when you need artifacts.
12. Always finish with session.shutdown. This should end the active session without forcing a full WDA reset.
13. If you are done for now, do not keep the session open just to preserve reuse. Reuse matters between active test runs, but an idle phone should not be left showing Automation Running.

If the session drops unexpectedly, first suspect device auto-lock or lost foreground automation:

• unlock the device
• confirm whether the app is still installed / in foreground
• restart the explorer session once before concluding the app itself broke

If Appium never reaches JSONL command handling after install and the server log shows repeated /status socket hangups, iProxy ... Unexpected data, or WebDriverAgent xcodebuild code 65, treat that as a harness/WDA problem first:

• retry the explorer once
• inspect automation/appium/output/appium-explore-server.log
• do not treat the app under test as failed unless the same behavior also reproduces after WDA is healthy

When reporting findings from an interactive session, state whether the session used a freshly installed workspace build or a trusted reused install.