For an Appium suite, when should capabilities ship the artifact rather than name an installed build?

## Two ways to point a session at a build Everything in this leaf reduces to one choice, made in the capability set and nowhere else: - **Ship the artifact.** `appium:app` names an `.apk` or `.apks` for the Android drivers, or an `.ipa` or `.app` bundle for the XCUITest driver. The identity - the package name or the bundle id - is read out of that artifact. - **Address an installed build.** `appium:appPackage` on Android or `appium:bundleId` on iOS, with `appium:app` absent. Nothing is delivered; the session works with whatever the device holds under that identity. Both are legitimate. They buy different things and they hand you different problems, and a suite that never decided which it is doing usually ends up with the weaknesses of both. ## The trade in one table | | Ship the artifact | Address the installed build | |---|---|---| | what the run proves | this exact artifact was exercised | only that something under that identity ran | | session start cost | an install, every session, every worker | none | | what must be reachable | the artifact, from the Appium server's host | nothing beyond the device | | who owns device contents | the capability set | whoever provisioned the fleet | | how drift shows up | it cannot | as a green run on old code | | platform asymmetry | Apple builds must be signed for the target device; Android artifacts are a single file, so URLs are simpler | the same on both: identity is just a string | ## When shipping the artifact is the right call - **The build changes on every run.** A pipeline that has just produced the laundry pickup artifact should hand that artifact to the session, not hope a device has it. - **Failures have to be attributable.** If a report has to say which binary failed, the capability set is the only place that fact can come from. - **Devices are not yours to trust.** Shared hardware, recycled emulators and anything you did not image yourself is unmanaged state. - **The suite is the gate.** When a red run blocks a release, the run has to be about a known binary. ## When addressing an installed build is the right call - **Session start time dominates.** With many short sessions across many workers, per-session installs can outweigh the tests themselves. - **Provisioning is already a controlled, separate step.** If installing the build is an explicit stage that runs once and records what it installed, the sessions afterwards do not have to repeat it. - **The run is exploratory.** Reconnaissance against a device someone already prepared does not need the delivery machinery. - **The artifact cannot travel.** If the build cannot practically be moved to the server's host for every session, addressing an installed copy is what remains. ## The hybrid most suites converge on 1. **Install once, deliberately.** When the build changes, run one provisioning step per device with `appium:app` set and `appium:enforceAppInstall` set to `true`, so the delivery is unconditional and logged. 2. **Address by identity afterwards.** The suite's sessions then carry `appium:appPackage` or `appium:bundleId` and start immediately. 3. **Record what was installed.** The provisioning step is the only moment that knows the version; make it emit that into the run's output. 4. **Re-provision on any doubt.** A device that has been power-cycled, re-imaged or borrowed goes back through step 1 rather than being assumed good. This keeps the fast path fast while leaving exactly one place responsible for build provenance - and it keeps that place explicit rather than resting on per-driver install defaults, which are each driver's own choice on Android and on iOS. ## What to write down either way - **Both capability sets, in full.** Android and iOS differ in artifact type and in identity capability, so a single shared set is a fiction; write two and keep them side by side. - **`appium:enforceAppInstall`, explicitly.** Its value is a decision your suite makes, not a default it inherits. - **Where the artifact lives.** A path is resolved on the Appium server's host, so a shared server usually means a URL. - **What the device is assumed to hold.** If the suite addresses an installed build, say so out loud in the configuration, because otherwise the assumption is invisible until a run passes against the wrong binary. ## The failure this choice prevents The reason this is a lead-level decision rather than a formatting preference is the shape of getting it wrong. A missing artifact fails loudly and is fixed in minutes. A session that silently addresses a stale installed build passes, reports success and lets a broken change through - on both platforms, for the same reason, through capabilities that look perfectly reasonable in review. Choosing deliberately, and writing the choice into the capability set, is what makes that failure impossible rather than merely unlikely.