{"id":7832,"library":"uiautomator2","title":"uiautomator2 for Android UI Automation","description":"uiautomator2 is a Python wrapper for Google's UiAutomator test framework, enabling robust UI automation for Android devices. It simplifies interacting with Android applications, performing actions like clicking, typing, scrolling, and getting device information. The current stable version is 3.5.0, with frequent patch releases addressing bug fixes and minor enhancements. It requires Python 3.8 to 3.11.","status":"active","version":"3.5.0","language":"en","source_language":"en","source_url":"https://github.com/openatx/uiautomator2","tags":["android","automation","ui","testing","mobile","adb"],"install":[{"cmd":"pip install uiautomator2","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Provides underlying ADB communication; tight version coupling.","package":"adbutils","optional":false}],"imports":[{"note":"While 'from uiautomator2 import connect' works, 'import uiautomator2 as u2' is the idiomatic and recommended way to use the library, providing access to all methods through the 'u2' alias.","wrong":"from uiautomator2 import connect","symbol":"uiautomator2","correct":"import uiautomator2 as u2"}],"quickstart":{"code":"import uiautomator2 as u2\nimport os\n\n# Connect to a device. You can specify a serial (e.g., 'emulator-5554')\n# or an IP address (e.g., '192.168.1.100'). If no argument is given,\n# it tries to connect to the first available device via ADB.\n# Ensure 'adb devices' shows your device and 'u2 init' has been run on the device.\n\n# Example for connecting to a specific IP, fallback to default\nDEVICE_ADDRESS = os.environ.get('U2_DEVICE_ADDRESS', None)\n\ntry:\n    if DEVICE_ADDRESS:\n        d = u2.connect(DEVICE_ADDRESS)\n    else:\n        d = u2.connect() # Connects to the default/first available device\n    \n    print(f\"Successfully connected to device: {d.info.get('serial', 'N/A')}\")\n\n    # Print basic device information\n    print(\"Device Info:\", d.info)\n\n    # Get the current package and activity\n    current_app = d.app_current()\n    print(f\"Current app: {current_app['package']} / {current_app['activity']}\")\n\n    # Take a screenshot and save it\n    screenshot_path = \"uiautomator2_quickstart_screenshot.png\"\n    d.screenshot(screenshot_path)\n    print(f\"Screenshot saved to {screenshot_path}\")\n\n    # Interact with the UI (example: press the Home button)\n    d.press(\"home\")\n    print(\"Pressed Home button.\")\n\n    # Dump the current UI hierarchy (useful for inspecting elements)\n    xml_dump = d.dump_hierarchy()\n    print(\"UI Hierarchy (first 200 characters):\", xml_dump[:200])\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    print(\"\\nTroubleshooting steps:\")\n    print(\"1. Ensure your Android device is connected via USB/WiFi and ADB debugging is enabled.\")\n    print(\"2. Run 'adb devices' in your terminal to confirm ADB detects your device.\")\n    print(\"3. Run 'python -m uiautomator2 init' (or 'u2 init') to install the uiautomator2 server on the device.\")\n    print(\"4. If connecting via IP, ensure the device is on the same network and you're using the correct IP.\")\n","lang":"python","description":"This quickstart demonstrates how to connect to an Android device using `uiautomator2`, retrieve device information, take a screenshot, press the home button, and dump the UI hierarchy. Remember to run `u2 init` on your device first to set up the necessary server applications."},"warnings":[{"fix":"Run `python -m uiautomator2 init` (or `u2 init` if installed as a command-line tool) from your terminal. This command installs the necessary APKs and starts the server on the connected device.","message":"The `uiautomator2` server (atx-agent) must be installed and running on the Android device for the Python client to connect. Forgetting to initialize often leads to connection errors.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always install/upgrade `uiautomator2` using `pip install uiautomator2 --upgrade`. This ensures compatible `adbutils` versions are installed. If issues arise, try reinstalling `uiautomator2` from scratch or checking its GitHub releases for specific `adbutils` compatibility notes.","message":"uiautomator2 has a tight dependency on specific versions of `adbutils`. Upgrading `adbutils` independently of `uiautomator2` might lead to compatibility issues or unexpected behavior, as breaking changes in `adbutils` are often addressed in subsequent `uiautomator2` releases.","severity":"breaking","affected_versions":"3.x"},{"fix":"Review scripts using `d.send_keys()` and remove any redundant `d.hide_keyboard()` calls that follow directly. Test carefully, as behavior can vary slightly across Android versions.","message":"As of version 3.5.0, `d.send_keys()` automatically hides the input method after text entry. If your script previously included an explicit `d.hide_keyboard()` call immediately after `send_keys`, this might result in an unnecessary or problematic extra action.","severity":"gotcha","affected_versions":">=3.5.0"},{"fix":"Prioritize `resourceId` for element identification. If `resourceId` is not stable or unique, consider using a combination of attributes or relative positioning. Avoid complex or deeply nested XPath expressions for better performance and maintainability.","message":"Element locators (e.g., XPath, text, resourceId) can be brittle. XPath is often slow and prone to breaking with minor UI changes. Text-based selectors can fail with localization or dynamic content. `resourceId` is generally the most stable if available and unique.","severity":"gotcha","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":"Run `python -m uiautomator2 init` (or `u2 init`) in your terminal. Ensure your device is connected via ADB and has granted debugging permissions. This command will install and start the necessary server.","cause":"The `atx-agent` server, which enables communication between the Python client and the Android device, is not running on the device.","error":"uiautomator2.exceptions.GatewayError: uiautomator2 server not started"},{"fix":"1. Ensure the device is physically connected (if using USB). 2. Verify 'USB debugging' is enabled in Developer Options. 3. Check for 'Allow USB debugging?' prompt on the device and accept it. 4. Run `adb devices` in your terminal to confirm the device is listed. 5. If connecting wirelessly, ensure the IP address is correct and ADB is connected (`adb connect <ip>`).","cause":"The Android Debug Bridge (ADB) cannot detect your device. This could be due to a disconnected cable, unauthorized device, missing ADB drivers, or an incorrect IP address/serial for wireless connection.","error":"AdbError: device not found"},{"fix":"Install the package using pip: `pip install uiautomator2`.","cause":"The `uiautomator2` Python package is not installed in your current Python environment.","error":"No module named 'uiautomator2'"},{"fix":"Ensure the `UiObject` you're targeting is indeed a scrollable element (e.g., a RecyclerView or ScrollView). If not, you might need to find its parent scrollable container or use general device-level scrolling methods like `d.scroll()` or `d.swipe()`.","cause":"Methods like `scroll_to_end` or `fling_to_end` are typically available only on UiObjects that are recognized as scrollable containers. Calling them on a generic or non-scrollable UiObject will raise an error.","error":"AttributeError: 'UiObject' object has no attribute 'scroll_to_end'"}]}