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. It is not supported by SauceLabs.
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
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.
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,
ExecuteRemoteCommandruns as a shell command on the actual phone. - On iOS,
ExecuteRemoteCommandruns 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
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
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 packagescommand with theExecuteRemoteCommandcommand 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
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 partially supported on Android and iOS through the Eggplant Functional Mobile Connection type. It is not supported by SauceLabs.
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 partially supported on Android and iOS through the Eggplant Functional Mobile Connection type. It is not supported by SauceLabs.
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"
Example:
PinchOut {At:"UNITEDSTATES_LEFT", To:"UNITEDSTATES_RIGHT"} -- Moves the To: finger in the pinch only and both fingers start together.
Example:
PinchOut {Distance:300} -- Executes a pinchout across the specified distance, in pixels. Distances are relative to the At: point, which is the center of the screen by default.
Press Command
Behavior: This command executes a tap and hold at either the current location or the point specified by the parameter. This command is equivalent to a MouseButtonDown command, catered to mobile devices.
When using the Press command, be sure to always pair it with a Release command.
Parameters: Optional set of coordinates or an image.
Example:
Press "AppIcon"
Example:
setremoteclipboard "12283" -- Sends the string "12283" to the clipboard of the SUT
Press "AddressField" -- Presses on the image AddressField
wait 2 -- Holds down the press for 2 seconds
Release -- Releases the press action
Tap "PasteDialog"
PressBackButton Command
This function is for Android devices only.
Behavior: Pushes the Back button on Android devices running Android 4.0.4 and later. For older Android devices, see TypeText Keywords for Mobile Control.
Parameters: None.
Example:
PressBackButton
PressHomeButton Command
Behavior: Pushes the Home button on iOS devices, as well as Android devices running Android 4.0.4 and later. For older Android devices, see TypeText Keywords for Mobile Control.
Parameters: None.
Example:
PressHomeButton
To double-press the Home button in iOS 9 and later, use TypeText:
TypeText HomeButton,HomeButton
This command must be entered as one line. If you use two separate lines, the device registers two separate home button presses, not a double-press.
Reboot Command
This command is not supported by Sauce Labs.
Behavior: The Reboot command is for mobile devices. This command restarts the mobile device with the active connection.
When you use the Reboot command in your script, we recommend sending a disconnect command immediately after it, and then reconnecting. When you reconnect, allow time for the device to come up. For example, you can include the connect command in a repeat command that tries the connection until it succeeds.
Parameters: None.
Example:
Reboot
Example:
This example shows how to use the connect command in a repeat loop in order to attempt to connect until the connection is made.
Connect "AndroidSUT", port:5900
Reboot
Disconnect
Repeat until the connectioninfo.connected is true
try to connect "AndroidSUT", port:5900
Log the counter
End repeat
Release Command
Behavior: This command releases a Press command at either the current location or the location specified. It is the equivalent of a MouseButtonUp command, catered to mobile devices.
Parameters: Optional set of coordinates, an image, or text (OCR).
Example:
Release "AppIcon"
RotateLeft, RotateRight Commands
This command is partially supported on Android and iOS through the Eggplant Functional Mobile Connection type. It is not supported by SauceLabs.
Behavior: The RotateLeft command rotates the mobile device screen one quarter turn (90 degrees) clockwise from the current device orientation, and the RotateRight command rotates the screen (90 degrees) counter-clockwise from the current orientation.
Parameters: Optional WaitFor time to allow the rotation to occur.
Example:
RotateLeft {WaitFor:10.0}
SetDeviceLocation Command
This command is partially supported on Android and iOS through the Eggplant Functional Mobile Connection type. It is not supported by SauceLabs.
Behavior: This command allows you to override the device's GPS and set a desired location on an Android device or an iOS device. On Android devices, you must change developer settings for this command to work. On iOS devices, you must enable location services for this command to work.
Parameters: The latitude and longitude of the location you want to set on the device.
Example:
SetDeviceLocation {latitude:1.1, longitude:2.2}
Example:
SetDeviceLocation [40.021824,-105.2473129]
SetDeviceOrientation Command
This command is not supported by Sauce Labs.
Behavior: This command changes the device orientation to what you specify with the parameter. It waits until the new orientation is achieved before proceeding; however, you can include a WaitFor delay as well to control timing issues. If the SetDeviceOrientation command times out, it will throw an exception.
Parameters: The device orientation that you want to set (LandscapeLeft, LandscapeRight, Portrait, PortraitUpsideDown) and an optional WaitFor time.
Example:
SetDeviceOrientation LandscapeRight
Related:
GetDeviceOrientation: Use this function to return information about the device's current orientatin.
SwipeDown, SwipeLeft, SwipeRight, SwipeUp Commands
Behavior: This command executes a swipe motion. The swipe starts at the specified location, image, or text (OCR), or at an automatically determined position near the edge of the screen. SwipeDown and SwipeUp automatically start at a central location near the bottom and top of the screen, respectively, and swipe toward the opposite end of the screen. SwipeLeft and SwipeRight automatically start at a central location near the right and left of the screen, respectively, and swipe toward the opposite side of the screen. This motion imitates a hand-executed swipe on a mobile device by moving in an arced fashion.
Use the SwipeSpeed global property to adjust the number of pixels dragged during the swipe action.
If you need to specify a stop location in addition to a start location for a swipe action, use the DragandDrop or Drag and Drop commands instead.
Parameters: Optional set of coordinates, image, or text (OCR) indicating the start point for the swipe.
Example:
SwipeLeft
Example:
SwipeDown "NotificationBar"
Example:
Set the SwipeSpeed to 80 //Sets the SwipeSpeed to drag 80 pixels during the swipe
SwipeUp the remoteScreenSize times .9 //Starts the swipe 90% from the top and 90% from the left of the screen.
Example:
ScrollUntilFound "ChromeIcon", "left" //Calls a handler "ScrollUntilFound", passing two parameters representing an image and a direction.
on ScrollUntilFound myImage, Direction //Declares a command handler with 2 parameters.
repeat until imagefound (imagename:myImage,waitFor:0) //Repeats until a particular image is found, allowing only 1 scan for the image for each iteration.
if the repeatindex = 5 then throw "Image not found", "Image not found while scrolling"&&Direction&period //Throws an exception if the repeat loop iterates 5 times
Do "Swipe" & Direction //Uses the Do command to combine a string and variable into a command
wait 2 //Waits two seconds to allow the screen to settle after the swipe
end repeat
end ScrollUntilFound
Tap Command
Behavior: This command executes a tap at either the current location or the location specified by the parameter. This command is equivalent to a Click command, catered to mobile devices.
Parameters: Optional set of coordinates or an image.
Example:
Tap "Safari_Icon"
The timing between tap down and tap up events in a Tap command is controlled by the MouseClickDelay global property. Greatly lengthening the MouseClickDelay causes the Tap to behave like a Press and Release:
set the mouseclickdelay to 2 //Sets the delay between the tap down and tap up events to 2 seconds
tap "SearchField" //Presses and releases on the SearchField image
UninstallApp Command
Behavior: The UninstallApp command removes the specified app.
Parameters: The name of the app you want to uninstall:
- On iOS, the app name is the name of an app.
- On Android, the app name is the
package name.
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:
Example:
put ExecuteRemoteCommand("pm list packages",WaitFor:10)
Example:
UninstallApp "MyApp" //Uninstalls an app on iOS
Example:
UninstallApp "com.google.android.apps.maps" //Uninstalls an Android app