Mobile Control and Touch Events
Eggplant Functional provides many commands and functions specifically for when you use mobile devices as systems under test (SUTs) as described below. For a summary of of supported SenseTalk commands, functions, and typetext keywords for different mobile devices, see Mobile Commands and Functions by Mobile Device Type.
ADBCallRemote
Function
This function is for Android devices only and requires Android Gateway.
This function is not supported by Sauce Labs.
Behavior: This function executes ADB calls to available Android devices and returns any output received from the ADB command. The ADBCallRemote
function requires a connection through Android Gateway, and can work with an Android device connected remotely to the Eggplant machine.
Parameters: Any call to the Android Debug Bridge (ADB) command line tool, such as push
, pull
, shell
, and logcat
, which you can use with or without associated parameters.
Example:
put ADBCallRemote("devices") into ListOfDevices -- Stores the output of the adb devices command in a variable.
Example:
put ADBCallRemote("shell input keyevent 82") -- Sends keyevent 82 to the device.
Example:
put the second word of the connectionInfo's serverID into Device -- Stores the adb serial number into a variable
delete "(" from Device -- Deletes the parentheses from the serial number so it can be used with the adbcall() function
delete ")" from Device
put ADBCallRemote (merge ("-s [[Device]] logcat -b events")) -- Uses the merge function to substitute the serial number into the adb command string
The ADBCall
function, an equivalent of the ADBCallRemote
Function, is deprecated as of Eggplant Functional 20.2.
Copy File
Command
This command is not supported by Sauce Labs.
Behavior: This command lets you copy a file either from the local machine to the SUT or from the SUT to the local machine. Use the prefix SUT:
before the path to indicate the SUT. Note that you can't use this command to copy a file from one location on the SUT to a different location on the SUT or to a different SUT. Copy File
works only with single files, not with folders.
In iOS Gateway, this command copies files to the Gateway, not to the device.
Parameters: A source file path and a destination file path.
Example:
copy file "/local/path/to/file" to "SUT:/remote/path/to/file" // Sends a file to the SUT
Example:
copy file "SUT:/remote/requested/file" to "/local/path/to/receive/file" // Retrieves a file from the SUT
DoubleTap
Command
Behavior: This command executes a double tap at either the current location or the location specified by the parameter. This command is equivalent to a DoubleClick command, catered to mobile devices. Generally on mobile devices, a double-tap action causes the app to zoom.
Example:
DoubleTap the remotescreensize/2-- Sends a doubletap command to the center of the screen
Example:
WaitFor 5, "FullsizeMap"
DoubleTap "BuildingIcon" -- Sends a doubletap command to the location of an image named "BuildingIcon"
WaitFor 5, "ZoomedMap"
Parameters: Optional set of coordinates, an image, or text (OCR).
Behavior: This command executes a double tap at either the current location or the location specified by the parameter. This command is equivalent to a DoubleClick command, but catered to mobile devices. Generally on mobile devices, a double-tap action causes the app to zoom.
The timing between tap events in a DoubleTap
command is controlled by the MouseDoubleClickDelay
property. Greatly lengthening the MouseDoubleClickDelay
causes the DoubleTap
to behave like two separate taps:
set the mousedoubleclickdelay to 1 -- Sets the delay between the tap events to 1 second
doubletap "MapMarker" -- Taps an image named "MapMarker" once, waits 1 second, and then taps the "MapMarker" image again
ExecuteRemoteCommand
Command and Function
Behavior: The ExecuteRemoteCommand
command and function are for running commands on SUTs that are mobile devices. You can choose to either return data or not. The command is either synchronous (waits for a response) or asynchronous (does not wait). The way in which it runs commands differs with the mobile operating systems as follows:
- On Android,
ExecuteRemoteCommand
runs as a shell command on the actual phone. - On iOS,
ExecuteRemoteCommand
runs the command as JavaScript, making calls to the Apple UIAutomation API.
Parameters: A command you want to run on a mobile device SUT.
Example:
ExecuteRemoteCommand("mkdir /data/local/tmp/TestDir") -- Creates a directory on the device using shell command syntax on Android
Example:
put ExecuteRemoteCommand ("ls /data/local/tmp/; echo hello", waitfor: 20) -- Passes multiple commands by separating them with semi-colons, and returns the results of the commands
InstallApp
Command
This command is not supported by Sauce Labs.
Behavior: This command installs an app to the mobile device. You specify the app to install with the applicationPath
parameter. Optionally, the command instructs iOS Gateway to developer sign the app before installing it if you include the provisionPath
and certificateName
properties. Applications to be installed can be specified with local paths if they are on the machine on which you are running Eggplant Functional; you can also install apps that are already on the machine where you're running iOS Gateway by using the SUT:
prefix on the path. This command waits until it receives a completed message from the server before proceeding.
Your signing certificate for the certificateName
property must be installed on the iOS Gateway machine before using it with InstallApp
.
Parameters: The applicationPath
is always required. For iOS, optional fields are provisionPath
and certificateName
if you want to code sign the app for development use (also called developer sign
).
Example:
installApp "/Path/to/App/AppName.ipa"
Example:
installApp {applicationPath:"/Path/to/App/AppName.apk"}
Example:
installApp {applicationPath:"/Path/to/App/AppName.ipa", provisionPath:"sut:/Path/to/Provisioning/Profile/YourProvisioningProfile.mobileprovision", certificateName:"your iPhone Developer certificate name"}
KillApp
Command
This command is not supported by Sauce Labs.
Behavior: The KillApp
command terminates the specified app.
Parameters: The name of the app you want to terminate:
-
On iOS, the app name is the name or bundle ID of the app.
-
On Android, the app name is the
package name
.
Example:
KillApp "Podcasts" -- Kills the Podcasts app on iOS 9 and 10
Example:
KillApp "com.apple.camera" -- Kills the Camera app on iOS 9 and 10
Example:
KillApp "com.google.android.apps.maps" -- Kills the Maps app on Android
-
To find the app package name on an Android device, you can use the Package Manager
pm list packages
command with theExecuteRemoteCommand
command as follows:put ExecuteRemoteCommand("pm list packages", WaitFor:10)
-
On iOS 8, certain apps can't be killed using this command.
-
For more information about using this command on iOS, see Killing Apps on the Solving Common Issues in iOS Testing page.
LaunchApp
Command
These commands are not supported by Sauce Labs.
Behavior: This command launches an app to a mobile device.
Parameters: The name of the app you want to launch:
- On iOS, the app name is the name or bundle ID of the app.
- On Android, the app name is the
package name
.
Example:
LaunchApp "Springboard"
Example:
LaunchApp "com.apple.camera"
Example:
LaunchApp "com.google.android.apps.maps"
To find the app package name on an Android device, you can use the Package Manager pm list packages
command with the ExecuteRemoteCommand
command as follows:
put ExecuteRemoteCommand("pm list packages", WaitFor:10)
PinchIn
Command
This command is not supported by Sauce Labs.
Behavior: The PinchIn
command acts like a two-point pinch on a screen; the effect of pinching in is to zoom out (i.e., the screen image effectively gets smaller). For the PinchIn
command, the At
point is static or "fixed", and the From
point moves toward the At
point. If no parameters are included, the pinchIn
occurs at screen center with a duration of 2 seconds and pinch amount of 4.5%.
Not all screen views or apps support zoom in or out behavior. For instance, using a pinch command while a device is on the Home screen has no effect.
Because distances are expressed in pixels, the behavior of the distance property is inconsistent across devices with varying resolutions. If using the distance property on various devices, set the distance to be relative to the actual screen size. For example:
PinchIn {Distance:the width of the RemoteScreenSize*0.25} -- Sets the distance to one quarter of the width of the screen
Parameters: Optional At
point, expressed as a set of coordinates, an image, or text (OCR); optional From
point, expressed as a set of coordinates, an image, or text (OCR); optional Duration
to express the time the zoom takes to execute (default is 2 seconds); optional Distance
, expressed in pixels, which would be used instead of a From
parameter (if neither Distance
nor From
is specified, the default distance is 4.5% of the shortest screen dimension).
Example:
PinchIn {At:"UNITEDSTATES_LEFT", From:"UNITEDSTATES_RIGHT"} -- Moves the From: finger in the pinch only and both fingers end together
Example:
PinchIn {distance:500} -- Executes a pinchIn across the specified distance, in pixels. Distances are relative to the At: point, which is the center of the screen by default.
Example:
PinchIn {At:RemoteScreenSize()/3, Duration: 5.0} -- Executes a pinchIn starting 1/3 from the left side of the screen with a duration of 5 seconds.
PinchOut
Command
This command is not supported by Sauce Labs.
Behavior: The PinchIn
command acts like a two-point pinch on a screen; the effect of pinching out is to zoom in (i.e., the screen image effectively gets bigger). For the PinchOut
command, the At point is static or "fixed"; the To point moves away from At point. If no parameters are included, the pinchout occurs at screen center with a duration of 2 seconds and a pinch amount of 20%.
Not all screen views or apps support zoom in or out behavior. For instance, using a pinch command while a device is on the Home screen has no effect.
Parameters: Optional At
point, expressed as a set of coordinates or with an image (default is the screen center); optional To
point, expressed as a set of coordinates or with an image; optional Duration
to express the time the zoom takes to execute (default is 2 seconds); optional Distance
, expressed in pixels, which would be used instead of a To
parameter. If neither Distance
nor To
is specified, the default distance is 25% of the shortest screen dimension.
Example:
PinchOut "CityLabel"