uiautomator2

PyPI

QQ交流群: 815453846 Discord: https://discord.gg/PbJhnZJKDd

有段时间没有维护这个项目了（可能有两年了），但是最近工作需要又重新研究一下Android原生自动化，当然又调研了Appium，对比下来一看，发现uiautomator2这个项目的运行速度是真的好快，从检测元素到点击，都是毫秒级的，代码也比较好理解。真是没想到以前竟然写出了这么神奇的项目，这么好的项目怎么能让它落灰呢，得好好整一整，一些垃圾代码清理清理。所以项目版本从2.x.x升级到了3.x.x

还在用2.x.x版本的用户，可以先看一下2to3 再决定是否要升级3.x.x （我个人还是非常建议升级的）

2到3毕竟是大版本升级，很多的函数删掉了。首先删掉的就是atx-agent，其次还有一堆atx-agent相关的函数。废弃的功能比如init.

各种依赖库的版本号

UiAutomator是Google提供的用来做安卓自动化测试的一个Java库，基于Accessibility服务。功能很强，可以对第三方App进行测试，获取屏幕上任意一个APP的任意一个控件属性，并对其进行任意操作，但有两个缺点：1. 测试脚本只能使用Java语言 2. 测试脚本要打包成jar或者apk包上传到设备上才能运行。

我们希望测试逻辑能够用Python编写，能够在电脑上运行的时候就控制手机。这里要非常感谢 Xiaocong He ([@xiaocong][])，他将这个想法实现了出来（见xiaocong/uiautomator），原理是在手机上运行了一个http rpc服务，将uiautomator中的功能开放出来，然后再将这些http接口封装成Python库。因为xiaocong/uiautomator这个库，已经很久不见更新。所以我们直接fork了一个版本，为了方便做区分我们就在后面加了个2 openatx/uiautomator2,对应的Android包源码我也fork了一份，openatx/android-uiautomator-server

除了对原有的库的bug进行了修复，还增加了很多新的Feature。主要有以下部分：

~~设备和开发机可以脱离数据线，通过WiFi互联（基于atx-agent~~
~~集成了openstf/minicap达到实时屏幕投频，以及实时截图~~
~~集成了openstf/minitouch达到精确实时控制设备~~
修复了xiaocong/uiautomator经常性退出的问题
代码进行了重构和精简，方便维护
实现了一个设备管理平台(也支持iOS) atxserver2 （注：目前不怎么维护了）
扩充了toast获取和展示的功能（需要手动开启ATX的悬浮窗权限）貌似有bug用不了

这里要先说明下，因为经常有很多人问 openatx/uiautomator2 并不支持iOS测试，需要iOS自动化测试，可以转到这个库 openatx/facebook-wda。

PS: 这个库 ~~https://github.com/NeteaseGame/ATX~~ 目前已经不维护了，请尽快更换。

这里有一份快速参考，适合已经入门的人 QUICK REFERENCE GUIDE，欢迎多提意见。

Requirements

Android版本 4.4+
Python 3.8+

QUICK START

先准备一台（不要两台）开启了开发者选项的安卓手机，连接上电脑，确保执行adb devices可以看到连接上的设备。

运行pip3 install -U uiautomator2 安装uiautomator2

命令行运行python打开python交互窗口。然后将下面的命令输入到窗口中。

import uiautomator2 as u2

d = u2.connect() # connect to device
print(d.info)

这时看到类似下面的输出，就可以正式开始用我们这个库了。因为这个库功能太多，后面还有很多的内容，需要慢慢去看 ....

{'currentPackageName': 'net.oneplus.launcher', 'displayHeight': 1920, 'displayRotation': 0, 'displaySizeDpX': 411, 'displaySizeDpY': 731, 'displayWidth': 1080, 'productName': 'OnePlus5', '
screenOn': True, 'sdkInt': 27, 'naturalOrientation': True}

另外为了保持稳定，还需要开启小黄车的悬浮窗权限。参考文章 py-uiautomator2通过悬浮窗让服务长时间可用

一般情况下都会成功，不过也可能会有意外。可以加QQ群反馈问题(群号在最上面），群里有很多大佬可以帮你解决问题。

Article Recommended

优秀文章推荐 (欢迎QQ群里at我反馈）

termux里如何部署uiautomator2简介 by 成都-测试只会一点点

相关项目

基于adb协议与Android进行交互的库 adbutils
uiauto.dev 用于查看UI层级结构，类似于uiautomatorviewer(用于替代之前写的weditor），用于查看UI层级结构
设备管理平台，设备多了就会用到 atxserver2 （寻找项目维护人员）
~~atx-agent 运行在设备上的驻守程序，go开发，用于保活设备上相关的服务~~
~~weditor 类似于uiautomatorviewer，专门为本项目开发的辅助编辑器(这个暂不维护了~~

Installation

Connect to a device

Command line

Global settings

Debug HTTP requests
Implicit wait

App management

Install an app
Launch an app
Stop an app
Stop all running apps
Push and pull files
Other app operations

cheme)**

**[UI automation](#basic-api-usages)**
- **[Shell commands](#shell-commands)**
- **[Session](#session)**
- **[Retrieve the device info](#retrieve-the-device-info)**
- **[Key Events](#key-events)**
- **[Gesture interaction with the device](#gesture-interaction-with-the-device)**
- **[Screen-related](#screen-related)**
- **[Selector](#selector)**
- **[Watcher](#watcher)**
- **[Global settings](#global-settings)**
- **[Input method](#input-method)**
- **[Toast](#toast)**
- **[XPath](#xpath)**
- **[Screenrecord](#screenrecord)**
- **[Image match](#image-match) Removed**


**[Contributors](#contributors)**

**[LICENSE](#license)**


# Installation
1. Install uiautomator2

  ```bash
  pip install -U uiautomator2
  ```
  
  测试是否安装成功 `uiautomator2 --help`
  
2. UI Inspector

  ```bash
  pip install uiautodev
  # 启动
  uiauto.dev
  ```

  浏览器打开 https://uiauto.dev 查看当前设备的界面结构。

  **uiauto.dev**

  [uiauto.dev](https://github.com/codeskyblue/uiauto.dev) 是一个独立与uiautomator2之外的一个项目，用于查看图层结构的。属于旧版项目[weditor的重构版本](https://github.com/openatx/weditor)，后续也许会收费（价格肯定物超所值），来支持当前这个项目继续维护下去。感兴趣的可以加群讨论(也包含提需求) QQ群 536481989

# Connect to a device
use serialno to connect device eg. `123456f` (seen from `adb devices`)

```python
import uiautomator2 as u2

d = u2.connect('123456f') # alias for u2.connect_usb('123456f')
print(d.info)

Serial can be passed through env-var ANDROID_SERIAL

# export ANDROID_SERIAL=123456f
d = u2.connect()

Command line

其中的$device_ip代表设备的ip地址

如需指定设备需要传入--serial 如 python3 -m uiautomator2 --serial bff1234 <SubCommand>, SubCommand为子命令（screenshot, current 等）

1.0.3 Added: python3 -m uiautomator2 equals to uiautomator2

screenshot: 截图

$ uiautomator2 screenshot screenshot.jpg

current: 获取当前包名和activity

$ uiautomator2 current
{
    "package": "com.android.browser",
    "activity": "com.uc.browser.InnerUCMobile",
    "pid": 28478
}

uninstall： Uninstall app

$ uiautomator2 uninstall <package-name> # 卸载一个包
$ uiautomator2 uninstall <package-name-1> <package-name-2> # 卸载多个包
$ uiautomator2 uninstall --all # 全部卸载

stop: Stop app

$ uiautomator2 stop com.example.app # 停止一个app
$ uiautomator2 stop --all # 停止所有的app

doctor:

$ uiautomator2 doctor
[I 2024-04-25 19:53:36,288 __main__:101 pid:15596] uiautomator2 is OK

API Documents

New command timeout （Removed)

When python quit, the UiAutomation service also quit.

Debug HTTP requests

打印出代码背后的HTTP请求信息

>>> d.debug = True
>>> d.info
12:32:47.182 $ curl -X POST -d '{"jsonrpc": "2.0", "id": "b80d3a488580be1f3e9cb3e926175310", "method": "deviceInfo", "params": {}}' 'http://127.0.0.1:54179/jsonrpc/0'
12:32:47.225 Response >>>
{"jsonrpc":"2.0","id":"b80d3a488580be1f3e9cb3e926175310","result":{"currentPackageName":"com.android.mms","displayHeight":1920,"displayRotation":0,"displaySizeDpX":360,"displaySizeDpY":640,"displayWidth":1080,"productName"
:"odin","screenOn":true,"sdkInt":25,"naturalOrientation":true}}
<<< END

Implicit wait

设置元素查找等待时间（默认20s）

d.implicitly_wait(10.0) # 也可以通过d.settings['wait_timeout'] = 10.0 修改
d(text="Settings").click() # if Settings button not show in 10s, UiObjectNotFoundError will raised

print("wait timeout", d.implicitly_wait()) # get default implicit wait

This function will have influence on click, long_click, drag_to, get_text, set_text, clear_text, etc.

App management

This part showcases how to perform app management

Install an app

We only support installing an APK from a URL

d.app_install('http://some-domain.com/some.apk')

Launch an app

# 默认的这种方法是先通过atx-agent解析apk包的mainActivity，然后调用am start -n $package/$activity启动
d.app_start("com.example.hello_world")

# 使用 monkey -p com.example.hello_world -c android.intent.category.LAUNCHER 1 启动
# 这种方法有个副作用，它自动会将手机的旋转锁定给关掉
d.app_start("com.example.hello_world", use_monkey=True) # start with package name

# 通过指定main