Deep Link Entry

## Why the argument exists at all Handing a device a URL is an ambiguous request. More than one installed application can claim the same URL, and the operating system, not your test, decides who gets it. Appium's deep-link command therefore lets you say which app should receive it. That single argument is what turns "open this URL somewhere" into "open this URL in the app under test", and it is spelled differently on the two platforms. ## The two parameter maps | | Android (UiAutomator2) | Apple (XCUITest) | |---|---|---| | the URL | `url` | `url` | | the target app | `package` | `bundleId` | | what that identifier is | the application's package name | the application's bundle identifier | | with no target named | the system resolves the view intent itself | the system's registered handler takes the URL | | extra argument | `waitForLaunch` | none of the same shape | Both maps are posted the same way — a script name plus one parameter map on `POST /session/:sessionId/execute/sync` — so from the client's point of view only the map changes. That is exactly why the divergence is easy to miss until a run fails on one platform and passes on the other. ## Android: naming the receiver of a view intent On Android the driver asks the system to start an `android.intent.action.VIEW` intent carrying the URL, reaching the device through `adb` on the host. What `package` does is aim that intent: - With no `package`, the system resolves the intent against every app that can handle the URL. - For a custom scheme that only your app claims, resolution usually still lands correctly. - For an `https` URL the field is crowded, and a browser is a very plausible winner. - With `package` set, the intent is aimed at that application, so the resolution question never arises. - `waitForLaunch` is about timing, not targeting: it controls whether the driver waits for the started component to hand control back before the command returns. A useful way to hold it: `package` decides **who** receives the URL and `waitForLaunch` decides **how long the command lingers**. Neither one waits for your screen's content. ## Apple platforms: naming the app that opens the URL On Apple platforms the driver hands the URL to the operating system and the registered handler opens it. `bundleId` names the application that should do the opening. The route to the OS is not the same on every target: - On a Simulator, the driver goes through `simctl`. - On a real device, it goes through WebDriverAgent. - Both paths end with the OS opening the URL, but they fail differently, which matters when the same suite runs on a Simulator locally and on hardware in a lane. As on Android, naming the app is the difference between a deterministic entry and one that depends on what else happens to be installed on that device. ## Two traps that catch mid-level candidates 1. **Treating these as capabilities.** `package` and `bundleId` here are arguments inside an execute method's parameter map. They are not session capabilities and carry no `appium:` prefix. A candidate who reaches for the capability names instead is describing a different mechanism at a different point in the session's life. 2. **Assuming one name covers both platforms.** Putting `package` into an Apple session's map, or `bundleId` into an Android one, produces a call the driver does not read as a target — and the confusing outcome is not an error but a URL that opens somewhere else, followed by a find that fails on an unrelated screen. ## What this means for a cross-platform suite The honest shape of a shared helper is: one URL, one per-platform identifier, one branch that builds the map. - Keep the deep-link URLs themselves in one place, since they are usually the same string on both platforms. - Keep the Android package and the Apple bundle identifier beside each other in configuration, because the helper needs whichever matches the running session. - Do not abstract the argument name away behind a single invented key; the divergence lives in the driver's signature, and hiding it only moves the failure later. - Always follow the call with a wait on an element of the destination screen, on both platforms. Said compactly in an interview: same method, same URL argument, different target argument — `package` on Android because the driver is aiming an intent, `bundleId` on Apple platforms because the driver is naming the app that should open the scheme.