Android之UiAutomator测试框架源码分析（第三篇：UiDevice功能介绍）

作者：你好赵伟 | 2024-03-26 07:25:28

踩

uidevice

（注意：本文基于UI Automator测试框架版本为2.2.0）

UiDevice类位于androidx.test.uiautomator包中，作为UI Automator测试框架中最重要的类之一，使用UI Automator测试框架就一定需要创建UiDevice对象。

UiDevice对象包含大部分我们需要用到的功能：查找控件、Android设备上执行shell命令、获取Android设备屏幕信息等等……创建的每个UiDevice对象表示当前的Android设备，Android操作系统在各种设备上都能运行，只要使用Android系统的设备都在设备范围内，可以是一个手机、一个手表、一个电视、一个手环、等等！

UiDevice对象是作为单例对象存在的，无论我们获取几次，其实是同一个UiDevice对象，通过UiDevice的静态方法getInstance(Instrumentation instrumentation)可以获得一个UiDevice对象，这也是唯一的方式，new的方式已被限制使用。

学习UiDevice的API时，众多功能一时让我们有点蒙蔽。记住一句话：官方提供的API，则说明这个功能一定在某种需求下有它的价值，你可以暂时不用某个API，但是以后可能还是会使用，这取决你的需求，所以先熟悉一下API非常重要。

按照UiDevice提供的功能，按照相关性做一个分类，总体上分为5个类别，它们是：

1、与控件相关的功能，比如查找控件，获取控件树信息（数据结构）到文件或者内存中、查找多个控件、某个控件是否存在、找不到控件时的回调处理、等待界面绘制

2、与设备屏幕相关的功能，比如获取屏幕分辨率

3、与设备特性相关的功能，比如按下back键、点击某个坐标、滑动一段距离

4、与Android系统shell相关的功能，比如可以执行shell命令，甚至你可以使用它启动Monkey程序（需root）

5、与被测App相关的功能，比如获取包名

下面就按照顺序介绍这些功能……

与控件相关的功能

void	clearLastTraversedText() 清除上次UI遍历事件中的文本
String 最后一次遍历事件的文本，否则返回一个空字符串	getLastTraversedText() 从接收到的最后一个UI遍历事件中检索文本。详细介绍：从收到的最后一个UI遍历事件中检索文本。您可以使用此方法来读取WebView容器中的内容，因为当每个文本被突出显示时，可访问性框架将触发事件。您可以编写一个测试来执行方向箭头按下以聚焦于WebView中的不同元素，并调用这个方法来从每个遍历的元素中获取文本。如果您正在测试一个可以返回对文档对象模型(DOM)对象的引用的视图容器，那么您的测试应该使用视图的DOM。（API详细描述或源码中都能看到方法的描述）
boolean	click(int x, int y) 在用户指定的任意坐标（x,y）处执行单击行为，屏幕任意坐标的点击事件，最后一定会触发到一个控件中！
boolean	drag(int startX, int startY, int endX, int endY, int steps) 从一个坐标滑动到另一个坐标，坐标之间的手势滑动，受影响到一定是控件！
void	dumpWindowHierarchy(File dest) 将当前窗口的层次结构（View树）转储到一个文件中，这个文件是不是可以通过一个工具打开？是的，通过Uiautomatorviewer工具即可打开
void	dumpWindowHierarchy(OutputStream out) 将当前窗口层次结构转储到OutputStream对象中，卧槽，可以通过网络传输View树结构了……
void	dumpWindowHierarchy(String fileName) 不推荐使用这种方法。使用dumpwindowherarch(文件)或dumpwindowherarch(输出流)。
void	setCompressedLayoutHeirarchy(boolean compressed) 启用或禁用布局层次结构压缩。
UiObject	findObject(UiSelector selector) 查找一个控件的方法，返回一个UiObject对象，它是第一个查找到的符合指定选择器条件（UiSelector对象）的视图（View）（不建议用，但是可以用）
UiObject2	findObject(BySelector selector) 查找一个控件的方法，返回第一个匹配选择器条件（BySelector对象）的UiObject2，如果没有找到匹配的UiObject2对象，则会返回null。（建议用这个）
List<UiObject2>	findObjects(BySelector selector) 查找多个控件的方法，返回所有匹配选择器条件BySelector的容器对象List。（如果需要校验屏幕上所有符合要求的控件，这个方法很实用）
boolean	hasObject(BySelector selector) 检查屏幕中是否存在一个指定的控件。返回指定选择器条件对象（BySelector对象）的控件是否被匹配（当前Window中的View树中搜索，只要搜索到一个就算存在）
boolean	hasWatcherTriggered(String watcherName) 检查一个指定名字的已注册的UiWatcher对象是否已被触发过，我们可以根据触发情况，执行一些特定的逻辑，比如监控某个指定的控件，当它一旦出现，我们就干点什么……
boolean	hasAnyWatcherTriggered() 检查是否有任何已注册的UiWatcher对象被触发
void	registerWatcher(String name, UiWatcher watcher) 注册一个UiWatcher对象，当找不到控件时，UiAutomator测试框架中会自动运行所有一已注册的UiWatcher中的checkForCondition（）方法
void	removeWatcher(String name) 移除先前注册的UiWatcher对象
void	resetWatcherTriggers() 重置记录的所有已触发UiWatcher对象
void	runWatchers() 强制通知所有注册的作为观察者的UiWatcher对象运行checkForCondition（）方法
<R> R	performActionAndWait(Runnable action, EventCondition<R> condition, long timeout) 根据条件去执行一个行为，可以设定任务和等待条件，以及等待时长，等待一个设定的条件condition以及设定的最大等待时长timeout，当符合预期条件时会执行一个Runnable对象的run方法。（这个方法骚了）
boolean	swipe(int startX, int startY, int endX, int endY, int steps) 在两个点之间进行手势滑动的方法，从一个坐标滑动到另一个坐标，使用步骤数量steps来确定平滑度和速度
boolean	swipe(Point[] segments, int segmentSteps) 可以在指定的多个点之间进行手势滑动的方法
<R> R	wait(SearchCondition<R> condition, long timeout) 等待给定条件被满足 SearchCondition:要评估的SearchCondition timeout:等待的最长时间，以毫秒为单位。该方法为范型方法，最后的返回值是范型对象
void	waitForIdle(long timeout) 等待当前应用程序空闲，timeout是最大的等待时长
void	waitForIdle() 等待当前应用程序空闲（指主线程空闲）
boolean	waitForWindowUpdate(String packageName, long timeout) 等待发生窗口内容更新事件。

与设备屏幕相关的功能

int	getDisplayHeight() 获取屏幕的高度，单位：像素
int	getDisplayRotation() 返回在Surface中定义的显示的当前旋转角度
Point	getDisplaySizeDp() 返回显示的大小，返回的显示大小根据屏幕旋转进行调整，单位：dp(设备无关像素)
int	getDisplayWidth() 获取屏幕的宽度，单位：像素

boolean	isNaturalOrientation() 检查设备是否处于自然方向
void	setOrientationLeft() 模拟设备向左的方向，并通过禁用传感器来冻结旋转
void	setOrientationNatural() 模拟将设备定向到其自然方向，并通过禁用传感器冻结旋转
void	setOrientationRight() 模拟设备向右定位，并通过禁用传感器来冻结旋转。

boolean

isScreenOn()

检查电源管理器是否已经打开屏幕

void

sleep()

如果屏幕处于开启状态，此方法只需按下电源按钮，否则，如果屏幕已经关闭，它将什么也不做。

void

wakeUp()

这个方法模拟在屏幕关闭时按下电源按钮，否则在屏幕已经打开时它什么也不做

boolean

takeScreenshot(File storePath, float scale, int quality)

获取当前窗口的屏幕截图并将其存储为PNG，屏幕截图会根据屏幕旋转进行调整（我什么需要增加屏幕截图？，增加的屏幕截图不能存储在手机里，那样太不方便，直接发送到后端或者云盘服务中……

boolean

takeScreenshot(File storePath)

选取当前窗口的截图，存储为PNG默认比例1.0f(原始尺寸)，使用90%的质量，截图根据屏幕旋转进行调整

与设备特性相关的功能

void

freezeRotation()

禁用传感器并冻结设备在当前旋转状态下的旋转。（可以禁用传感器）

void

unfreezeRotation()

重新启用传感器并解除设备旋转的冻结，允许其内容随设备物理旋转而旋转。

boolean	pressDPadCenter() 模拟短按中心按钮。
boolean	pressDPadDown() 模拟短按下向下按钮。
boolean	pressDPadLeft() 模拟短按左键。
boolean	pressDPadRight() 模拟短按右按钮。
boolean	pressDPadUp() 模拟短按向上按钮。
boolean	pressDelete() 模拟短按DELETE键。
boolean	pressEnter() 模拟短按回车键。
boolean	pressHome() 模拟短按HOME键。
boolean	pressKeyCode(int keyCode) 使用密钥代码模拟短按。
boolean	pressKeyCode(int keyCode, int metaState) 使用密钥代码（KeyCode）模拟短按。
boolean	pressMenu() 模拟短按菜单按钮。
boolean	pressRecentApps() 模拟短按“最近应用程序”按钮。
boolean	pressSearch() 模拟短按搜索按钮。