appium

name

appium

description

Use for dynamic inspection and navigation of the Blokada app through the repo-local Appium machine session. Trigger when Codex needs to explore the live native UI on a real device, inspect labels or structure, tap through screens, capture screenshots or XML on demand, or verify interactive behavior without writing a static WDIO spec. The current workflow is implemented for iOS, but the skill name stays generic so it can later cover other Appium-backed platforms too.

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.

Command guidance

Prefer ui.summary first:

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

Use ui.inspect for bounded structure:

{"id":"2","command":"ui.inspect","args":{"labels":true,"tree":true,"limit":40}}

Use generic navigation and reads for dynamic exploration:

{"id":"3","command":"ui.search","args":{"text":"keyboard"}}
{"id":"4","command":"ui.tap","args":{"selector":"~Keyboard"}}
{"id":"5","command":"ui.read","args":{"selector":"~Auto-Correction"}}
{"id":"6","command":"ui.back","args":{}}
{"id":"7","command":"ui.scroll","args":{"direction":"down"}}

Use raw WDIO/Appium selectors directly:

{"id":"8","command":"ui.tap","args":{"selector":"~Privacy Pulse"}}
{"id":"9","command":"ui.wait","args":{"selector":"~Avancerat","timeoutMs":10000}}
{"id":"10","command":"ui.attr","args":{"selector":"~automation.power_toggle","name":"value"}}

Switch between the built-in app targets without restarting Appium:

{"id":"11","command":"app.targets","args":{}}
{"id":"12","command":"app.activate","args":{"target":"family"}}
{"id":"13","command":"ui.summary","args":{}}
{"id":"14","command":"app.activate","args":{"target":"settings"}}
{"id":"15","command":"app.activate","args":{"target":"six"}}

For dynamic Settings work, prefer discovery over a maintained path catalog:

• switch to settings
• use ui.summary and ui.inspect to see the visible hierarchy
• use ui.search if the screen exposes a search field
• open rows and read switches dynamically with ui.tap and ui.read

Lightweight hint only: DNS is usually under General, then VPN & Device Management, then DNS, but use the live hierarchy instead of assuming labels or locale.

Practical DNS notes:

• Treat DNS as a top-level system setting reached from Settings -> General -> the VPN/DNS management area. The exact row labels depend on locale, but it is not an app-specific setting under the Blokada app entry.
• A failed Settings search for DNS is not enough to conclude the path is unavailable; prefer live hierarchy discovery.
• If tapping the visible VPN/DNS management row is unreliable, try the accessibility id when present.
• If the task is to put DNS "back", first verify the current selection on the DNS screen. If Automatic is already selected, leave it unchanged instead of toggling away and back.

Capture artifacts only when needed:

{"id":"16","command":"ui.screenshot","args":{"name":"settings-screen"}}
{"id":"17","command":"ui.source","args":{"name":"settings-screen"}}

System alerts (notification / location / etc.)

iOS system permission alerts live in SpringBoard, not the foreground app. ui.tap (selector or coordinate) cannot reach them — the alert is outside WDA's app-scoped accessibility tree, and a coordinate tap lands "underneath" the alert in the app's coordinate space.

Use ui.alert instead, which wraps WDA's mobile: alert extension and operates on the system alert layer:

{"id":"1","command":"ui.alert","args":{"action":"getButtons"}}
{"id":"2","command":"ui.alert","args":{"action":"accept","buttonLabel":"Tillåt"}}
{"id":"3","command":"ui.alert","args":{"action":"dismiss"}}

• action: accept (positive button) | dismiss (negative button) | getButtons (return the button labels for diagnostics)
• buttonLabel (optional): pick a specific button by visible label. Useful for localized alerts where "Allow" vs "Tillåt" vs "Erlauben" differs by sim locale.

If ui.alert returns "An attempt was made to operate on a modal dialog when one was not open", the alert hasn't materialized yet. Sleep briefly and retry, or send the user-action that triggers it first.

Flutter widget taps (when element.click() is a no-op)

Flutter often exposes interactive widgets as XCUIElementTypeStaticText (no Semantics(button: true)). ui.tap with a selector calls element.click(), which targets the accessibility element but doesn't dispatch the underlying GestureDetector callback. The tap reports success but nothing happens in the app.

Use ui.tapCenter for these — it resolves the element's on-screen rect and dispatches a real touch via mobile: tap:

{"id":"1","command":"ui.tapCenter","args":{"selector":"~Aktivera"}}

Quick diagnosis: if ui.tap ~Foo reports tapped but the app's log shows no trace of the expected callback, switch to ui.tapCenter with the same selector.

Cross-worktree sim targeting

By default the harness reads the per-worktree sim from make -C ios sim-status. To drive a sim that was provisioned by a sibling worktree (without reprovisioning a new sim in this worktree), set IOS_UDID (and optionally IOS_DEVICE_NAME):

IOS_USE_SIM=1 \
IOS_UDID=83114086-0934-4944-A01C-7955DB91B0A8 \
IOS_DEVICE_NAME="iPhone 16 - other-worktree" \
APP_FLAVOR=family APP_INSTALL=0 \
make appium-explore-session

This is the path for: edit harness scripts in worktree A, drive the existing app/sim from worktree B without rebuilding.

Cleanup

Always send:

{"id":"999","command":"session.shutdown","args":{}}

The intended behavior is that shutdown removes active automation from the phone without discarding reusable WDA state. If the iPhone still shows Automation Running, treat it as a harness cleanup bug and use an explicit hard reset rather than normalizing full WDA teardown after every run.