Mobile Control and Touch Events

Eggplant Functional provides many commands and functions specifically for when you use mobile devices as systems under test (SUTs).

Note: These features are available with Eggplant Functional 14.0 and later.

ADBCall() Function, ADBCallRemote() Function

Note: This function is for Android devices only.

Example:

put ADBCall("devices") into ListOfDevices //Stores the output of the adb devices command in a variable.

Example:

put ADBCall("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 adbcall (merge ("-s [[Device]] logcat -b events")) // Uses the merge function to substitute the serial number into the adb command string

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.

Behavior: These functions execute ADB calls to available Android devices and return any output received from the ADB command. ADBCallRemote() requires a connection through Android Gateway, and can work with an Android device connected remotely to the Eggplant machine.

Copy File Command

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

Parameters: A source file path and a destination file path.

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.

Note: In iOS Gateway, this command copies files to the Gateway, not to the device.

DoubleTap Command

Example:

DoubleTap the remotescreensize/2 //Sends a doubletap command at the center of the screen.

Example:

WaitFor 5, "FullsizeMap"

DoubleTap "BuildingIcon" //Sends a doubletap command at the location of the BuildingIcon image

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, catered to mobile devices. Generally on mobile devices, a double-tap action causes the app to zoom.

Behavior: 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:

Example:

set the mousedoubleclickdelay to 1 //Sets the delay between the tap events to 1 second

doubletap "MapMarker" //Taps the MapMarker image once, waits 1 second, and taps the MapMarker image again

ExecuteRemoteCommand() Command and Function

Example:

ExecuteRemoteCommand("mkdir /data/local/tmp/TestDir") //Creates a directory on the device using shell command syntax on Android

Example:

ExecuteRemoteCommand("UIATarget.localTarget().systemName()") //Gets the system name of the device with the active connection on iOS 7 and 8 only.

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.

Parameters: A command you want to run on a mobile device SUT.

Behavior: The ExecuteRemoteCommand() command and function is for running commands on SUTs that are mobile devices. You can use it to 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.
Note: Using the ExecuteRemoteCommand() command requires iOS Gateway 2.6 and later or the embedded Android VNC server in Eggplant Functional 15.21 and later. ExecuteRemoteCommand() works on iOS 7 and 8 only.

InstallApp Command

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

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

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.

Note: Your signing certificate for the certificateName property must be installed on the iOS Gateway machine before using it with InstallApp.

KillApp Command

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

Parameters: The name of the app you want to terminate:

  • On iOS 7 and iOS 8, the app name is the name, or bundle ID, of an app that has been signed by using a development provisioning profile.
  • On iOS 9 and later, the app name is the name of the app or the bundle ID (i.e., com.apple.camera).
  • On Android, the app name is the package name.

Behavior: The KillApp command terminates the specified app.

Notes:

  • Using the KillApp command requires iOS Gateway 2.6 and later, Android Gateway, or the embedded Android VNC server in Eggplant Functional 15.21 and later.
  • 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)

  • 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

Example:

LaunchApp "Springboard"

Example:

LaunchApp "com.apple.camera"

Example:

LaunchApp "com.google.android.apps.maps"

Parameters: The name of the app you want to launch:

  • On iOS 7 and 8, the app name is the name of a developer-signed app (or Springboard), or the bundle ID. You can also specify the name of the iOS device, followed by a space, a colon, a space, and the name of the developer-signed app on the device.
  • On iOS 9 and later, the app name is the name or bundle ID of the app.
  • On Android, the app name is the package name.

Behavior: This command launches an app to a mobile device. For an iOS 7 or 8 device connected through the iOS Gateway, this command is limited to developer-signed apps or Springboard.

Note: 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)

PinchIn Command

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.

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

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"; 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%.

Note: 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.
Tip: 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:

Example:

PinchIn(Distance:the width of the RemoteScreenSize * 0.25)//Sets the distance to one quarter of the width of the screen.

PinchOut Command

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.

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.

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%.

Note: 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.

Press Command

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"

Parameters: Optional set of coordinates or an image.

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.

Tip:When using the Press command, be sure to always pair it with a Release command.

PressBackButton Command

Note: This function is for Android devices only.

Example:

PressBackButton

Parameters: None.

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.

PressHomeButton Command

Example:

PressHomeButton

Parameters: None.

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.

Note: 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

Example:

Reboot

Parameters: None.

Behavior: The Reboot command is for mobile devices. This command restarts the mobile device with the active connection.

Note: Using the Reboot command requires iOS Gateway 2.6 and later, Android Gateway, or the embedded Android VNC server in Eggplant Functional 15.21 and later.

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 as shown in the example below:

Example:

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

Example:

Release "AppIcon"

Parameters: Optional set of coordinates, an image, or text (OCR).

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.

RotateLeft, RotateRight Commands

Example:

RotateLeft(WaitFor:10.0)

Parameters: Optional WaitFor time to allow the rotation to occur.

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.

SetDeviceLocation

Example:

SetDeviceLocation(latitude:1.1, longitude:2.2)

Example:

SetDeviceLocation(40.021824,-105.2473129)

Parameters: The latitude and longitude of the location you want to set on the device.

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.

SetDeviceOrientation Command

Example:

SetDeviceOrientation LandscapeRight

Parameters: The device orientation that you want to set (LandscapeLeft, LandscapeRight, Portrait, PortraitUpsideDown) and an optional WaitFor time.

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.

Related:

  • GetDeviceOrientation: Use this function to return information about the device's current orientatin.

SwipeDown, SwipeLeft, SwipeRight, SwipeUp Commands

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

Parameters: Optional set of coordinates, image, or text (OCR) indicating the start point for the swipe.

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.

Tip: Use the SwipeSpeed global property to adjust the number of pixels dragged during the swipe action.
Tip: 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.

Tap Command

Example:

Tap "Safari_Icon"

Parameters: Optional set of coordinates or an image.

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.

Behavior: 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:

Example:

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

Example:

UninstallApp "MyApp" //Uninstalls an app on iOS

Example:

UninstallApp "com.google.android.apps.maps" //Uninstalls an Android 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.

Behavior: The UninstallApp command removes the specified app.

Note: 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)

 

This topic was last updated on April 30, 2019, at 01:48:35 PM.

Eggplant icon Eggplant.io | Documentation Home | User Forums | Support | Copyright © 2019 Eggplant