App and Device Control

Sending browserName instead of an application makes the phone's own browser the app under test: Chrome on Android, whose page commands a Chromedriver answers, and Safari on iOS, driven by XCUITest through Apple's remote web inspector.

Both platforms share the WEBVIEW_ prefix and then diverge: Android appends the package name of the process hosting the web view, while iOS appends a numeric page id that the remote debugger assigns at runtime.

Both sides share mobile: activateApp to foreground an app, mobile: backgroundApp to suspend it, mobile: terminateApp to stop it and mobile: queryAppState to check it. Android adds mobile: startActivity; Apple platforms add mobile: launchApp and mobile: killApp.

It tells the Android drivers to grant every permission the app declares as part of installing it, so no runtime prompt ever appears. It is an install-time switch decided at session start, and the XCUITest driver has no equivalent.

On Android the Android drivers expose mobile: changePermissions, which grants or revokes a permission on an installed package. On Apple platforms the XCUITest driver exposes mobile: setPermission, which writes a decision for a bundle and only works on a Simulator.

browserName makes each driver start the platform's own browser and wire a web bridge to it: the Android drivers launch Chrome and proxy page commands to Chromedriver, while XCUITest launches Safari and drives it through Apple's remote web inspector.

Appium's mobile: clearApp wipes an installed app's stored data without reinstalling it. On Android the driver runs a package-data clear (pm clear) on the package; on iOS the XCUITest driver deletes the app's data container, and only on a Simulator.

Android's UiAutomator2 driver names the receiving app with package; Apple's XCUITest driver names it with bundleId. Both sit in the same parameter map beside url, and both exist to stop the operating system resolving the URL to some other app.

Because they run on different machinery. The XCUITest driver's mobile: setPermission and mobile: getPermission drive Simulator-only facilities on the host, while mobile: resetPermission proxies to WebDriverAgent's /wda/resetAppAuth, which runs on the device itself.

Drive the browser when the subject is the web property itself on a phone: the session asks for a browser, installs nothing, and starts on the page. It means Chrome on Android and Safari on iOS.

On Android mobile: clearApp runs a package-data clear, so the app's databases, preferences, caches and files go and it returns to a first-run state. The app stays installed, its process is stopped, and anything outside the package survives.

Because the sign-in token lives in the iOS keychain, which sits outside the app data container that mobile: clearApp deletes. XCUITest ships mobile: clearKeychains for that store, and it is Simulator-only as well.

Use mobile: activateApp when the case wants the app as a whole, resumed or started at its normal entry point. Use Android's mobile: startActivity only when the case must land on one named screen directly, accepting the coupling that creates.

Build the helper on the four commands both platforms answer, and expose the platform-only commands as explicit, platform-named operations. Never let an operation silently do nothing on the platform that cannot perform it.

Two requests do it, and they are the same on both platforms: GET /session/:sessionId/contexts returns the available handles, and POST /session/:sessionId/context with a name enters one. Only the handle values differ per platform.

Appium uses one name on both: the execute method mobile: deepLink, declared by Android's UiAutomator2 driver and by Apple's XCUITest driver. The plain WebDriver route POST /session/:sessionId/url does the same job from a native session.

Both platforms use the same three execute methods: mobile: installApp puts a build on the target, mobile: removeApp takes it off, and mobile: isAppInstalled reports whether it is there. The artifact and the identifier you pass differ per platform.

Android needs a Chromedriver binary matching the device's Chrome or System WebView, which Appium's Android drivers start and proxy to. iOS needs no binary: the XCUITest driver attaches to the remote debugger, so the web view must be debuggable.

A system dialog is drawn by the operating system, not by your app, so nothing in your build sets its ids or text. Both drivers therefore expose out-of-band alert commands: UiAutomator2's acceptAlert and dismissAlert on Android, XCUITest's alert on iOS.

It changes where a session begins. Without it, a new session starts on the native surface, NATIVE_APP, on both Android and iOS; with it, the driver enters a detected web-view context as the session comes up.

It performs deep-link entry. Both mobile drivers answer WebDriver's navigation route from a native session by handing the URL to the device: Android starts an android.intent.action.VIEW intent, Apple platforms open the URL through simctl or WebDriverAgent.

On Android the drivers hand the artifact to their adb layer, which transfers it and drives the platform package installer. On Apple platforms the XCUITest driver installs through simctl for a simulator and devicectl for a real device.

It returns one integer from an ordered ladder: 0 not installed, 1 not running, 2 background suspended, 3 background, 4 foreground. Both the Android drivers and the XCUITest driver answer it, but they derive the value from different evidence.

Chromedriver only supports a narrow range of Chrome and Android System WebView builds, so Appium's Android drivers need one that fits the device. Supply an exact path, a folder of builds to choose from, or let the autodownload feature fetch it.

On iOS, appium:nativeWebTap makes XCUITest perform a real native tap at the web element's translated screen coordinates instead of clicking it inside the page, which is closer to a finger but depends on translating page coordinates past Safari's own chrome.

Pick by evidence, not by position: read the per-view detail mobile: getContexts returns and match on the view's title or URL. Android names a handle after the hosting process, while iOS names it with a page id that changes each run.

The session is almost certainly still on the native surface, where the driver cannot see page markup. List the session's contexts, confirm which one is current, switch into the web-view handle, then retry the find.

Establish which application received the URL before blaming the app. On Android read the foreground package and activity and check the call named package; on Apple platforms check bundleId, and whether simctl or WebDriverAgent delivered it.

Separate the artifact from the target. On Android, check the build's shape and remove a conflicting package before retrying. On an iPhone, check the artifact is a device build rather than a Simulator one, and that the driver reaches the device.