openatx/uiautomator2 2.x到3.x版本升级指南与技术变更解析

openatx/uiautomator2 2.x到3.x版本升级指南与技术变更解析

uiautomator2 Android Uiautomator2 Python Wrapper 项目地址: https://gitcode.com/gh_mirrors/ui/uiautomator2

前言

openatx/uiautomator2作为Android UI自动化测试的重要工具，在3.x版本中进行了重大架构调整和功能优化。本文将全面解析2.x到3.x版本的升级注意事项，帮助开发者平滑过渡到新版本。

核心架构变更

1. 服务架构重构

3.x版本移除了atx-agent常驻服务，改为运行时动态启动uiautomator服务。这一变化带来了以下优势：

• 资源占用更低：不再需要后台常驻服务
• 稳定性提升：避免了常驻服务可能出现的各种异常
• 部署简化：不再需要单独安装和维护atx-agent

2. 连接方式调整

• 不再支持直接通过atx-agent地址连接设备
• connect()函数现在仅支持：
  • 本地USB连接的设备
  • 通过adb connect连接的设备
• 环境变量ANDROID_DEVICE_IP被移除，改用ANDROID_SERIAL传递设备序列号

开发环境要求变化

• Python版本：最低要求提升至3.8
• 依赖管理：从pbr切换到poetry，精简了依赖库数量
• 日志系统：改用标准库logging，默认不输出日志，需手动开启

新增功能特性

1. 新增实用功能

# 启用美观日志输出
enable_pretty_logging()

# 获取页面源码
d.xpath.get_page_source() -> PageSource

2. 新增异常类型

• AdbShellError：ADB命令执行错误
• HierarchyEmptyError：UI层级为空错误
• HTTPError：HTTP请求错误

移除的功能与API

1. 移除的第三方库

• logzero（改用标准库logging）
• filelocks
• progress
• packaging
• Pillow

2. 移除的模块与类

• 移除uiautomator2.ext.xpath模块
• 移除AdbUI类
• 移除多种错误类（GatewayError、ServerError等）

3. 移除的属性与方法

属性移除：

• d.watcher.debug
• address（原atx-agent URL地址）
• alive（atx-agent存活状态检测）
• uiautomator（停止uiautomator服务）
• widget（不常用）
• http（直接HTTP请求）

方法移除：

• current_app() → 改用app_current()
• healcheck()（uiautomator服务恢复）
• service()（atx-agent服务管理）
• app_icon()（依赖atx-agent）
• connect_wifi()（依赖atx-agent）
• open_identify()（界面展示功能）

4. XPath相关变更

移除的方法：

• dump_hierarchy
• get_last_hierarchy
• add_event_listener
• 各种send_*操作（点击、滑动等）
• when、run_watchers等监听方法
• position查找方式

API变更详解

1. 连接相关

# 2.x
connect_usb(serial, init: bool)

# 3.x
connect_usb(serial)

2. Shell命令

# 2.x
shell(cmdargs, stream: bool, timeout)

# 3.x
shell(cmdargs, timeout)

3. 文件传输

# 2.x
push(src, dst, mode, show_process: bool)

# 3.x
push(src, dst, mode)

4. XPath等待

# 2.x
d.xpath("...").wait() -> XMLElement|None

# 3.x
d.xpath("...").wait() -> bool

5. 应用信息

2.x返回完整信息：

{
    "mainActivity": "...",
    "label": "...",
    "versionName": "...",
    "versionCode": ...,
    "size":...
}

3.x精简为：

{
    "versionName": "...",
    "versionCode": ...
}

6. 设备信息

3.x版本设备信息输出更加简洁，移除了电池、内存等动态信息，只保留基本设备标识和配置信息。

7. Toast处理

# 2.x
d.toast.get_message(5.0, default="")
d.toast.reset()

# 3.x
d.last_toast  # 属性方式获取
d.clear_toast()

升级建议

1. 环境准备：

   • 确保Python版本≥3.8
   • 清理旧版本依赖

2. 代码适配：

   • 替换所有已移除的API调用
   • 调整连接设备的方式
   • 更新异常处理逻辑

3. 测试验证：

   • 重点关注XPath相关操作
   • 验证Toast处理逻辑
   • 检查设备信息获取代码

4. 性能优化：

   • 利用新版本的轻量级特性
   • 优化日志输出配置

结语

openatx/uiautomator2 3.x版本通过架构简化带来了更好的稳定性和易用性。虽然升级过程中需要一定的适配工作，但长远来看将提升自动化测试的效率和可靠性。建议开发者根据本文指南逐步完成版本迁移，享受新版本带来的改进。

uiautomator2 Android Uiautomator2 Python Wrapper 项目地址: https://gitcode.com/gh_mirrors/ui/uiautomator2