Android便利API

以下是 Android Convenience API 函数的快速链接

androidUiAutomator()

此函数在 Android OS API 级别 18 或更高版本（Android-4.3 或更高版本）时返回一个 UiAutomator 对象。当需要从 Squish 测试脚本访问 android.support.test.uiautomator 类和对象时使用。

字符串 defaultDevice

此只读属性是 squishinfo 对象 的属性，包含在 squishide 中选中的或传递给 squishrunner 的 --device 选项的 Android 设备字符串。

doubleTap(objectOrName)

doubleTap(objectOrName, x, y)

此函数在指定的 objectOrName 小部件上进行双击。x 和 y 坐标可选。如果未指定，则在组件的中心位置进行双击。另一方面，如果提供了附加参数，则在 objectOrName 小部件坐标中的 x 和 y 位置进行双击。

goBack(objectOrName)

此函数点击 Android 返回按钮。指定的 objectOrName 可以引用任何可见的对象，尽管 Squish 将记录具有输入焦点对象。

goHome()

当 UiAutomation 启用时，此函数点击 Android 主页按钮。否则，此函数不执行任何操作。

goRecents()

当 UiAutomation 启用时，此函数点击 Android 最近应用按钮。否则，此函数抛出异常。

goNotifications}

当 UiAutomation 启用时，此函数打开 Android 通知。否则，此函数抛出异常。

goQuickSettings}

当 UiAutomation 启用时，此函数打开 Android 快速设置。否则，此函数抛出异常。

gesture(objectOrName, touches)

此函数播放手势。指定的 objectOrName 可以引用任何可见对象，仅用于同步。指定的 touches 指的是使用 readGesture(gesture-file) 获取的 GestureBuilder 对象。

hideKeyboard(object)

此函数在软键盘显示时隐藏它。指定的object可以引用任何可见对象。Object waitForObject(objectOrName)也会隐式地隐藏软键盘。

隐藏键盘对AccessibilityNode对象不起作用。

installEventHandler(eventName, handlerFunctionNameOrReference)

此函数安装一个全局事件处理器。在handlerFunctionNameOrReference中命名的或引用的脚本函数，将在发生eventName类型的事件时被调用。

eventName可以是以下任何事件类型的名称：

• BannerShowed在显示android.widget.Toast时发生
• DialogOpened在显示android.app.AlertDialog时发生
• Vibrate当应用程序调用Android API函数android.os.Vibrator.vibrate时发生

在handlerFunctionName中命名的函数将使用一个参数调用——显示的对象。

有关示例，请参阅如何使用事件处理器。

longPress(objectOrName)

longPress(objectOrName, x, y)

此函数通过在指定的objectOrName小部件上按2秒来实现点击。坐标x和y是可选的。如果没有指定，则在小部件的中心处进行点击。另一方面，如果提供了额外的参数，则在小部件的x和y坐标位置进行点击。

longPressAndDrag(objectOrName, dx, dy)

longPressAndDrag(objectOrName, x, y, dx, dy)

此函数执行一个触摸拖动操作，首先按下2秒，然后拖动指定的objectOrName小部件。该小部件通过水平移动dx像素并在垂直方向上移动dy像素来移动。坐标x和y是可选的。如果没有指定，则在小部件的中心处进行初始按下。另一方面，如果提供了额外的参数，则在小部件的x和y位置（在小部件的坐标中）进行初始按下。

openMenu(objectOrName)

此函数点击Android菜单按钮。指定的objectOrName可以引用任何可见对象，尽管Squish会记录具有输入焦点的对象。

Object nativeObject

Squish自动为每个Android对象添加一个名为nativeObject的属性。本地对象提供访问所有底层对象的方法和属性的途径。

有关如何使用nativeObject的示例，请参阅如何使用nativeObject属性。

nativeGesture(touches)

该函数通过使用Android的shell命令来执行手势操作，因此它在Squish启动的应用程序外部运行。仅重新播放手势文件中的第一个笔划（即一只手指的触摸）。指定的touches指的是一个GestureBuilder对象，可以通过readGesture(gesture-file)使用。

nativeTap(x, y)

该函数通过Android的shell命令执行触摸操作，因此它在Squish启动的应用程序外部运行。参数x和y相对于屏幕的左上角。

readGesture(gesture-file)

该函数从测试套件目录打开手势文件，并返回一个GestureBuilder对象。然后可以将它传递给gesture(objectOrName, touches)。指定的gesture-file引用的是文件名。

startObserver()

仅在将–no-autostart-observer指定为androidobserver的启动参数，或者调用过stopObserver()时，应使用此函数。当observer没有运行时，具有弹出窗口、下拉菜单和对话框的对象识别会受到限制，或者根本无法工作。

stopObserver()

此函数用于停止observer。当在Squish下运行应用程序时，若应用程序执行中的某个部分变得非常缓慢，可以使用此函数。有关再次启用observer的信息，请参阅startObserver()。

tapMenuItem(objectOrName)

此函数执行菜单操作。指定的objectOrName可以指代任何可见对象，尽管Squish将记录当前的Activity对象。

此函数在有障碍节点的对象上不工作。此外，必须在尚打开的应用程序菜单情况下运行，否则此函数将失败。

tapObject(objectOrName)

tapObject(objectOrName, x, y)

此函数在指定的objectOrName小部件上执行触摸操作。坐标x和y是可选的。如果没有指定，则在小部件的中心执行触摸。另一方面，如果提供了附加参数，则在objectOrName小部件的坐标中，在位置x和y处执行点击。

touchAndDrag(objectOrName, x, y, dx, dy)

此函数执行触摸拖动操作。它从x和y位置启动objectOrName小部件的拖动操作。小部件沿水平方向拖动dx像素，沿垂直方向拖动dy像素。

type(objectOrName, text)

此函数将指定的text（如用户使用键盘一样）输入到可编辑的小部件objectOrName中。如果文本被尖括号（<>）包围，则它被解释为键组合，例如"<Ctrl+Return>"。输入是大小写敏感的，因此type(object, "R")与type(object, "r")不同。（有关支持的特殊键列表，请参阅nativeType(keys)函数的文档。）

卸载事件处理函数(eventName, 处理工函数名或引用)

此函数用于卸载之前使用 installEventHandler(eventName, handlerFunctionNameOrReference) 安装的事件处理函数。

WebView.evalJS(script)

这是一个方便的函数，用于 android.webkit.WebView.evaluateJavaScript。目标 WebView 是一个类型为 WebView 的 UI 元素，而 script 参数是某些 JavaScript 代码。此函数返回 JavaScript 评估结果作为字符串。

var webview = waitForObject(":some_WebView");
test.log("Pixel ratio is " + webview.evalJS("window.top.devicePixelRatio"));

my $webview = waitForObject(":some_WebView");
test::log("Pixel ratio is " . $webview->evalJS("window.top.devicePixelRatio"));

webview = waitForObject(":some_WebView")
test.log("Pixel ratio is " + webview.evalJS("window.top.devicePixelRatio"))

webview = waitForObject(":some_WebView")
Test.log("Pixel ratio is " + webview.evalJS("window.top.devicePixelRatio"))

set webview [waitForObject ":some_WebView"]
test log [concat "Pixel ratio is" [webview evalJS "window.top.devicePixelRatio"]]

GestureBuilder

此类对象保存了用于重新播放 gesture(objectOrName, touches) 所需的触摸笔迹信息。此类的实例是通过 readGesture(gesture-file) 返回的。笔迹由屏幕坐标点、压力和触摸大小定义。

有关如何使用 GestureBuilder 对象来操作手势信息，请参阅 如何使用 GestureBuilder 类 的示例。

int GestureBuilder.areaWidth

此手势定义的区域宽度。这将是大屏或仿真器屏幕宽度。

int GestureBuilder.areaHeight

此手势定义的区域高度。这将是大屏或仿真器屏幕高度。

在GestureBuilder 类的手势创建和手势操作部分中列出的所有 GestureBuilder 方法返回的是 GestureBuilder 对象本身，除非有其他指定。

手势创建

本节列出了用于手动创建 GestureBuilder 对象的方法。

GestureBuilder(width, height, unit)

GestureBuilder(xml)

用于创建 GestureBuilder 对象的两个构造函数。参数 width 和 height 是目标屏幕大小。参数 unit 可以是 0 或 1，分别表示像素或毫米。也可以使用常量 GestureBuilder.Pixel 和 GestureBuilder.MilliMeter。

第二个构造函数通过传递包含 XML 的字符串来构建 GestureBuilder 对象，该 XML 应与记录的手势文件格式相同。

Object GestureBuilder.addStroke(x, y)

Object GestureBuilder.addStroke(startTime, x, y)

Object GestureBuilder.addStroke(startTime, x, y, pressure)

Object GestureBuilder.addStroke(startTime, x, y, pressure, size)

开始新的笔划。从触屏到释放整个过程，一个手指或笔的运动被称为笔划。触屏坐标是（《code translate="no">x，《code translate="no">y）。对于非第一次笔划，可以使用《code translate="no">startTime》参数指定时间偏移（以毫秒为单位）。笔划在时间上不能有间隙，在整个手势过程中至少有一个手指或笔必须按下。最大同时触控数取决于设备。

最后，《code translate="no">pressure和《code translate="no">size分别是笔或手指的压力和大小相对于测量值。这些值应在0.0到1.0之间，省略时默认为0.25。

Object GestureBuilder.curveTo(duration, controlX, controlY, endX, endy)

Object GestureBuilder.curveTo(duration, control1X, control1Y, control2X, control2Y, endX, endy)

在最后添加的笔划中添加贝塞尔曲线运动，持续《code translate="no">duration毫秒。曲线从最后添加的运动的终点坐标开始，如果没有添加到笔划中，则从笔划的触屏坐标开始。终点坐标由《code translate="no">endX和《code translate="no">endY指定的。可以使用一个或两个所谓的控制点。

Object GestureBuilder.lineTo(duration, endX, endy)

在最后添加的笔划中添加直线运动，持续《code translate="no">duration毫秒。线从最后添加的运动的终点坐标开始，如果没有添加到笔划中，则从笔划的触屏坐标开始。终点坐标由《code translate="no">endX和《code translate="no">endY指定。

Object GestureBuilder.build()

从添加的笔划和运动中创建手势。调用此方法后，不能再添加笔划或运动。

手势操作

Object GestureBuilder.accelerate(factor)

根据一个系数改变笔划速度。系数在0.0和1.0之间会减慢手势，高于1.0将加快手势。

Object GestureBuilder.rotate(degrees)

Object GestureBuilder.rotate(degrees, originX, originY)

旋转笔划。《code translate="no">degrees是以逆时针方向度数计的角度。originX和originY定义了旋转操作的起点。如果省略，则取区域中心为起点。

Object GestureBuilder.scale(scale)

Object GestureBuilder.scale(scaleX, scaleY)

Object GestureBuilder.scale(scaleX, scaleY, originX, originY)

改变笔划的大小。scaleX是水平方向的缩放系数，scaleY是垂直方向的缩放系数。originX和originY定义了缩放操作的起点。如果省略，则取区域中心为起点。如果也省略scaleY，则缩放在两个方向上是同等的。

Object GestureBuilder.translate(x, y)

移动笔画。`x` 和 `y` 参数指定移动的方向。`x` 的正值将笔画向右移动，`y` 的正值将笔画向下移动。

UiAutomator

此类对象允许测试脚本在 `android.support.test.uiautomator` 类和对象上运行方法。通过调用 androidUiAutomator() 来获取 `UiAutomator` 的一个实例。

要求 Android 操作系统的 API 级别为 18 或更高（Android 4.3 或更高版本）。

以下是一个示例脚本的等效脚本，该脚本按下 Android 的“home”按钮、打开 Android 远程启动器，并从第二个屏幕打开设置应用。使用对象名称 `:Apps_Clickable`，它代表 description='Apps' simpleName='TextView' type='Clickable' visible='true'，`:_AccessiblePanel` 代表 simpleName='FrameLayout' type='AccessiblePanel' visible='true'，和 `:Settings_Clickable` 代表 simpleName='TextView' text='Settings' type='Clickable' visible='true'。

goHome()
tapObject(waitForObject(":Apps_Clickable"))
geom = Screen.byIndex(0).geometry
w = geom.width
touchAndDrag(waitForObject(":_AccessiblePanel"), w-10, geom.height/2, 20-w, 0)
tapObject(waitForObject(":Settings_Clickable"))

使用 UiAutomator 的等效片段为

var au = androidUiAutomator();

//press home
var dev = au.getDevice();
dev.pressHome();

//open application launcher
var sel = au.createSelector().description("Apps");
var obj = au.createObject(sel);
obj.click();

//swipe right to left
var y = dev.displayHeight / 2;
dev.swipe(dev.displayWidth - 10, y, 10, y, 50);

//open settings app
sel = au.createSelector().text("Settings");
obj = au.createObject(sel);
obj.click();

my $au = androidUiAutomator();

#press home
my $dev = $au->getDevice();
$dev->pressHome();

#open application launcher
my $sel = $au->createSelector()->description("Apps");
my $obj = $au->createObject($sel);
$obj->click();

#swipe right to left
my $y = $dev->displayHeight / 2;
$dev->swipe($dev->displayWidth - 10, $y, 10, $y, 50);

#open settings app
$sel = $au->createSelector()->text("Settings");
$obj = $au->createObject($sel);
$obj->click();

au = androidUiAutomator()

#press home
dev = au.getDevice()
dev.pressHome()

#open application launcher
sel = au.createSelector().description("Apps")
obj = au.createObject(sel)
obj.click()

#swipe right to left
y = dev.displayHeight / 2
dev.swipe(dev.displayWidth - 10, y, 10, y, 50)

#open settings app
sel = au.createSelector().text("Settings")
obj = au.createObject(sel)
obj.click()

au = androidUiAutomator()

#press home
dev = au.getDevice()
dev.pressHome()

#open application launcher
sel = au.createSelector().description("Apps")
obj = au.createObject(sel)
obj.click()

#swipe right to left
y = dev.displayHeight / 2
dev.swipe(dev.displayWidth - 10, y, 10, y, 50)

#open settings app
sel = au.createSelector().text("Settings")
obj = au.createObject(sel)
obj.click()

set au [invoke androidUiAutomator]

#press home
set dev [invoke $au getDevice]
invoke $dev pressHome

#open application launcher
set sel [invoke [invoke $au createSelector] description "Apps"]
set obj [invoke $au createObject $sel]
invoke $obj click

#swipe right to left
set y [expr [property get $dev displayHeight] / 2]
invoke $dev swipe [expr [property get $dev displayWidth] - 10] $y 10 $y 50

#open settings app
set sel [invoke [invoke $au createSelector] text "Settings"]
set obj [invoke $au createObject $sel]
invoke $obj click

UiAutomator.getDevice

返回一个 android.support.test.UiDevice 对象。通过调用 android.support.test.UiDevice.getInstance 并使用 SquishHook 作为 instrumentation 参数来获取。

UiAutomator.createSelector

返回一个新创建的 android.support.test.uiautomator.UiSelector 对象。

UiAutomator.createObject(selector)

对于 selector 参数返回一个新创建的 android.support.test.uiautomator.UiObject 对象。

UiAutomator.getBy

返回一个 android.support.test.uiautomator.By 类，并可调用静态方法以创建 android.support.test.uiautomator.BySelector 对象。

UiAutomator.getUntil

返回一个 android.support.test.uiautomator.Until 类，并可调用该类上的静态方法。