Mobile
3.1.5 Mobile
The Mobile command is supported since 7.1. It delivers mobile specific features on the Android Over ADB and iOS Over Xcode connections.
The command replaces the legacy Android and iOS extensions (plugins) which were being delivered as separate products. The goal is to provide a common language for automation of mobile devices and to avoid the overhead of the plugin installation. Due to the different nature of the iOS and Android operating systems not all the Mobile command functionality is supported the same way by both connections. For example, downloading and uploading of files is supported only on Android while keyboard map operations are specific to iOS. If you intend to write a single script targeting both platforms please pay attention to the feature compatibility notes in this document.
A complete list of supported operations follows:
| Operation | Description | iOS Over Xcode | Android Over ADB | Legacy iOS/Android Plugins |
|---|---|---|---|---|
| Mobile alert | Alert handling | supported | unsupported | yes/no |
| Mobile app | Get current app ID | supported | supported | yes/no |
| Mobile find | Operate UI elements | supported | supported | no/no |
| Mobile install | Install app on device | unsupported | supported | no/yes |
| Mobile keyboard | Keyboard operations | partly supported (get, dismiss, load, remap) | partly supported (get, show, dismiss) | partly (load, remap)/no |
| Mobile kill | Kill app on device | supported | supported | yes/yes |
| Mobile orientation | Screen orientation handling | supported | supported | yes/no |
| Mobile pull | Download file from device | unsupported | supported | no/yes |
| Mobile push | Upload file to device | unsupported | supported | no/yes |
| Mobile shell | Execute shell command | unsupported | supported | no/yes |
| Mobile start | Start app on device | supported | supported | yes/yes |
| Mobile uninstall | Uninstall app from device | unsupported | supported | no/yes |
The command delivers enhanced functionality of the legacy plugins plus a new feature called Mobile find. It allows to identify a UI component on the device screen by its attributes (text, type etc.s), retrieve its properties and optionally apply an action to it (click it). It is based on the ability of iOS and Android to retrieve the tree of UI components in form of an XML document. It is fairly similar to how the Browser find command identifies components in a Selenium driven web browser.
- The advantage of Mobile find is reliability. Unlike image search or OCR this method is more accurate and reliable to identify standard UI components on the screen.
- The disadvantages are speed (retrieval of the XML hierarchy is slow) and failure to identify any custom content such as graphical output (games) or mobile web browser content.
The algorithm used to identify components is also exposed to image comparison commands such as Compareto and Waitfor as a method called "mobile".The "passrate" parameter is not used and ignored by this method.The "cmparea" one is also ignored though it may change in a future release.
SYNOPSIS
Mobile alert action=get
- Test out if there's an alert window on the mobile device screen.
Mobile alert action=dismiss [button=<button>] [text=<text_to_type>] [accept=<true|false>]
- Dismiss the alert. If there's no alert do nothing.
OPTIONS
action=<get|dimiss>
- The alert action name. The currently supported values are:
- "get" - Test out if there's an alert displayed on the mobile device. If there's an alert the method populates the _MOBILE_ALERT_TEXT, _MOBILE_ALERT_BUTTON_COUNT and _MOBILE_ALERT_BUTTON[n] variables with the alert text and number of buttons and their labels.
- "dismiss" - Dismiss the alert. You may optionally specify how to close the alert using the button, text and accept parameters.
button=<button>
- Name of the button to dismiss the alert with (optional). You may use one of the button names stored to the _MOBILE_ALERT_BUTTON[n] variables by a previous call of "Mobile alert action=get". If the button is not specified the command will choose one.
text=<text_to_type>
- The text to be typed into the alert's text field before dismissing it (optional). If the alert does not contain a text field the parameter will be ignored.
accept=<true|false>
- If the button is not specified use this parameter to indicate whether you wish to accept or cancel the alert. This is taken into account only if the alert contains two or more buttons, for example "OK" and "Cancel". If the parameter is omitted the command will choose how to close the alert.
RETURNS:
The "get" action returns 0 if there's an alert and 1 if there is none. The "dismiss" action returns 0 on successful alert dismissal or 1 otherwise.
Mobile app
Retrieve ID of the active (currently displayed) application into the _MOBILE_ACTIVE_ID variable.
RETURNS:
The command always returns 0.
Mobile find [timeout=<time_interval>] [action=<action>] [number=<element_number>] [continue=<true|false>] [<attributes>]
- Find a UI element on the device screen by the specified attributes and optionally click it. Attributes of the element(s) are stored to variables with the _MOBIlE_FIND prefix. When click is required use the continue parameter to determine whether to crash the script or allow it to continue when the element is not found.
The element search algorithm is also exposed to image comparison commands such as CompareTo and WaitFor. Look for the method called "mobile".
OPTIONS
timeout=<time_value>
- Optional time to keep looking for the element. It must be a valid time value.
- If no timeout is specified the command looks for the element just once.
- If the timeout is specified and is greater than zero the command will keep trying to find the element until the time expires or the element is found.
action=<action>
- Optional action to apply to the resulting element. If the search produces multiple elements you may use the number parameter to select the target element. Supported actions are:
- "click" - Click the element. It applies only to clickable elements such as links, buttons etc.
number=<element_number>
- The ordinal number of the element to target with the action specified by action. The default value is 1 (use the first element). If the number of elements is lower than number then the command throws an error and terminates the script.
continue=<true|false>
- Specifies how to handle the failure. If the element is not found and this parameter is not specified or is false the command terminates the script. If the parameter is true the script is allowed to continue and the command returns a non-zero exit code.
<attributes>
-The list of attributes (search criteria) in the form of name=value pairs such as:
- "xpath=<xpath_expression>" - Perform search by an XPath expression. When this option is used no other attribute may be specified.
- "type=<button|input|text>" - The element type, one of "button" (a standard button of any recognized type), "input" (an editable text component) or "text" (a component displaying a static text).
- "text=<text>" - The exact element text.
- "parttext=<partial_text>" - Find element(s) whose text contains the specified partial text.Besides the above parameters the command accepts any UI hierarchy tree attributes and their values. Such a search will be however iOS or Android specific. For example, to identify a currently focused on Android use focused=true.
RETURNS:
When called without the action parameter the command returns 0 if at least one element is found or 1 otherwise. The number of identified elements is stored to the _MOBILE_FIND_COUNT variable and attributes of individual elements are exposed as numbered variables with the
MOBILE FIND_ prefix.
When the action parameter is present and the action is successfully applied to an element the command returns 0. The failure behavior is subject to the continue parameter:
- If continue is not specified or is false the command throws an error and terminates the script.
- If continue is true the script is allowed to continue executing and the command returns either 1 (no elements found) or 2 (not enough elements found to match the element by number).
Mobile install [file=<app_file>] [reinstall=<true|false>]
* Red colour indicates obligatory parameters
- Install an application from the specified local file on the device. When successful the command populates the _MOBILE_INSTALLED_ID variable with the application ID which may be then used to start, kill or uninstall the app.
OPTIONS
file=<app_file>
- Path to the Android application file (.apk).
reinstall=<true|false>
- The value of true will force reinstallation if the app is already present on the device.
RETURNS:
The command returns 0 on successful completion or throws an error and terminates the script otherwise.
Mobile keyboard action=get
- Populate the _MOBILE_KEYBOARD_VISIBLE variable with true/false to indicate if the soft keyboard is visible. The command returns 0 or terminates the script on a failure to determine the keyboard status (unsupported OS, ...).
Mobile keyboard action=show
- Android only: Make an attempt to display the soft keyboard on the device and indicate the result through the exit code. Note that this functionality often fails because it is subject to whether an editable UI component is currently in focus and other conditions. Make sure to test the return code for the result. The command may throw an error and terminate the script on a failure to determine the keyboard status (unsupported OS, ...).
Mobile keyboard action=dismiss [keys=<semicolon_separated_list>]
- Make an attempt to dismiss the currently showing soft keyboard on the device and indicate the result through the exit code. Note that the keys parameter is required only on iOS and is not required and ignored on Android. The command may throw an error and terminate the script on a failure to determine the keyboard status (unsupported OS, ...).
Mobile keyboard action=load [file=<map_file>]
- iOS only: Load a stored keyboard map. If the file is not available or is in a wrong format the command throws an error and terminates the script.
Mobile keyboard action=remap
- iOS only: Perform immediate remapping of the currently displayed soft keyboard. If the soft keyboard is not displayed or an unexpected error is experienced the command throws an error and terminates the script.
* Red colour indicates obligatory parameters
OPTIONS
action=<get|show|dismiss|load|remap>
- The action name, one of "get", "show", "dismiss", "load" or "remap".
file=<map_file>
- Path to the keyboard map file (.keymap).
keys=<semicolon_separated_keys>
- The list of semicolon separated key names to tap to close the keyboard. This parameter is required only on iOS and is ignored on Android.
RETURNS:
See the individual action descriptions for the returned exit codes and error throwing.
Mobile kill [id=<application_id>] [force=<true|false>] [timeout=<time_interval>] [log=<true|false>]
- Kill the specified application or send it to the background eventually.
OPTIONS
id=<application_id>
- The application ID. On iOS it is the application bundle name, for example "com.apple.mobilesafari" for the Safari browser. On Android it is either the application package alone (the "kill" and "uninstall" actions), such as "com.android.chrome" for Chrome app or the package followed by a slash and the activity (the "start" action), for example "com.android.chrome/com.google.android.apps.chrome.Main". If the application ID is not specified the command kills the application installed recently by a call of "Mobile install" (Android only) or provided by a call of "Mobile app" (the ID is retrieved from the _MOBILE_ACTIVE_ID variable). To kill the currently displayed app use a sequence of "Mobile app" and "Mobile kill" commands. If no application ID can be resolved the command throws an error and terminates the script.
force=<true|false>
- The value of true tells the command to try harder to kill the app. The internal implementation is subject to the target OS and the flag may be even ignored. The default value is true.
timeout=<time_value>
- Optional time to wait for the shell command to finish. It must be a valid time value. It is being used only by Android where app are being killed through a shell command. The parameter is ignored by iOS.
log=<true|false>
- The value of true will log the operation output to the execution log for debugging purposes. The default value is false.
RETURNS:
The command returns 0.
Mobile orientation action=get
- Populate the _MOBILE_SCREEN_ORIENTATION_NAME and _MOBILE_SCREEN_ORIENTATION variables with the current screen orientation name and code. The names are "Portrait" (code 0), "LandscapeLeft" (1) , "UpsideDown" (2) and "LandscapeRight" (3).
Mobile orientation action=set [set=<orientation>]
* Red colour indicates obligatory parameters
- Set the screen orientation and populate the same variables as the "get" action.
OPTIONS
action=<get|set>
- The action name, one of "get" or "set".
set=<orientation>
- The target orientation identified either by the name or its numeric code. Acceptable values are "Portrait" (code 0), "LandscapeLeft" (1) , "UpsideDown" (2) and "LandscapeRight" (3). Android also supports "Auto" (code 4) to reset the screen orientation to the gyroscope indicated one.
RETURNS:
The command returns 0.
Mobile pull [remote=<remote_file>] [local=<local_file>]
* Red colour indicates obligatory parameters
- Android only: Pull (download) a file from the device to the local file system.
OPTIONS
remote=<remote_file>
- The file on the device.
local=<local_file>
- The file in the local file system.
RETURNS:
The command returns 0 on success or throws an error and terminates the script on a failure.
Mobile push [local=<local_file>] [remote=<remote_file>]
* Red colour indicates obligatory parameters
- Android only: Push (upload) a file to the device.
OPTIONS
local=<local_file>
- The file in the local file system.
remote=<remote_file>
- The file on the device.
RETURNS:
The command returns 0 on success or throws an error and terminates the script on a failure.
Mobile shell [command=<command>] [remote=<remote_file>] [timeout=<time_interval>] [log=<true|false>]
* Red colour indicates obligatory parameters
- Android only: Execute a shell command on the device. The command output is then stored to the _MOBILE_OUTPUT variable.
OPTIONS
command=<command>
- The shell command to be executed.
timeout=<time_value>
- Optional time to wait for the shell command to finish. It must be a valid time value.
log=<true|false>
- The value of true will log the operation output to the execution log for debugging purposes. The default value is false.
RETURNS:
The command returns 0 on success or throws an error and terminates the script on a failure.
Mobile start [id=<application_id>] [timeout=<time_interval>] [log=<true|false>]
- Start an application on the device. Unless the timeout is specified the app start command is kicked off but no efforts are made to verify whether the app displays correctly. The command just may indicate through the exit code whether the start process was performed properly and populate the _MOBILE_OUTPUT variable with an error output. To make sure that the app started and displayed on the screen use the timeout parameter.
OPTIONS
id=<application_id>
- The application ID. On iOS it is the application bundle name, for example "com.apple.mobilesafari" for the Safari browser. On Android it is must be the package followed by a slash and the activity, for example "com.android.chrome/com.google.android.apps.chrome.Main". If the application ID is not specified on Android the command starts the application installed recently by a call of "Mobile install" (the ID is retrieved from the _MOBILE_INSTALLED_ID variable). If no application ID can be resolved the command throws an error and terminates the script.
timeout=<time_value>
- Optional time to wait for the shell command to finish. It must be a valid time value.
log=<true|false>
- The value of true will log the operation output to the execution log for debugging purposes. The default value is false.
RETURNS:
If the timeout parameter is not specified or is set to 0 the command just kicks off the application and returns 0. The command may return 1 or another code for known error states, for example when the app is not installed.
When a timeout is set the command verifies that the app is started and displaying on the screen by testing the active app against the argument id within the specified time period. If the app fails to show it throws an error and terminates the script.
Mobile uninstall [id=<application_id>]
- Android only: Uninstall an application from the device. If the operation fails it populates the _MOBILE_OUTPUT variable with the reason.
OPTIONS
id=<application_id>
- The application ID. It is either the Android application package alone such as "com.android.chrome" for Chrome app or the package followed by a slash and the activity (the "start" action), for example "com.android.chrome/com.google.android.apps.chrome.Main". If the application ID is not specified the command uninstalls the application installed recently by a call of "Mobile install" (the ID is retrieved from the _MOBILE_INSTALLED_ID variable). To uninstall the currently displayed app use a sequence of "Mobile app" and "Mobile uninstall id="{_MOBILE_ACTIVE_ID}" commands. If no application ID can be resolved the command throws an error and terminates the script.
RETURNS:
The command returns 0 on success or 1 on failure. It throws an error and terminate the script if the app ID can not be resolved or in case of an unexpected I/O error.