WebDriverAgent vs Appium

A common scenario for using the xcuitrunner is to launch WebDriverAgent on your iOS device. The xcuitrunner ships with the Appium flavor of WebDriverAgent, which is launched by default, unless you specify another copy of WebDriverAgent.

What is WebDriverAgent

The WebDriverAgent is an open source WebDriver server implementation for iOS that can be used to remotely control iOS devices. WebDriverAgent is maintained by Facebook.

How Appium uses WebDriverAgent

Appium adopted WebDriverAgent to implement test automation on iOS devices. Over time, Appium started to maintain its own flavor (or fork) of WebDriverAgent. The Appium flavor of WebDriverAgent tends to evolve faster and include more functionality than the original version from Facebook.

Whenever your start a test automation session on an iOS device, Appium will install WebDriverAgent on your device. When you request Appium to execute commands (such as finding an element or clicing on one), Appium forwards these commands to WebDriverAgent running on your iOS device.

In most scenarios, Appium acts as a very thin ‘front-end’ to WebDriverAgent. In some cases, Appium intercepts your commands and preprocesses them. Appium uses a plugin system to support multiple operating systems. Each plugin is called a ‘driver’. The Appium driver which uses WebDriverAgent is called appium-xcuitest-driver and is available on GitHub.

How xcuitrunner uses WebDriverAgent

xcuitrunner installs and launches WebDriverAgent on your mobile device, and provides you with a HTTP endpoint you can use to communicate directly with WebDriverAgent.

xcuitrunner is cross-platform - it runs on Windows, Mac and Linux, and takes care of code signing for you. There’s no dependency on Xcode.

xcuitrunner does not preprocess any commands you send to WebDriverAgent. Sending commands directly to WebDriverAgent is in most cases similar to sending those commands to Appium, but not all.

Known differences between Appium and WebDriverAgent

This section highlights commonly encountered differences between Appium and WebDriverAgent:

  • Implicit Waits. Implicit Waits are not implemented by WebDriverAgent. If you want to use implicit waits, you can implement polling logic in your methods which execute the ‘Find Element(s)’ commands.
  • Application management. The /appium/app/launch command is replaced by the /wda/app/launch command. The POST /appium/app/reset command is not implemented. You can use ideviceinstaller to obtain similar behavior.
  • Launching sessions. WebDriverAgent has the concept of a default session. We recommend you connect to the default session instead of creating a new session. You can obtain the Session ID of the default session by connecting to the /status endpoint.
  • Window size and location. The /window/current/size command is not implemented. Use GET /window/size instead. The /element/:elementId/location and /element/:elementId/size commands are replaced by a single GET /element/:elementId/rect command, which includes both the location and size of the element.
  • Hiding the Keyboard. The /appium/device/hide_keyboard command is replaced by the /wda/keyboard/dismiss command. In certain scenarios, this command may not work correctly and a workaround is needed.