概述与架构

• uiautomator2（Python wrapper） 是一个把 Android UiAutomator 能力（device-side）通过 HTTP 接口暴露出来，供 Python 客户端调用的工具链。整体分两部分：设备端运行的 agent/apk（负责执行 UiAutomator 操作、提供 API）；以及 Python 客户端库（封装 HTTP 请求并提供便捷 API）。官方开源实现位于 openatx/uiautomator2。GitHub+1

• UiAutomator（Android 框架层） 是 Google / AndroidX 提供的跨应用 UI 自动化框架，主要用于跨应用/系统级 UI 测试，核心类包括 UiDevice、UiSelector 等（uiautomator2 的 device-side 正是基于这些 API 实现交互）。当需要与系统设置或其他应用交互时，UiAutomator 是合适选择。Android Developers+1

环境与依赖准备

1. 系统与工具
• 安装 Android SDK（建议使用 Android Studio 的 SDK Manager），并确保 platform-tools（adb）在 PATH 中。Appium / uiautomator2 driver 也会依赖 SDK 工具。appium.io+1

2. Python 环境
• Python 3.7+（不同版本的 uiautomator2 要求有所不同，请以 PyPI / README 为准）。通过 pip 安装：
或使用指定版本。PyPI 页面列出了最新发行版本与要求。PyPI

3. 设备准备
• 打开 Android 设备的“开发者选项”和“USB 调试”。
• 建议在真实设备或 AVD 上测试，确保 adb 能识别设备（adb devices）。若使用无线连接，先通过 USB 做一次 pairing / adb tcpip 或 uiautomator2 的远程连接方法（见下一节）。

4. agent / apk（device-side）
• uiautomator2 客户端会在设备上安装一组 APK（通常称为 atx-agent、uiautomator2 apk 等），这些 apk 提供 HTTP 服务和 uiautomator 桥接。首次连接时客户端可自动安装，或可手工预装以减少首次连接延迟。具体实现详见项目 README。GitHub+1

连接方式与常用初始化流程

USB（推荐用于稳定性）

• 首次连接时，库会尝试安装 device-side apk（若未安装）。如果因权限或签名问题失败，可手动把 apk 安装到设备上。详见 readme。GitHub+1

通过 IP（Wi-Fi）

• 在设备上启用 adb tcpip 或直接让 agent 监听 HTTP 并通过 IP 连接：

• Wi-Fi 连接不如 USB 稳定，适合远程调试与演示。agent/http 模式可能需要额外的安全/防火墙配置。GitHub

元素定位与常用 API

常用 Selector 参数

• text：显示文本（完全匹配）

• textContains / textStartsWith（部分匹配）

• resourceId / resourceIdMatches

• className

• description（content-desc）

• index / instance

查找与等待

• exists() / wait(timeout) / get_text() 等：

常用操作 API（示例）

• 点击 / 长按 / 双击 / 滑动 / drag_to：

• 文本输入（注意输入法与键盘状态）：

• 应用管理与设备操作：

• 屏幕截图、UI dump：

调试、检查与定位元素工具

• UIAutomatorViewer（Android SDK 自带）可抓取当前屏幕的 UI 层次树并查看 resource-id、text、class 等信息；适合离线分析。browserstack.com

• uiautomator2 自带的 dump_hierarchy() / screenshot()，可把 UI XML 与截图拉回到本地进行分析。

• 使用 adb shell uiautomator dump /sdcard/uidump.xml 能在设备上生成 UI XML（限制较多，建议使用工具或库自带方法）。

快速命令/参考速查表

• 连接与设备信息：
d = u2.connect('serial_or_ip')；d.info

• 应用控制：
d.app_start(pkg)；d.app_stop(pkg)；d.app_install(path_or_url)；d.app_uninstall(pkg)

• 元素操作：
d(text="xxx").click()；d(resourceId="pkg:id/xx").set_text('abc')；d(text="btn").long_click()

• 屏幕与 UI：
d.screenshot('a.png')；xml = d.dump_hierarchy()

• Shell 与 adb：
d.shell('pm list packages')；d.adb.shell('input keyevent 3')（注：部分库将 adb 封装为 d.shell）

• 等待/判断：
d(text="完成").wait(timeout=10)；d(text="完成").exists

推荐阅读与参考链接

• uiautomator2（openatx / GitHub README & 文档）—— 包含安装、常用 API、示例。GitHub+1

• uiautomator2 readthedocs（API 详解）。uiautomator2.readthedocs.io

• Android 官方：Write automated tests with UI Automator（AndroidX / UiAutomator 说明）。Android Developers

• Appium UiAutomator2 driver 文档（当与 Appium 集成时参考）。appium.io+1

• UIAutomatorViewer 使用教程（Element inspection）。browserstack.com