Mobile Control and Touch Events

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

ADBCall Function, ADBCallRemote Function

Note: This function is for Android devices only.

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.

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

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.

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

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

setthe mousedoubleclickdelayto1-- 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

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

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"

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

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.

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 of the app or the bundle ID (i.e., com.apple.camera).
  • 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

Notes:

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

    putExecuteRemoteCommand("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"

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:

put ExecuteRemoteCommand("pm list packages", WaitFor:10)

PinchIn Command

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

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:

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

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.

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.

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

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

Note: To double-press the Home button in iOS 9 and later, use TypeText:
TypeTextHomeButton, 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

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

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

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

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.

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.

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"

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

putExecuteRemoteCommand("pm list packages", WaitFor:10)

Example:

UninstallApp "MyApp" //Uninstalls an app on iOS

Example:

UninstallApp "com.google.android.apps.maps" //Uninstalls an Android app

 

This topic was last updated on July 02, 2020, at 02:51:52 PM.

Eggplant icon Eggplantsoftware.com | Documentation Home | User Forums | Support | Copyright © 2020 Eggplant