WebDriverAgent: WebDriver Server for iOS and tvOS
WebDriverAgent is the WebDriver server that Appium's XCUITest driver runs on-device to automate iOS and tvOS apps. It links directly against Apple's XCTest.framework instead of faking gestures from outside, which is why Appium builds on it rather than around it. Reach for it if you're debugging what Appium does on-device; skip it if you wanted a standalone tool, since almost nobody drives it directly.
What is WebDriverAgent?
WebDriverAgent is a WebDriver server for iOS that remote-controls iOS and tvOS devices — launching and killing apps, tapping and scrolling views, checking whether a view is on screen. It links directly against Apple's XCTest.framework and calls Apple's own APIs on-device, rather than simulating input from outside. Appium adopted it as the engine behind its XCUITest driver, which is how most developers end up using it.
Core Capabilities
- ✓Automates both iOS and tvOS, on physical devices and simulators.
- ✓Implements most of the W3C WebDriver Spec, so standard WebDriver commands map onto real device actions.
- ✓Implements part of the Mobile JSON Wire Protocol Spec for compatibility with older mobile test tooling.
- ✓Handles USB device communication through the appium-ios-device library, with zero third-party tool dependencies for that path.
- ✓Runs and debugs as an Xcode test target (WebDriverAgentRunner), so you set breakpoints in Xcode instead of a separate debugger.
- ✓Pairs with Mac2Driver to extend automation to macOS apps.
Primary Use Cases
- •End-to-end testing of iOS and tvOS apps — tapping through real user flows and asserting on-screen state.
- •General device automation outside of testing, like scripted app launches and UI interaction for other tooling.
- •Serving as the on-device driver layer under Appium, when teams write tests against Appium's XCUITest driver rather than calling WebDriverAgent directly.
- •Local debugging of device-automation behavior by running the WebDriverAgentRunner target straight from Xcode.
Getting Started
Clone the repo and make sure Node.js is installed first — the project's build tooling needs it even though the runtime is Objective-C. From there, open WebDriverAgent.xcodeproj in Xcode and run the WebDriverAgentRunner test target; that starts the server and you send it requests over HTTP (the README points to its wiki for the exact request format). If you need a redistributable build instead of running from Xcode, `npm run bundle` produces WebDriverAgentRunner-Runner-sim-<version>.zip for iOS and WebDriverAgentRunner-Runner-tv_sim-<version>.zip for tvOS. Beyond that, the README defers most setup detail — like code signing — to the project wiki, so treat deeper configuration as not clearly documented in the repo itself.
Running and Debugging
Once WebDriverAgentRunner is running, you drive it by sending it requests the same way you'd hit any WebDriver server — the README links out to its wiki for the exact query format rather than documenting it inline. Debugging happens where you'd expect for an Xcode project: set breakpoints in WebDriverAgentRunner and step through them live, instead of attaching a separate debugger to a black-box process. When something breaks, the README's first instruction is to check the project wiki's Common Issues page before filing anything new.
Strengths
- ✓USB device communication goes through appium-ios-device with zero third-party tool dependencies for that specific path.
- ✓You debug it like any other Xcode project — set a breakpoint in WebDriverAgentRunner and step through, instead of treating the server as a black box.
- ✓One codebase covers both iOS and tvOS, devices and simulators.
- ✓It's the same layer Appium's XCUITest driver runs on, so what you learn about WebDriverAgent's behavior explains what you see through Appium too.
Known Issues and Dependencies
- △Setup and troubleshooting details live mostly on the project wiki rather than in the README, so getting a first run working means jumping between the repo and external wiki pages.
- △It vendors two third-party HTTP server libraries, CocoaHTTPServer and RoutingHTTPServer, directly into its source tree because those upstream projects stopped being maintained — you inherit that code as-is instead of getting it patched upstream.
- △By the project's own description it implements 'most of' the WebDriver Spec and only part of the Mobile JSON Wire Protocol Spec, so some commands from either spec may not be covered.
- △It's built on Apple's XCTest.framework and Xcode, so there's no path to running it outside the Apple toolchain.
Similar Tools for iOS Automation
Common Questions
WebDriverAgent supports iOS and tvOS, on both real devices and simulators.
WebDriverAgent implements most of the W3C WebDriver Spec plus part of the Mobile JSON Wire Protocol Spec, so it isn't full coverage of either.
WebDriverAgent talks to USB-connected devices through the appium-ios-device library, and that path has zero third-party tool dependencies.
WebDriverAgent is released under the BSD license, per the LICENSE file in the repo, so you can embed it in both open-source and proprietary test tooling without a copyleft obligation.
WebDriverAgent integrates with Appium as the on-device server behind Appium's XCUITest driver — that's the primary way most developers use it.
The README points to the project wiki's Common Issues page as the first stop for known issues, rather than listing them in the repo itself.
The problem it solves
iOS doesn't ship a built-in way for an external process to speak WebDriver to an app the way a browser does — there's no on-device remote-control server out of the box. WebDriverAgent fills that specific gap: it links against XCTest.framework and exposes what it can do (launch/kill apps, tap, scroll, check view presence) over a WebDriver-shaped HTTP interface, which is exactly the bridge Appium needed to add real iOS support through its XCUITest driver instead of building its own device-side agent from scratch.
Who should try it — and who should skip
Try WebDriverAgent if you already automate iOS through Appium and want to understand, extend, or debug the layer XCUITest driver depends on, or if you're building tooling that needs direct on-device WebDriver-style control without going through Appium's abstraction. Skip it if you just want to write and run iOS UI tests — install Appium (or write XCUITest directly) and let it manage WebDriverAgent for you, because dealing with WebDriverAgent's Xcode project, signing, and wiki-documented setup on its own is more plumbing than most test authors need to touch.