Client Bindings

## Three release trains, deliberately Appium's client, its server and each driver are published separately, and the split is a design choice rather than an accident. A driver has to move quickly, because Android's and Apple's tooling moves and the driver follows. The protocol between client and server moves slowly, because it is W3C WebDriver plus a small, stable set of Appium extensions. Coupling the client's release to the driver's would drag the slow-moving part along behind the fast-moving one, for no benefit to anybody. The consequence is exactly the situation in the question: a driver publishes a command your client release predates. Answering it well means naming which artefact has to move, and — just as important — which ones do not. ## What a new driver command actually needs Nothing in the client. To the client, a `mobile:` command is a string and a map: - The name sits in the script slot as a string; the library never validates it and does not know it. - The parameters are one map, serialised as-is. - The reply comes back as generic JSON and is decoded into a map, a list or a scalar. Because none of that involves the command's identity, an older client encodes a brand-new command exactly as well as a brand-new client does. What must be current is the **driver installed on the Appium server**, since that driver is the only thing that can answer the name at all — plus, where the driver requires it, the server generation that driver runs on. The inverse is the more common misconception and is worth stating flatly: **upgrading the client never adds driver behaviour.** No client release can make a command exist that the driver on the other end does not implement. ## What genuinely requires a client upgrade The client has to move for protocol-shaped changes and for convenience, not for driver features: - A new or changed W3C endpoint the client has no method for at all. - A change to how a session is created, or how capabilities are serialised on the way out. - A serialisation or decoding fix in the client, or in the Selenium client beneath it. - A typed helper you would rather use than a raw execute call. - Support for a language or runtime version your project has moved to. That list is short, and it is why suites routinely run a client several releases behind a fast-moving driver with no trouble at all. ## Reading a failure back to its artefact | Symptom | Most likely artefact | First thing to check | |---|---|---| | Server rejects a `mobile:` name as an unknown method | the driver in that session | which driver created the session, and its command surface | | The command runs but rejects your parameters | your parameter map | the key names and shape that driver expects | | No client method exists for a standard endpoint | the client | whether that endpoint is newer than your client pin | | Session creation itself fails | the client or the capability map | how the client serialises the capabilities you set | | Answered on Android but unknown on Apple devices | neither — this is attribution | each driver publishes its own command names | The last row is the one that most often masquerades as version skew. A name owned by Android's UiAutomator2 driver is simply unknown to Apple's XCUITest driver, and no client version changes that. ## A worked case A physiotherapy exercise app suite runs the same journeys on Android's UiAutomator2 driver and on Apple's XCUITest driver. Someone adds a step that needs a driver command introduced after the team's `java-client` pin. The instinct is to bump the client dependency, which means re-validating the whole matrix for a change that could not possibly have helped: the client would have encoded the same string either way. The change that mattered was on the server side — the installed driver had to be the release that owns the command. Once the team sees that, the client pin stays where it is, the upgrade touches one artefact, and the validation burden shrinks to that artefact's behaviour. ## A pinning policy worth defending 1. Pin all three — client, server and driver — explicitly, so any environment difference is a readable diff rather than a guess. 2. Move the driver on its own cadence, because that is where new device behaviour arrives. 3. Move the client for protocol or language reasons, and treat a client bump as its own change with its own validation. 4. Before bumping anything, classify the failure by artefact using the symptoms above; most "our client is too old" reports turn out to be driver or attribution problems. 5. Record which driver release a given command depends on, because the client cannot express that dependency for you and your build will not warn you about it.