{"id":8147,"library":"facebook-wda","title":"Facebook WebDriverAgent Python Client","description":"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.","status":"active","version":"1.5.4","language":"en","source_language":"en","source_url":"https://github.com/openatx/facebook-wda","tags":["iOS automation","WebDriverAgent","mobile testing","UI automation"],"install":[{"cmd":"pip install facebook-wda","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for saving screenshots to a file.","package":"Pillow","optional":true}],"imports":[{"symbol":"Client","correct":"import wda\nc = wda.Client()"}],"quickstart":{"code":"import wda\nimport os\n\n# Get WDA server URL from environment variable, default to localhost\n# Ensure WebDriverAgent is running on your iOS device/simulator, e.g., via Xcode or another tool.\nwda_url = os.environ.get('WDA_URL', 'http://localhost:8100')\nc = wda.Client(wda_url)\n\nprint(f\"Connecting to WDA at: {wda_url}\")\ntry:\n    status = c.status()\n    print(f\"WDA Status: {status['state']}\")\n\n    # Example: Press home button\n    c.home()\n\n    # Example: Start a session with an app (e.g., Safari)\n    with c.session('com.apple.mobilesafari') as s:\n        print(f\"Session orientation: {s.orientation}\")\n        print(f\"Window size (UIKit points): {s.window_size()}\")\n        s.open_url(\"https://www.google.com\")\n        # Take a screenshot (requires Pillow to save to file)\n        s.screenshot('safari_screen.png')\n        print(\"Screenshot saved to safari_screen.png\")\nexcept wda.WDAError as e:\n    print(f\"Failed to connect or interact with WDA: {e}\")\n    print(\"Ensure WebDriverAgent is running and accessible at the specified URL.\")\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=1.5.4"},{"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`).","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All 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.","message":"The `session.set_alert_callback()` method is deprecated and may not work as expected or might be removed in future versions.","severity":"deprecated","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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.","error":"wda.WDAError: ..."},{"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.","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.","error":"wda.exceptions.WDAElementNotFoundError: ..."},{"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.","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.","error":"Terminating app due to uncaught exception 'NSInvalidArgumentException', reason:'-[PDSpecificationsContentView title]:unrecognized selector sent to instance0x...' or similar NSInvalidArgumentException"},{"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.","cause":"The WDA session you were using became invalid, likely due to the WebDriverAgent server restarting, the app crashing, or the session timing out.","error":"invalid session id"}]}