Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 37 ยท Architecture and Setup

Appium Client-Server Architecture

See how an Appium command travels from your test through the HTTP server and driver to the device, and decode the W3C WebDriver requests it uses.

When your test calls element.click(), a surprising amount happens. The client library builds an HTTP request, the Appium server routes it, a driver translates it into a platform command, a helper process on the device performs the tap, and the answer travels all the way back. Understanding this path turns mysterious failures into simple questions: which layer failed?

This lesson follows one command through every layer and teaches you to read the underlying W3C WebDriver requests.

The layers

sequenceDiagram
  participant T as Test + client library
  participant S as Appium server (Node.js)
  participant D as Driver (UiAutomator2 or XCUITest)
  participant H as Helper on device
  participant A as App
  T->>S: POST /session/{id}/element/{eid}/click
  S->>D: click(eid)
  D->>H: HTTP call to helper server
  H->>A: perform tap via platform API
  A-->>H: UI reacts
  H-->>D: result
  D-->>S: null
  S-->>T: 200 {"value": null}

Figure: one click traveling through the stack.

  1. Client library. Wraps HTTP. Written in Python, Java, JavaScript, Ruby, C# and others. You never see the HTTP unless you enable logging.
  2. Appium server. A Node.js (Express-style) HTTP server. It validates the request, finds the session, and calls the right driver method. It also runs plug-ins.
  3. Driver. Knows one platform. Starts the helper, translates commands and handles setup like installing the app.
  4. Device helper. For Android, UiAutomator2 installs a small server APK (io.appium.uiautomator2.server) on the device that exposes automation over HTTP. For iOS, the XCUITest driver builds and runs WebDriverAgent (WDA), an app-like test bundle that exposes the same kind of interface.
  5. Platform framework. Android's UiAutomator and iOS's XCUITest do the real tapping, scrolling and tree reading.

Because of this design, a command can fail in any of five places, and error messages often tell you which.

The W3C WebDriver protocol

The server speaks the W3C WebDriver protocol, extended with Appium commands. Every endpoint is plain HTTP with JSON. The most important ones:

Purpose Request
Server status GET /status
New session POST /session
Find element POST /session/{sid}/element
Click POST /session/{sid}/element/{eid}/click
Type POST /session/{sid}/element/{eid}/value
Read text GET /session/{sid}/element/{eid}/text
Page source GET /session/{sid}/source
Screenshot GET /session/{sid}/screenshot
End session DELETE /session/{sid}

A find request body:

JSON
{ "using": "accessibility id", "value": "login" }

And the success response:

JSON
{ "value": { "element-6066-11e4-a52e-4f735466cecf": "c0f9a3e2-0d4b-4b5e-9d6e-2f1f8a9d8a11" } }

That odd key, element-6066-11e4-a52e-4f735466cecf, is the fixed identifier that the W3C standard uses for element references. Its value is an id assigned by the driver. When something goes wrong, the response is an error object:

JSON
{ "value": { "error": "no such element", "message": "An element could not be located on the page using the given search parameters.", "stacktrace": "..." } }

Appium-specific commands use the mobile: prefix through the execute script endpoint, for example driver.execute_script("mobile: shell", {...}). You will use that heavily in the platform lessons.

Where do I run what?

The client and server can be on the same machine or different ones. Typical setups:

  • Local. Test, server and emulator on your laptop. Server at http://127.0.0.1:4723.
  • CI. The build agent runs both; the device is an emulator or a connected phone.
  • Remote. The test runs anywhere; the server (yours, or a cloud provider's) is elsewhere and has the devices attached. The app capability then must point to a file on the server's machine, or a URL, because the server installs it.

That last point is a very common beginner mistake. A path like C:\builds\shop.apk means nothing to a remote server.

Decoding requests with a stand-in

Real servers route by pattern matching on method and path. The stand-in below does the same for a handful of routes, which is a good way to see how a URL becomes a command.

JS Stand-in: route W3C-style requests to commands

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Building a request the way a client does

A client library has a small table of commands and fills in ids. The next stand-in builds the full HTTP description for a command, so you can compare the shape with the table above.

JS Stand-in: build requests from commands

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Reading logs to find the failing layer

When a test fails, read the server log from the top of the failing command:

  • An error at session creation with messages about capabilities: client or capability problem.
  • Messages mentioning adb, emulator or xcrun: environment problem on the server machine.
  • A timeout waiting for the helper (UiAutomator2 server or WebDriverAgent) to start: device, signing or port problem.
  • no such element after a successful find earlier: timing or the screen changed.

Starting the server with appium --log-level debug prints every request and response. It is noisy but invaluable.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is WebDriverAgent?

    The XCUITest driver builds and launches WebDriverAgent on the simulator or device, and talks to it over HTTP.
  2. 2. Which request creates a session?

    POST /session with a capabilities body starts a new session; DELETE /session/{id} ends it.
  3. 3. You run the server on a remote machine and set app to C:\builds\shop.apk on your laptop. What happens?

    The server installs the app, so paths are resolved on the server side.
  4. 4. How do Appium-specific commands such as mobile: shell reach the server?

    Extension commands are sent via execute script, e.g. driver.execute_script('mobile: shell', args).

Summary

  • A command passes client, server, driver, device helper and platform framework.
  • The protocol is W3C WebDriver over HTTP and JSON, extended with mobile: commands.
  • Element references use a fixed W3C key; errors have a standard error name.
  • Paths in capabilities are resolved on the server machine.
  • Debug-level server logs show every request and help find the failing layer.

Next: Installing the Appium Server