Logo
Project Icon

uiautomator2

Python驱动的Android UI自动化测试框架

uiautomator2Android自动化测试Python库UI自动化移动应用测试Github开源项目

uiautomator2是一个开源的Python驱动Android UI自动化测试框架，基于Google的UIAutomator技术。它提供快速稳定的UI自动化能力，支持Android 4.4+设备和Python 3.8+环境。该框架优化了原uiautomator库的稳定性，简化了API接口，提高了Android应用测试效率。uiautomator2还支持设备管理、屏幕操作等扩展功能，为开发者提供全面的自动化测试解决方案。

访问官网访问官网GithubGithub
介绍相关项目

uiautomator2

PyPI PyPI codecov

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.

各种依赖库的版本号

  • PyPI
  • PyPI
  • GitHub tag (latest SemVer)
  • GitHub tag (latest SemVer)

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群反馈问题(群号在最上面），群里有很多大佬可以帮你解决问题。

Sponsors

Thank you to all our sponsors! ✨🍰✨

金牌赞助商（Gold Sponsor）

Empty

Article Recommended

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

相关项目

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

Installation

Connect to a device

Command line

Global settings

App management

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
相关项目
项目侧边栏1项目侧边栏2
推荐项目
Project Cover

豆包MarsCode

豆包 MarsCode 是一款革命性的编程助手，通过AI技术提供代码补全、单测生成、代码解释和智能问答等功能，支持100+编程语言，与主流编辑器无缝集成，显著提升开发效率和代码质量。

Project Cover

AI写歌

Suno AI是一个革命性的AI音乐创作平台，能在短短30秒内帮助用户创作出一首完整的歌曲。无论是寻找创作灵感还是需要快速制作音乐，Suno AI都是音乐爱好者和专业人士的理想选择。

Project Cover

有言AI

有言平台提供一站式AIGC视频创作解决方案，通过智能技术简化视频制作流程。无论是企业宣传还是个人分享，有言都能帮助用户快速、轻松地制作出专业级别的视频内容。

Project Cover

Kimi

Kimi AI助手提供多语言对话支持，能够阅读和理解用户上传的文件内容，解析网页信息，并结合搜索结果为用户提供详尽的答案。无论是日常咨询还是专业问题，Kimi都能以友好、专业的方式提供帮助。

Project Cover

阿里绘蛙

绘蛙是阿里巴巴集团推出的革命性AI电商营销平台。利用尖端人工智能技术，为商家提供一键生成商品图和营销文案的服务，显著提升内容创作效率和营销效果。适用于淘宝、天猫等电商平台，让商品第一时间被种草。

Project Cover

吐司

探索Tensor.Art平台的独特AI模型，免费访问各种图像生成与AI训练工具，从Stable Diffusion等基础模型开始，轻松实现创新图像生成。体验前沿的AI技术，推动个人和企业的创新发展。

Project Cover

SubCat字幕猫

SubCat字幕猫APP是一款创新的视频播放器，它将改变您观看视频的方式！SubCat结合了先进的人工智能技术，为您提供即时视频字幕翻译，无论是本地视频还是网络流媒体，让您轻松享受各种语言的内容。

Project Cover

美间AI

美间AI创意设计平台，利用前沿AI技术，为设计师和营销人员提供一站式设计解决方案。从智能海报到3D效果图，再到文案生成，美间让创意设计更简单、更高效。

Project Cover

稿定AI

稿定设计 是一个多功能的在线设计和创意平台，提供广泛的设计工具和资源，以满足不同用户的需求。从专业的图形设计师到普通用户，无论是进行图片处理、智能抠图、H5页面制作还是视频剪辑，稿定设计都能提供简单、高效的解决方案。该平台以其用户友好的界面和强大的功能集合，帮助用户轻松实现创意设计。

使用协议隐私政策广告服务
投诉举报邮箱: service@vectorlightyear.com
@2024 懂AI·鲁ICP备2024100362号-6·鲁公网安备37021002001498号