Android Convenience API

Here are some quick links to the Android Convenience API's functions:

androidUiAutomator()

This function returns a UiAutomator object, when the Android OS is at API level 18 or higher (Android-4.3 or later). Which should be used when accessing the android.support.test.uiautomator classes and objects from a Squish test script.

String defaultDevice

This read-only property of squishinfo object holds the Android device string that is selected in the squishide or passed as --device option to squishrunner.

doubleTap(objectOrName)

doubleTap(objectOrName, x, y)

This function double taps on the specified objectOrName widget. The x and y coordinates are optional. If they are not specified, the double tap is made in the center of the widget. On the other hand, if the additional parameters are given, the double tap is made at position x and y in the objectOrName widget's coordinates.

goBack(objectOrName)

This function taps the Android back button. The specified objectOrName can refer to any object that is visible, though Squish will record the object having the input focus.

goHome()

This function taps the Android home button when UiAutomation is enabled. Otherwise this function does nothing.

goRecents()

This function taps the Android recents button when UiAutomation is enabled. Otherwise this function throws an exception.

goNotifications()

This function opens the Android notifications when UiAutomation is enabled. Otherwise this function throws an exception.

goQuickSettings()

This function opens the Android quick-settings when UiAutomation is enabled. Otherwise this function throws an exception.

gesture(objectOrName, touches)

This function plays a gesture. The specified objectOrName can refer to any object that is visible and serves for synchronization only. The specified touches refers to a GestureBuilder object, which can be retrieved using readGesture(gesture-file).

hideKeyboard(object)

This function hides the soft keyboard when it is showing. The specified object can refer to any object that is visible. Object waitForObject(objectOrName) also implicitly hides the soft keyboard.

Hiding keyboard does not does not work for AccessibilityNode objects.

installEventHandler(eventName, handlerFunctionNameOrReference)

This function installs a global event handler. The script function named or referenced in handlerFunctionNameOrReference, will be called when an event of the eventName type occurs.

The eventName can be the name of any of the following event types:

• BannerShowed occurs when an android.widget.Toast is shown
• DialogOpened occurs when an android.app.AlertDialog is shown
• Vibrate occurs when the app calls the Android API function android.os.Vibrator.vibrate

The function named in handlerFunctionName is called with one argument—the object that was shown.

For examples see How to Use Event Handlers.

longPress(objectOrName)

longPress(objectOrName, x, y)

This function taps by pressing 2s on the specified objectOrName widget. The x and y coordinates are optional. If they are not specified the tap is made in the center of the widget. On the other hand, if the additional parameters are given, the tap is made at position x and y in the objectOrName widget's coordinates.

longPressAndDrag(objectOrName, dx, dy)

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

This function performs a touch drag operation, pressing 2s first then drag, of the specified objectOrName widget. The objectOrName widget is dragged by dx pixels horizontally and by dy pixels vertically. The x and y coordinates are optional. If they are not specified the initial press is made in the center of the widget. On the other hand, if the additional parameters are given, the initial press is made at position x and y (in the objectOrName widget's coordinates).

openMenu(objectOrName)

This function taps the Android menu button. The specified objectOrName can refer to any object that is visible, though Squish will record the object having the input focus.

Object nativeObject

Squish automatically adds a property called nativeObject to every Android object. The native object provides access to all the underlying object's methods and properties.

For examples of how to use the nativeObject see How to Use the nativeObject Property.

nativeGesture(touches)

This function plays a gesture by using Android's shell commands and thus works outside the by Squish started app. Only the first stroke in a gesture file is replayed (i.e., touches for one finger). The specified touches refers to a GestureBuilder object, which can be retrieved using readGesture(gesture-file).

nativeTap(x, y)

This function performs a tap by using Android's shell commands and thus works outside the by Squish started app. The x and y are relative w.r.t. the top-left of the screen.

readGesture(gesture-file)

This function opens a gesture file from a test suite directory and returns a GestureBuilder object. This can then be passed to gesture(objectOrName, touches). The specified gesture-file refers to the filename.

startObserver()

This function should only be used when –no-autostart-observer is specified as launcher argument to androidobserver or when stopObserver() has been called. When the observer is not running, the object recognition with popups, dropdowns and dialogs is limited or will not work at all.

stopObserver()

This function stops the observer. Use this function when a certain part in the app execution becomes very slow when running under Squish. See startObserver() for enabling the observer again.

tapMenuItem(objectOrName)

This function performs a menu action. The specified objectOrName can refer to any object that is visible, though Squish will record the current Activity object.

This function does not work on AccessibilityNode objects. Also the application menu has to be open or else this function will fail.

tapObject(objectOrName)

tapObject(objectOrName, x, y)

This function taps on the specified objectOrName widget. The x and y coordinates are optional. If they are not specified, the tap is made in the center of the widget. On the other hand, if the additional parameters are given, the click is made at position x and y in the objectOrName widget's coordinates.

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

This function performs a touch drag operation. It initiates a drag of the specified objectOrName widget starting at position x and y. The objectOrName widget is dragged by dx pixels horizontally and by dy pixels vertically.

type(objectOrName, text)

This function types the specified text (as if the user had used the keyboard) into the objectOrName editable widget. If the text is surrounded by angle brackets (<>), it is interpreted as a key combination, e.g "<Ctrl+Return>". The input is case-sensitive, so type(object, "R") is different from type(object, "r"). (For a list of the supported special keys see the nativeType(keys) function's documentation.)

uninstallEventHandler(eventName, handlerFunctionNameOrReference)

This function uninstalls an event handler that has been previously installed using installEventHandler(eventName, handlerFunctionNameOrReference).

WebView.evalJS(script)

This function is a convenient for android.webkit.WebView.evaluateJavaScript. The target WebView is a UI element of type WebView and the script argument is some JavaScript code. This function returns the result of the JavaScript evaluation as a string.

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

Objects of this type hold the touch strokes information needed to replay gesture(objectOrName, touches). An instance of this class is returned by readGesture(gesture-file). Strokes are defined by screen coordinates points, pressure and touch size.

For examples of how GestureBuilder objects can be used to manipulate the gesture information, see How to Use the GestureBuilder class.

int GestureBuilder.areaWidth

The width of the area in which this gesture is defined. This will be the device or emulator screen width.

int GestureBuilder.areaHeight

The height of the area in which this gesture is defined. This will be the device or emulator screen height.

All GestureBuilder methods listed in the Gesture creation and Gesture manipulation section, return the GestureBuilder object itself, unless specified differently.

Gesture creation

This section lists the methods for manually creating a GestureBuilder object.

GestureBuilder(width, height, unit)

GestureBuilder(xml)

Two constructor functions for creating a GestureBuilder object. The width and height are the target screen size. The unit can be either 0 or 1, meaning respectively in pixels or millimeters. The constants GestureBuilder.Pixel and GestureBuilder.MilliMeter can be used as well.

The second constructor function constructs a GestureBuilder object by passing a string containing XML, which should be in the same format as the recorded gesture files.

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)

Starts a new stroke. The whole movement of one finger or pen from touch down to releasing the screen is called a stroke. The touch down coordinate is (x, y). For the non-first stroke, a time offset can be specified in milliseconds using the startTime argument. Strokes cannot be disjointed in time, at least one finger or pen has to be down during the whole gesture. The maximum simultaneous touches is device dependent.

Finally, the pressure and size are relative messure values for respectively pen or finger pressure and size. These should be between 0.0 and 1.0 and when omitted defaults to 0.25.

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

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

Adds a bézier curve movement to the latest added stroke in duration milliseconds. The curve starts with the end coordinate of the last added movement or, if none added to the stroke, the stroke touch down coordinate. The end coordinate is specified with endX and endY. One or two so called control points can be used.

Object GestureBuilder.lineTo(duration, endX, endy)

Adds a line movement to the latest added stroke in duration milliseconds. The line starts with the end coordinate of the last added movement or, if none added to the stroke, the stroke touch down coordinate. The end coordinate is specified with endX and endY.

Object GestureBuilder.build()

Creates the gesture from the added strokes and movements. After calling this method, no strokes or movements can be added.

Gesture manipulation

Object GestureBuilder.accelerate(factor)

Changes stroke speed given a factor. A factor between 0.0 and 1.0 slows down the gesture, above 1.0 will speed it up.

Object GestureBuilder.rotate(degrees)

Object GestureBuilder.rotate(degrees, originX, originY)

Rotates the strokes. The degrees is the agle in degrees in a counter clockwise direction. The originX and originY define the origin of the rotate operation. If omitted, the area center is taken as origin.

Object GestureBuilder.scale(scale)

Object GestureBuilder.scale(scaleX, scaleY)

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

Changes the size of the strokes. The scaleX is the scale factor in the horizontal direction and scaleY in the vertical direction. The originX and originY define the origin of the scale operation. If omitted, the area center is taken as origin. When also scaleY is omitted, the scaling is homogeneous in both directions.

Object GestureBuilder.translate(x, y)

Moves the strokes. The x and y specifies the movement. A positive value for x moves the strokes to the right and a positive value for y moves the strokes downwards.

UiAutomator

Objects of this type allows test scripts to run methods on android.support.test.uiautomator classes and objects. Call androidUiAutomator() to get an instance of a UiAutomator instance.

The requirement is that the Android OS is at API level 18 or higher (Android-4.3 or later).

The equivalent script of an example script that presses the Android "Home" button, opens the Android application launcher and from the second screen, opens the Settings app. Using the object names :Apps_Clickable which is description='Apps' simpleName='TextView' type='Clickable' visible='true', :_AccessiblePanel being simpleName='FrameLayout' type='AccessiblePanel' visible='true' and :Settings_Clickable stands for 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"))

The equivalent snippet using UiAutomator is:

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()

Returns a android.support.test.UiDevice object. By calling android.support.test.UiDevice.getInstance and using the SquishHook as instrumentation argument.

UiAutomator.createSelector()

Returns a newly created android.support.test.uiautomator.UiSelector object.

UiAutomator.createObject(selector)

Returns a newly created android.support.test.uiautomator.UiObject object for the selector argument.

UiAutomator.getBy()

Returns the android.support.test.uiautomator.By class on which the static methods can be called to create android.support.test.uiautomator.BySelector objects.

UiAutomator.getUntil()

Returns the android.support.test.uiautomator.Until class on which the static methods can be called.