介绍

uiautomator2 是一个可以使用Python对Android设备进行UI自动化的库。其底层基于Google uiautomator,Google提供的uiautomator库可以获取屏幕上任意一个APP的任意一个控件属性,并对其进行任意操作。

库地址

GitHub地址:https://github.com/openatx/uiautomator2
文档说明:https://github.com/openatx/uiautomator2/blob/master/README.md

安装

安装uiautomator2

1
2
pip install --pre uiautomator2
pip install pillow (如果需要截图,可安装这个库)

设备安装atx-agent(接收PC端命令,对手机UI进行操作)

首先设备连接到PC,并能够adb devices发现该设备。
执行下面的命令会自动安装本库所需要的设备端程序:uiautomator-server,atx-agent,openstf / minicap,openstf / minitouch

1
2
3
4
5
6
7
8
# init就是所有USB连接电脑的手机上都安装uiautomator2
python -m uiautomator2 init

# 指定手机安装uiautomator2, 用 --mirror
python -m uiautomator2 init --mirror --serial $SERIAL

# 嫌弃慢的话,可以用国内的镜像
python -m uiautomator2 init --mirror

最后提示success,代表atx-agent初始化成功。

注:如果安装完成后,在手机桌面上没有出现名为ATX的应用,说明没有安装成功。需要手动安装APK,路径为:site-packages\uiautomator2\assets,安装包名称为app-uiautomator.apk

安装weditor

有了这个,方便我们快速的识别手机上的元素,方便写代码

1
pip install -U weditor

安装好之后,就可以在命令行运行 weditor --help 确认是否安装成功了。

Windows系统可以使用命令在桌面创建一个快捷方式:

1
weditor --shortcut

在windows cmd中执行上述命令后,会在桌面上创建一个快捷方式。

启动方法:
方法1. 命令行直接输入 weditor 会自动打开浏览器,输入设备的ip或者序列号,点击Connect即可;
方法2. 桌面上双击WEditor快捷方式即可;
方法3. 命令行中执行 python -m weditor

应用及操作

调用uiautomator2的过程

  • 配置手机设备参数,设置具体操作的是哪一台手机
  • 抓取手机上应用的控件,制定对应的控件来进行操作
  • 对抓取到的控件进行操作,比如点击、填写参数等。

设备连接方法,有两种:

python-uiautomator2连接手机的方式有两种,一种是通过WIFI,另外一种是通过USB。两种方法各有优缺点。
WIFI最便利的地方要数可以不用连接数据线,USB则可以用在PC和手机网络不在一个网段用不了的情况。

(1)通过WiFi,假设设备IP 192.168.0.107和您的PC在同一网络中

1
2
import uiautomator2 as u2
d = u2.connect('192.168.0.107') #d=device对象

(2)通过USB, 假设设备序列是123456789F

1
2
3
import uiautomator2 as u2
d = u2.connect('123456789F') # USB链接设备。或者u2.connect_usb('123456f')
#d = u2.connect_usb() 或者 d = u2.connect() ,当前只有一个设备时可以用这个

在没有参数的情况下调用u2.connect(), uiautomator2将从环境变量ANDROID_DEVICE_IP获取设备IP。如果这个环境变量是空的,uiautomator将返回connect_usb,您需要确保只有一个设备连接到计算机。

检查并维持设备端守护进程处于运行状态:

1
d.healthcheck() # 解锁屏幕并启动uiautomator服务

注:该功能从3.0.0开始不可用。

打开调试开关:

1
2
d.debug = True
d.info

安装应用,只能从URL安装:

1
d.app_install('http://some-domain.com/some.apk') #引号内为下载apk地址

启动应用:

1
d.app_start('com.eg.android.AlipayGphone') #引号内为包名称,这里为支付宝

停止应用:

1
2
3
4
5
#相当于'am force-stop'强制停止应用
d.app_stop('com.eg.android.AlipayGphone')

#相当于'pm clear' 清空App数据
d.app_clear('com.eg.android.AlipayGphone')

停止所有正在运行的应用程序:

1
2
3
4
5
# 停止所有
d.app_stop_all()

# 停止所有应用程序,除了com.examples.demo
d.app_stop_all(excludes=['com.examples.demo'])

跳过弹窗,禁止弹窗:

1
2
d.disable_popups() # 自动跳过弹出窗口
d.disable_popups(False) # 禁用自动跳过弹出窗

获取设备信息:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# 获取基本信息
d.info

# 获取窗口大小
print(d.window_size())
# 设备垂直输出示例: (1080, 1920)
# 设备水平输出示例: (1920, 1080)

# 获取当前应用程序信息。对于某些android设备,输出可以为空
print(d.current_app())

#获取设备序列号
print(d.serial)

#获取WIFI IP
print(d.wlan_ip)

#获取详细的设备信息
print(d.device_info)

获取应用信息:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
d.app_info("com.eg.android.AlipayGphone")
# 会输出
'''
{
"packageName": "com.eg.android.AlipayGphone",
"mainActivity": "com.eg.android.AlipayGphone.AlipayLogin",
"label": "支付寶",
"versionName": "10.2.13.9020",
"versionCode": 360,
"size": 108306104
}
'''

# 保存应用程序图标
img = d.app_icon("com.eg.android.AlipayGphone")
img.save("icon.png")

推拉文件:
(1)将文件推送到设备

1
2
3
4
5
6
7
8
9
10
11
12
# push文件夹
d.push("foo.txt", "/sdcard/")

# push和重命名
d.push("foo.txt", "/sdcard/bar.txt")

# push fileobj
with open("foo.txt", 'rb') as f:
d.push(f, "/sdcard/")

# 推动和更改文件访问模式
d.push("foo.sh", "/data/local/tmp/", mode=0o755)

(2)从设备中拉出一个文件

1
2
3
4
d.pull("/sdcard/tmp.txt", "tmp.txt")

# 如果在设备上找不到文件,FileNotFoundError将引发
d.pull("/sdcard/some-file-not-exists.txt", "tmp.txt")

关键事件:
(1)打开/关闭屏幕

1
2
d.screen_on()#打开屏幕
d.screen_off() #关闭屏幕

(2)获取当前屏幕状态

1
d.info.get('screenOn') # 需要 Android> = 4.4

(3)硬键盘和软键盘操作

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
d.press("home") # 点击home键
d.press("back") # 点击back键
d.press("left") # 点击左键
d.press("right") # 点击右键
d.press("up") # 点击上键
d.press("down") # 点击下键
d.press("center") # 点击选中
d.press("menu") # 点击menu按键
d.press("search") # 点击搜索按键
d.press("enter") # 点击enter键
d.press("delete") # 点击删除按键
d.press("recent") # 点击近期活动按键
d.press("volume_up") # 音量+
d.press("volume_down") # 音量-
d.press("volume_mute") # 静音
d.press("camera") # 相机
d.press("power") #电源键

(4)解锁屏幕

1
2
3
4
d.unlock()
# 相当于
# 1. 发射活动:com.github.uiautomator.ACTION_IDENTIFY
# 2. 按home键

手势与设备的交互:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
# 单击屏幕
d.click(x,y) # x,y为点击坐标

# 双击屏幕
d.double_click(x,y)
d.double_click(x,y,0.1) # 默认两个单击之间间隔时间为0.1秒

# 长按
d.long_click(x,y)
d.long_click(x,y,0.5) # 长按0.5秒(默认)

# 滑动
d.swipe(sx, sy, ex, ey)
d.swipe(sx, sy, ex, ey, 0.5) #滑动0.5s(default)

#拖动
d.drag(sx, sy, ex, ey)
d.drag(sx, sy, ex, ey, 0.5)#拖动0.5s(default)
# 滑动点 多用于九宫格解锁,提前获取到每个点的相对坐标(这里支持百分比)

# 从点(x0, y0)滑到点(x1, y1)再滑到点(x2, y2)
# 两点之间的滑动速度是0.2秒
d.swipe((x0, y0), (x1, y1), (x2, y2), 0.2)

# 注意:单击,滑动,拖动操作支持百分比位置值。例:
d.long_click(0.5, 0.5) 表示长按屏幕中心
XPath:

# 检索方向
d.orientation
# 检索方向。输出可以是 "natural" or "left" or "right" or "upsidedown"

# 设置方向
d.set_orientation("l") # or "left"
d.set_orientation("r") # or "right"
d.set_orientation("n") # or "natural"

#冻结/ 开启旋转
d.freeze_rotation() # 冻结旋转
d.freeze_rotation(False) # 开启旋转

########## 截图 ############
# 截图并保存到电脑上的一个文件中,需要Android>=4.2。
d.screenshot("home.jpg")

# 得到PIL.Image格式的图像. 但你必须先安装pillow
image = d.screenshot() # default format="pillow"
image.save("home.jpg") # 或'home.png',目前只支持png 和 jpg格式的图像

# 得到OpenCV的格式图像。当然,你需要numpy和cv2安装第一个
import cv2
image = d.screenshot(format='opencv')
cv2.imwrite('home.jpg', image)

# 获取原始JPEG数据
imagebin = d.screenshot(format='raw')
open("some.jpg", "wb").write(imagebin)

#############################
# 转储UI层次结构
# get the UI hierarchy dump content (unicoded).(获取UI层次结构转储内容)
d.dump_hierarchy()

# 打开通知或快速设置
d.open_notification() #下拉打开通知栏
d.open_quick_settings() #下拉打开快速设置栏

# 检查特定的UI对象是否存在
d(text="Settings").exists # 返回布尔值,如果存在则为True,否则为False
d.exists(text="Settings") # 另一种写法

# 高级用法
d(text="Settings").exists(timeout=3) # 等待'Settings'在3秒钟出现

# 获取特定UI对象的信息
d(text="Settings").info

# 获取/设置/清除可编辑字段的文本(例如EditText小部件)
d(text="Settings").get_text() #得到文本小部件
d(text="Settings").set_text("My text...") #设置文本
d(text="Settings").clear_text() #清除文本

# 获取Widget中心点
d(text="Settings").center()
#d(text="Settings").center(offset=(0, 0)) # 基准位置左前

UI对象有五种定位方式:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
# text、resourceId、description、className、xpath、坐标
# 执行单击UI对象

#text定位单击
d(text="Settings").click()
d(text="Settings", className="android.widget.TextView").click()

#resourceId定位单击
d(resourceId="com.ruguoapp.jike:id/tv_title", className="android.widget.TextView").click()

#description定位单击
d(description="设置").click()
d(description="设置", className="android.widget.TextView").click()

#className定位单击
d(className="android.widget.TextView").click()

#xpath定位单击
d.xpath("//android.widget.FrameLayout[@index='0']/android.widget.LinearLayout[@index='0']").click()

#坐标单击
d.click(182, 1264)

# 等待元素出现(最多10秒),出现后单击
d(text="Settings").click(timeout=10)

# 在10秒时点击,默认的超时0
d(text='Skip').click_exists(timeout=10.0)

# 单击直到元素消失,返回布尔
d(text="Skip").click_gone(maxretry=10, interval=1.0) # maxretry默认值10,interval默认值1.0

# 点击基准位置偏移
d(text="Settings").click(offset=(0.5, 0.5)) # 点击中心位置,同d(text="Settings").click()
d(text="Settings").click(offset=(0, 0)) # 点击左前位置
d(text="Settings").click(offset=(1, 1)) # 点击右下

# 执行双击UI对象
d(text="设置").double_click() # 双击特定ui对象的中心
d.double_click(x, y, 0.1) # 两次单击之间的默认持续时间为0.1秒

#执行长按UI对象
# 长按特定UI对象的中心
d(text="Settings").long_click()
d.long_click(x, y, 0.5) # 长按坐标位置0.5s默认

# 将UI对象拖向另一个点或另一个UI对象
# Android<4.3不能使用drag.
# 在0.5秒内将UI对象拖到屏幕点(x, y)
d(text="Settings").drag_to(x, y, duration=0.5)

# 将UI对象拖到另一个UI对象的中心位置,时间为0.25秒
d(text="Settings").drag_to(text="Clock", duration=0.25)

常见用法:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
# 等待10s
d.xpath("//android.widget.TextView").wait(10.0)

# 找到并单击
d.xpath("//*[@content-desc='分享']").click()

# 检查是否存在
if d.xpath("//android.widget.TextView[contains(@text, 'Se')]").exists:
print("exists")

# 获取所有文本视图文本、属性和中心点
for elem in d.xpath("//android.widget.TextView").all():
print("Text:", elem.text)

#获取视图文本
for elem in d.xpath("//android.widget.TextView").all():
print("Attrib:", elem.attrib)

#获取属性和中心点
#返回: (100, 200)
for elem in d.xpath("//android.widget.TextView").all():
print("Position:", elem.center())

# xpath常见用法:
# 所有元素
//*
# resource-id包含login字符
//*[contains(@resource-id, 'login')]

# 按钮包含账号或帐号
//android.widget.Button[contains(@text, '账号') or contains(@text, '帐号')]

# 所有ImageView中的第二个
(//android.widget.ImageView)[2]

# 所有ImageView中的最后一个
(//android.widget.ImageView)[last()]

# className包含ImageView
//*[contains(name(), "ImageView")]

中文输入

1、set_text() 只能输入英文

2、输入中文要: 先切换为FastInputIME输入法,然后用 send_keys()

1
2
3
4
d(resourceId="com.lianjia.beike:id/a7r").click()     # 输入之前对输入框进行click()操作,用来获取焦点
d.set_fastinput_ime(True) # 切换成FastInputIME输入法
d.send_keys("保利学府里") # adb广播输入
d.set_fastinput_ime(False) # 切换成正常的输入法