facebook-wda

library1.5.4pypypi✓ verified 86d ago

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.

testing

pip install facebook-wda

github ↗package ↗

INSTALL

IMPORT

SIG · FACEBOOK-WDA

facebook-wda

testingpythonv1.5.4

Install

3.1s avg

Import

270ms

Disk

38MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.5.4 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.285s · 39.8MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 3.1s · import 0.256s · 41MB

38MB installed

● package 38MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Client

✓ import wda c = wda.Client()

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.")

Debug

Known issues

breakingStarting 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.

affects: >=1.5.4

gotchaWebDriverAgent (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`).

affects: All versions

gotchaThe `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.

affects: All versions

deprecatedThe `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.

affects: All versions

Errors

Common errors & fixes

wda.WDAError: ...

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: ...

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

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

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.

Upgrade

Version history

1.5.4latest on PyPI · released Sep 3, 2025

Audit

Dependencies

PillowoptionalRequired for saving screenshots to a file.

Agent activity

52 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/openatx/facebook-wda ↗

packagehttps://pypi.org/project/facebook-wda/ ↗