Facebook WebDriverAgent Python Client

1.5.4 · active · verified Thu Apr 16

facebook-wda is a Python client library for Facebook's WebDriverAgent, an iOS test automation framework that enables UI testing and remote control of iOS devices and simulators. It provides a programmatic interface to interact with iOS applications, perform gestures, take screenshots, and manage app states. The library is actively maintained, with frequent releases, and is currently at version 1.5.4.

Common errors

```
wda.WDAError: ...
```
cause The Python client failed to communicate with the WebDriverAgent server. This usually indicates WDA is not running, is unreachable, or an API call failed on the WDA side.

fix Verify WebDriverAgent is running on the device/simulator and is accessible at the specified URL (e.g., `http://localhost:8100`). Check network connectivity and WDA logs for errors. Ensure no system pop-ups are blocking WDA startup on the device.
```
wda.exceptions.WDAElementNotFoundError: ...
```
cause The requested UI element could not be found on the screen within the default timeout. This often happens if the app state is not as expected or the selector is incorrect.

fix Inspect the current screen's UI hierarchy (e.g., using Appium Inspector or `wda.Client().screenshot()`) to verify the element's presence and its attributes. Adjust element locators for accuracy or increase the wait timeout for the element. Use `.exists` for conditional checks or `.wait()` with a timeout.
```
Terminating app due to uncaught exception 'NSInvalidArgumentException', reason:'-[PDSpecificationsContentView title]:unrecognized selector sent to instance0x...' or similar NSInvalidArgumentException
```
cause This error originates from WebDriverAgent itself, indicating an attempt to call a method on an object that does not respond to that selector. It often points to issues within the WDA server or the iOS app under test.

fix This is typically a WDA or iOS-level issue rather than a `facebook-wda` library issue. Try restarting WebDriverAgent, the device/simulator, or updating WDA. Check if the error is reproducible with different WDA versions or on a different device.
```
invalid session id
```
cause The WDA session you were using became invalid, likely due to the WebDriverAgent server restarting, the app crashing, or the session timing out.

fix Catch this exception and re-establish a new session. It's good practice to wrap operations in `try...except wda.WDAError` blocks to handle such transient failures gracefully.

Warnings

breaking Starting from version 1.5.4, the `tidevice` dependency has been removed from `facebook-wda`. If your workflow previously relied on `facebook-wda` to implicitly manage or interact with `tidevice` for USB connections or WebDriverAgent startup, you will now need to manage `tidevice` and WebDriverAgent separately.
Fix: Manually install and run `tidevice` (e.g., `pip install tidevice` or `brew install tidevice`) and ensure WebDriverAgent is launched on your device/simulator independently. Refer to `tidevice` documentation for its usage, or start WDA directly via Xcode.
gotcha WebDriverAgent (WDA) must be running on the target iOS device or simulator *before* `facebook-wda` can connect to it. `facebook-wda` is a client, not a server manager, and does not automatically launch WDA.
Fix: Start WebDriverAgent via Xcode, `xcodebuild` command line, or use an external tool like `tidevice` to manage its lifecycle. Ensure WDA is accessible at the specified IP:PORT (default is `http://localhost:8100`).
gotcha The `window_size()` method returns dimensions in UIKit points, while `screenshot()` captures images in native resolution (pixels). These dimensions can differ, especially on Retina displays, requiring scaling when comparing or performing calculations.
Fix: Use `session.scale` to get the UIKit scale factor if you need to convert between UIKit points and native pixels for accurate element positioning or image processing.
deprecated The `session.set_alert_callback()` method is deprecated and may not work as expected or might be removed in future versions.
Fix: Instead of using a callback, handle alerts explicitly using `session.alert.accept()`, `session.alert.dismiss()`, or `session.alert.click("Button Name")` within your test logic.

Install

pip install facebook-wda Install stable version

Imports

Client
```
import wda
c = wda.Client()
```

Quickstart

This quickstart demonstrates how to initialize the facebook-wda client, check the WebDriverAgent's status, simulate a home button press, launch an application (Safari), navigate to a URL, and capture a screenshot. It uses an environment variable for the WDA URL for flexibility.

import wda
import os

# Get WDA server URL from environment variable, default to localhost
# Ensure WebDriverAgent is running on your iOS device/simulator, e.g., via Xcode or another tool.
wda_url = os.environ.get('WDA_URL', 'http://localhost:8100')
c = wda.Client(wda_url)

print(f"Connecting to WDA at: {wda_url}")
try:
    status = c.status()
    print(f"WDA Status: {status['state']}")

    # Example: Press home button
    c.home()

    # Example: Start a session with an app (e.g., Safari)
    with c.session('com.apple.mobilesafari') as s:
        print(f"Session orientation: {s.orientation}")
        print(f"Window size (UIKit points): {s.window_size()}")
        s.open_url("https://www.google.com")
        # Take a screenshot (requires Pillow to save to file)
        s.screenshot('safari_screen.png')
        print("Screenshot saved to safari_screen.png")
except wda.WDAError as e:
    print(f"Failed to connect or interact with WDA: {e}")
    print("Ensure WebDriverAgent is running and accessible at the specified URL.")

view raw JSON →