Using facebook-wda for iOS Automation: Installation, Basic API, and Custom Extensions

Introduction – WebDriverAgent is a WebDriver server implemented by Facebook for iOS devices; when the server app is installed on a device, it can be controlled via HTTP requests. facebook-wda is a compact Python library that communicates directly with WebDriverAgent without an intermediate service and supports multiple languages.

Installation preparation – Before writing test code, you must (1) deploy WebDriverAgent (see the linked tutorial), (2) install the Python package with pip install --pre facebook-wda , and (3) forward the iPhone port to a Mac using iproxy <local port> <remote port> [udid] . After forwarding, visiting http://localhost:8100/status should return a JSON string confirming successful installation.

Basic API usage

First import the library:

import wda

Enable debugging and adjust timeout:

wda.DEBUG = True
wda.HTTP_TIMEOUT = 10.0

Connect to the local WebDriverAgent server:

c = wda.Client('http://localhost:8100')

Common actions include:

# Press the HOME button
c.home()

# Launch an app (replace with your bundle ID)
s = c.session('com.netease.cloudmusic')

# Open Settings
c.session('com.apple.Preferences')

# Close the app
s.close()

# Locate an element
el = s(name='登录', className='Button')

# Check existence
el.exists()

# Clear a text field
s(type='TextField').clear_text()

# Set text
s(type='TextField').set_text('xxx')

# Tap the element
s(type='TextField').tap()

# Tap by coordinates
s.tap(144, 234)

# Long‑press for 2 seconds
s.tap_hold(144, 234, 2.0)

# Swipe between points
s.swipe(x1, y1, x2, y2)

# Directional swipes
s.swipe_left()
s.swipe_right()
s.swipe_up()
s.swipe_down()

These commands cover element interaction, session handling, and common gestures. For more complex operations, refer to the ATX iOS control API documentation.

Comparison with Appium – Using facebook-wda results in a simpler project structure, clearer command syntax, and more straightforward element locating compared with Appium‑based automation, thereby improving test case design and debugging efficiency.

Advanced: Customizing facebook-wda APIs – By examining the library’s __init__.py , you can see that each API builds an HTTP request after processing parameters. To add a custom API such as quicktap(x1, y1) , you modify both the library and the WebDriverAgent server:

In facebook-wda/__init__.py , add a new function that sends the appropriate request.

In the WebDriverAgent project, add a new route for /wda/quicktap and implement the handler (e.g., in handleKeys or a new function) to perform the fast tap on the device.

With a basic understanding of Objective‑C, you can also adjust internal functions like handleKeys to change input speed or other behaviors.

References

• https://www.helplib.com/GitHub/article_142159 • https://www.cnblogs.com/Owen-ET/p/9805518.html