Wetest UIAutomator2 Python Client

Wetest UIAutomator2 Python Client 是一款轻量化的 Python 客户端框架，对于 Wetest Appium Server 提供了完整的 API 支持。在 Wetest UIAutomator2 Python Client 的帮助下，您可以较为容易地跨平台编写和运行安卓 UI 自动化脚本。

Wetest UIAutomator2 Python Client 提供了 AndroidDriver，ServerRunner 和 Installer 三大组件（以下简称 driver，runner 和 installer）和 utils 工具库：

• AndroidDriver 对 Wetest Appium Server 提供了完整的 API 支持，创建 driver 后即可使用它进行自动化控制；
• ServerRunner 能够在自动地在安卓设备端自动启动和停止 server；
• Installer 对多种机型进行了适配，能够提供自动化的弹窗解决方案；
• utils 工具库集成了便捷的大文件夹推送，权限设置，端口转发等功能。

使用

安装

使用以下命令可以直接从腾讯 Pypi 源进行安装，或在仓库 release 中下载 .whl 包进行安装。

pip install wetest-uiautomator2 --upgrade --extra-index-url https://mirrors.tencent.com/repository/pypi/tencent_pypi/simple

API 说明文档

文档链接：Wetest UIAutomator2 Python Client API 说明文档

此外，项目的 HTML 文档也可以在仓库 ./docs/build/html/index.html 中找到，拉取项目到本地后通过浏览器打开。

样例

项目的基本框架可以在仓库 ./example.py 中找到。

基于 Pytest 的样例可以在仓库目录 ./wetest_uiautomator2/test/ 下找到，可以通过命令行运行：

pytest -s ./test/test_android_getter.py
pytest -s ./test/test_android_poster.py

Startup

通过 adb 命令将 Appium Server 包推送到手机内：

# ServerRunner 同样提供了推包能力，但更推荐在初次连接手机时进行手动配置，避免重复推包和 adb 不稳定造成的 bug
adb push ./appium-uiautomator2.apk /data/local/tmp/udt/uia2.jar  

在 Python 编写自动化流程的基本框架：

from adbutils import adb
from wetest.uiautomator2 import AndroidDriver, ServerRunner, Installer, utils

d = adb.device()  # 获取目标设备

# 创建 runner, 拉起 Appium server
runner = ServerRunner(d)
# 创建 driver, 开始自动化流程
driver = AndroidDriver(d, timeout=1000, debug=False, traceback=True)
# 通过 runner 和 driver 创建 installer
installer = Installer(runner, driver)

1. 使用 ServerRunner 和 AndroidDriver

• driver 和 runner 都是依赖 AdbDevice 存在的实例，可以较为容易地进行多设备管理；
• driver 在 server 启动后即可直接创建并使用，driver 中集成了丰富的 api 以供自动化使用；
• runner 本质上是一个设备端 Appium server 的自动管理器，通过实例化 runner 来提供 driver 的启动环境。如有需要，也可以自行手动启动 server；
• 本框架和 WeAutomator 2.0 共享了相同后端，在启动 WeAutomator 页面后，您甚至可以省却 runner 直接实例化 driver。

with ServerRunner(d) as runner:  # 推荐使用 with 管理其生命周期
    driver = AndroidDriver(d, timeout=1000, debug=True)
    # 查找并点击元素
    element = driver.find(text="startup", retry=10, interval=2000)
    element.click()

driver 支持丰富的元素查找能力，除基本属性之外，还提供了强大且灵活的正则匹配接口：

""" driver.finds(${prefix}${suffix} = value)

* ${prefix} 可为 ['text', 'classname', 'package', 'id', 'content_desc'] 参数中的任意一个
* ${suffix} 可为 ['_contains', '_matches', '_startswith', '_endswith'] 其中任意一个
* find(), finds(), inspect() 接口的任意参数都可以进行一种或多种正则匹配
* 参数支持传入列表，列表内各搜索条件为 or 关系（取并集）
"""

elements = driver.finds(text="text", package="com.tencent.pkg")

elements = driver.finds(
    id_startswith="prefix",
    text_endswith=["suffixA", "suffixB"],
    package_contains="keyword",
    classname_matches="\w*regular_expression*",
)

driver 支持常用的自动化API、强大的自动化手势操作和高级 API，请通过 API 文档 了解和查阅：

print(driver.page_source())
decoded_bytes = driver.screenshot(save_path="./screenshot.png")

driver.tap(x=1000, y=500)  # 点击
driver.long_press(x=1000, y=500, duration_ms=1000)  # 长按
driver.appium_pinch_in(percent=0.5, area=(100, 100, 100, 100), speed=100)  # 手指捏合

driver.press_back()  # 返回键
driver.accept_alert(button_label="Accept")  # 通过点击标签为 "Accept" 的选项接受弹窗
driver.schedule_action(
    name="popup", steps=[ScheduledStep(type="source", name="fetchPageSourceStep", payload={"subtype": "xml"})]
)  # 规划 Actions

driver 提供了灵活的错误处理器 expect()，以供编写简洁优雅的函数式自动化流程：

# Usage: driver.expect().method(*args, **kwargs)

# 直接跳过错误，替代了传统的 try-catch-pass 流程
driver.expect().finds(text=["settings", "设置"]) 

# expect 的高级使用
def err_handler(exception, callback_info):  # 如果回调函数包含 'exception' 参数名，则会自动捕获到的错误本身
    print(f"handling exception {exception.__class__.__name__} : {callback_info}")

driver.expect(
    handler=err_handler,  # 回调函数
    msg="some message",   # 捕获错误时打印自定义信息
    show_log=True,        # 是否打印错误信息    

    # 余下所有参数都会传入回调函数，请确保参数名正确
    callback_info="some information",
).find(
    retry=1,
    interval=1,
    text="不存在的元素",
).click()  # 通过函数式的链式调用，简化自动化流程中的错误处理

""" outputs:
$ expect().find() raises AppiumAndroidException: An element could not be located on the page
$ some message
$ handling exception AppiumAndroidException : some information
$ ignores a method call: click
"""

2. 通过 Installer 进行免弹窗安装

• 此外，installer 是通过集成和封装 driver、runner 能力而形成的免弹窗解决方案。
• 目前支持了 OPPO、VIVO、小米等应用安装自动化较为复杂的设备厂商。

with ServerRunner(d) as runner:
    driver = AndroidDriver(d, timeout=1000, debug=True)
    installer = Installer(runner=runner, driver=driver)
    installer.install(package_path, package_name)  # 安装 APK

3. 通过 utils 工具实现 abd 相关操作

utils 工具封装了部分常用的 abd 相关功能，包括镜像推送完整目录、端口转发、设置权限等。

from wetest.uiautomator2 import utils

serial = adb.device().serial

utils.adb_forward(serial, local=8000, remote=8000)
utils.adb_forward_remove(serial, local=8000)
utils.push_dir(serial, source="./source", target="/data/local/tmp", filters=[".*\.txt", "([^/]+\.(?:jpg|png))"])
utils.set_permission(serial, "com.tencent.qq").readwrite()

作者信息 & 致谢

Tencent WeTest Team

xiutongmu@tencent.com

感谢以下开源项目的启发：

• https://github.com/SonicCloudOrg/sonic-uiautomator2-python-client
• https://github.com/appium/appium-uiautomator2-server
• https://github.com/openatx/facebook-wda