In Appium on Android, what do appium:avdArgs and appium:isHeadless change about the emulator it starts?

## What these two capabilities actually touch Both capabilities configure one narrow moment: the point where the Android drivers **launch** the virtual device named by `appium:avd`. They do not configure the running system, the app under test, or the automation session. Internalise that single fact and every surprising behaviour around them stops being surprising. The sequence on the Android side of a hearing-aid fitting run is: 1. The session arrives naming an AVD with `appium:avd`. 2. If no emulator for that AVD is running, the drivers launch one — this is where `appium:avdArgs` and `appium:isHeadless` are consumed. 3. The emulator is reached over adb like any other Android target. 4. The on-device helper server is pushed and started, the build is installed, commands begin. Steps 3 and 4 are identical for an emulator and a physical phone. Steps 1 and 2 are the only part of the run that these capabilities exist for. ## appium:avdArgs — arguments for a launch you own `appium:avdArgs` is a passthrough: whatever you put there is handed to the emulator on the command line when the driver starts it. It is the escape hatch for launch behaviour Appium has no dedicated capability for, and it inherits every property of an escape hatch: - It is **not validated by Appium**. A bad argument is the emulator's problem, and the failure surfaces as a target that never becomes ready rather than as a clear capability error. - It is **coupled to the emulator tooling** rather than to Appium, so it is the part of a capability block most likely to rot when the host's SDK tooling moves. - It is **inert whenever the driver did not launch the emulator**, which includes the very common case of a developer who already has one open. Because of the last point, a suite that depends on a specific launch argument must also own the emulator's lifecycle. "Sometimes launched by the driver, sometimes attached to" is exactly the configuration that makes a run behave differently on a developer machine than on a shared one. ## appium:isHeadless — a window, not a rendering mode `appium:isHeadless` starts the emulator with no window on the host. The important half of that sentence is *on the host*. It is not the browser sense of headless: the guest Android system is still a complete system, the app still draws, and the session still interacts with a real view hierarchy. What you give up is a human being able to watch it. That matters for triage. Losing sight of the screen is not the same as losing evidence — Appium has its own capture surface for that — so treat headless as a property of the host environment, not as a reduced mode of the device. ## The Apple side of the same question There is no `appium:avdArgs` twin on the Apple side, and the reason is structural rather than an oversight: there is no AVD and no emulator binary to hand arguments to. The XCUITest driver boots a simulator through `simctl`, and the capability that shapes that step is a **budget**, not an argument list — `appium:simulatorStartupTimeout` bounds how long the driver waits for the boot to finish before failing the session. The two platforms put their knob in different places: - Android: *how* the target is launched (`appium:avdArgs`), plus whether it shows a window (`appium:isHeadless`). - Apple: *how long* the driver will wait for `simctl` to bring a simulator up (`appium:simulatorStartupTimeout`). Do not write a capability block that assumes symmetry here. It is safer to state the Android launch shaping and the Apple boot budget as two separate things than to invent a shared abstraction over them. ## Using them without surprises - Set them only in the lane that actually launches emulators; they are dead weight anywhere else. - Decide explicitly whether the driver or the machine owns the emulator lifecycle, and write it down — the capabilities behave differently under each choice. - When an argument appears to do nothing, check first whether the emulator was already running, before you suspect the argument itself. - Keep `appium:avdArgs` short. Every argument in it is a coupling to host tooling that no Appium-side test can verify for you. - Remember that neither capability has any effect on a physical Android device, so a mixed lane silently ignores both. ## The failure shapes to recognise A bad `appium:avdArgs` usually looks like a target that never becomes ready: the session sits in launch and then fails, with nothing wrong in the test. A headless run that "cannot find the element" is almost never headless-related, because the guest system renders regardless. And a capability that looks ignored is, far more often than not, a capability that arrived after the emulator was already up.