WebDriverAgent Documentation

WebDriverAgent is a WebDriver server implementation for iOS designed for remote controlling iOS devices. It enables application end-to-end testing and general-purpose device automation by allowing users to:

• Launch and kill applications.
• Tap and scroll views.
• Confirm the presence of views on a screen.

It functions by linking XCTest.framework and utilizing Apple's APIs to execute commands directly on the device. It supports both physical devices and simulators and implements most of the WebDriver Spec and parts of the Mobile JSON Wire Protocol Spec.

Archiving Notice

WebDriverAgent is currently archived and is no longer actively supported by Facebook. The code remains available for future use, but users are encouraged to consider alternatives.

Recommended Alternative: Facebook has open-sourced IDB (iOS Development Bridge), a command line interface for automating iOS Simulators and Devices. Facebook is migrating its internal projects from WDA to IDB and suggests checking it out.

To set up the WebDriverAgent project, run the provided bootstrap script. This script automates the following tasks:

1. Fetches all dependencies using Carthage.
2. Builds the Inspector bundle using npm.

Once the bootstrap process is complete, you can open WebDriverAgent.xcodeproj in Xcode, start the WebDriverAgentRunner test, and begin sending requests to the server.

./Scripts/bootstrap.sh

The Inspector web application is a React-based UI that provides a visual interface for inspecting mobile device elements. It automatically initializes by mounting the App component to document.body.

Upon mounting, the application performs the following automated tasks:

1. Fetches the device orientation from the orientation endpoint.
2. Fetches a base64 encoded screenshot from the screenshot endpoint.
3. Constructs a screenshot object using ScreenshotFactory.createScreenshot.
4. Fetches the element tree structure from the source?format=json endpoint.
5. Builds a tree of TreeNode objects using TreeNode.buildNode and a TreeContext.

WebDriverAgent provides several key capabilities for automation:

• Device & Simulator Support: Works with both physical iOS devices and simulators.
• Protocol Implementation: Implements most of the WebDriver Spec and parts of the Mobile JSON Wire Protocol Spec.
• USB Support: Provides USB support for physical devices.
• Inspector Endpoint: Includes an inspector endpoint at http://localhost:8100/inspector with a user interface to inspect the current device state.
• Xcode Integration: Supports an easy development cycle as it can be launched and debugged directly via Xcode.
• Platform Support: While not officially supported, it works with tvOS and OSX.

The FBInspectorCommands class defines HTTP routes used to serve the WebDriverAgent Inspector web interface. These routes allow a client to retrieve the necessary HTML and JavaScript files to render the inspector in a browser.

Available routes:

• GET /inspector: Returns the index.html file.
• GET /inspector.js: Returns the inspector.js file.

Both routes are configured .withoutSession, meaning they can be accessed without an active session context.

The POST /wda/element/:uuid/scroll route supports several modes of scrolling:

1. Scroll to specific child: Provide a name (identifier) or predicateString in the arguments. The command will find the descendant and scroll it into view.
2. Scroll by direction: Provide direction (up, down, left, right) and an optional distance (default 1.0).
3. Scroll element to visible: Provide the toVisible argument to scroll the target element itself into view.

Retrieve the current application's UI hierarchy using the /source endpoint. You can specify the output format using the format query parameter.

Supported formats:

• xml (default): Returns an XML string representing the UI snapshot via FBXPath.
• json: Returns the application's UI tree as a JSON object.
• description: Returns a text-based description of the UI elements (using debugDescription).

If the format is unsupported, the command returns an error with the status FBCommandStatusUnsupported.

To change the physical device rotation, send a POST request to the /rotation endpoint. The request must include a rotation argument in the arguments dictionary.

Error Response: If rotation is not supported, the server returns FBCommandStatusRotationNotAllowed with a message indicating the unsupported rotation: "Rotation not supported: <rotation_value>".