Execute Mobile Command
Execute a native mobile command
Example Usage
- java
driver.executeScript("mobile: scroll", ImmutableMap.of("direction", "down"));
- python
self.driver.execute_script("mobile: scroll", {'direction': 'down'})
- Javascript
// webdriver.io example
var result = browser.execute('mobile: scroll', {direction: 'down'})
// wd example
await driver.execute('mobile: scroll', {direction: 'down'});
- ruby
# ruby_lib example
execute_script("mobile: scroll", { "direction" => "down"})
# ruby_lib_core example
@driver.execute_script("mobile: scroll", { "direction" => "down"})
Description
Execute a variety of native, mobile commands that aren’t associated with a specific endpoint
Syntax is execute("mobile: <commandName>", <JSON serializable argument>) (see Execute Script for more details on syntax).
List of available commands:
IOS
| Command | Description | Argument | Argument Example |
|---|---|---|---|
| mobile:viewportScreenshot | Like screenshot but only includes contents of viewport |
IOS (XCUITest Only)
| Command | Description | Argument | Argument Example |
|---|---|---|---|
| mobile:startPerfRecord | Starts performance profiling for the device under test | ||
| mobile:stopPerfRecord | Stops performance profiling for the device under test | ||
| mobile:startLogsBroadcast | Starts iOS system logs broadcast websocket on the same host and port where Appium server is running at /ws/session/:sessionId:/appium/device/syslog endpoint. |
||
| mobile:stopLogsBroadcast | Stops the iOS system logs broadcasting websocket server started by mobile:startLogsBroadcast
|
||
| mobile:swipe | refer to Automating Mobile Gestures For iOS With WebDriverAgent/XCTest Backend | ||
| mobile:scroll | refer to Automating Mobile Gestures For iOS With WebDriverAgent/XCTest Backend | ||
| mobile:pinch | refer to Automating Mobile Gestures For iOS With WebDriverAgent/XCTest Backend | ||
| mobile:doubleTap | refer to Automating Mobile Gestures For iOS With WebDriverAgent/XCTest Backend | ||
| mobile:touchAndHold | refer to Automating Mobile Gestures For iOS With WebDriverAgent/XCTest Backend | ||
| mobile:twoFingerTap | refer to Automating Mobile Gestures For iOS With WebDriverAgent/XCTest Backend | ||
| mobile:tapWithNumberOfTaps | refer to Automating Mobile Gestures For iOS With WebDriverAgent/XCTest Backend | ||
| mobile:tap | refer to Automating Mobile Gestures For iOS With WebDriverAgent/XCTest Backend | ||
| mobile:dragFromToForDuration | refer to Automating Mobile Gestures For iOS With WebDriverAgent/XCTest Backend | ||
| mobile:selectPickerWheelValue | refer to Automating Mobile Gestures For iOS With WebDriverAgent/XCTest Backend | ||
| mobile:alert | refer to Automating Mobile Gestures For iOS With WebDriverAgent/XCTest Backend | ||
| mobile:installApp | refer to XCUITest Mobile App Managemenet | ||
| mobile:removeApp | refer to XCUITest Mobile App Managemenet | ||
| mobile:isAppInstalled | refer to XCUITest Mobile App Managemenet | ||
| mobile:launchApp | refer to XCUITest Mobile App Managemenet | ||
| mobile:terminateApp | refer to XCUITest Mobile App Managemenet | ||
| mobile:activateApp | refer to XCUITest Mobile App Managemenet | ||
| mobile:queryAppState | refer to XCUITest Mobile App Managemenet | ||
| mobile:setPasteboard | refer to IOS Pasteboard Guide | ||
| mobile:getPasteboard | refer to IOS Pasteboard Guide | ||
| mobile:installCertificate | refer to IOS Pasteboard Guide | ||
| mobile:getContexts | Retrieve available contexts, along with the url and title associated with each webview (see get contexts). If waitForWebviewMs is provided, Appium will wait for available WebViews up to the number since Appium 1.17.0. |
{waitForWebviewMs} |
{waitForWebviewMs: 5000} |
| mobile:batteryInfo | Reads the battery information from the device under test | ||
| mobile:pressButton | Press a physical button. The available button options are: home , volumeup and volumedown . Real devices support all three buttons whereas simulator only supports home . | {name} |
{name: "home"} |
| mobile:enrollBiometric | Enroll (or unenroll) an iOS Simulator to use biometrics | {isEnabled} |
{isEnabled: true} |
| mobile:sendBiometricMatch | Send a matching or non-matching biometric input to an iOS Simulator. ‘type’ must be touchId or faceId . Match is a boolean indicating if it’s a matching or non-matching input |
{type, match} |
{type: "touchId", match: true} |
| mobile:isBiometricEnrolled | Check if an iOS Simulator is enrolled or not. Returns true if enrolled, false if not enrolled. |
||
| mobile:clearKeychains | Clear the keychains for an iOS Simulator | ||
| mobile:siriCommand | Sends a command to Siri | {text} |
{text: "What time is it?"} |
| mobile:source | This endpoint allows to retrieve the current native page source from WDA as a string (also being in a web context). Possible output formats are: xml (same output as for getPageSource command, the default value), json (the same tree structure as for the xml format, but represented as JSON) and description (native debugDescription output generated by XCTest). An optional excludedAttributes array allows to provide attributes names, which are going to be excluded from the resulting xml tree. This might significantly improve the performance of page source retrieval, especially if the visible attribute gets excluded. |
{format, excludedAttributes} |
{format: 'description'} {format: 'xml', excludedAttributes: ['visible']}
|
| mobile:activeAppInfo | Gets current active application’s information such as bundleId and process arguments | ||
| mobile:deviceInfo | Gets device information like locale and timezone. The timezone is TZ database format like America/New_York by default, fallback to Apple name like US/New_York
|
||
| mobile:rotateElement | Sends a rotation gesture with two touches to the given element. See rotate:withVelocity: for more details. | {element, rotation, velocity} |
{element: 2, rotation: π/2, velocity: 1.5} |
| mobile:deleteFile | Delete a file on the device under test. The remote path value should comply to Pushing/Pulling Files tutorial. | {remotePath} |
{remotePath: 'path/to/file'} |
| mobile:deleteFolder | Delete a folder on the device under test. The remote path value should comply to Pushing/Pulling Files tutorial. | {remotePath} |
{remotePath: '@io.appium.example:documents/path/to/folder'} |
| mobile:getPermission | Gets application permission state on a simulator. It requires https://github.com/wix/AppleSimulatorUtils | ||
| mobile:setPermission | Set a permission for the given bundleId via xcrun simctl privacy which is available since Xcode 11.4. key is ‘service’ in the list of xcrun simctl privacy . value is yes (grant), no (revoke) or unset (reset). It works on simulator. |
{bundleId, {key: value}} |
{bundleId: 'io.appium.example', {'location-always': 'yes', calendar: 'no'} |
| mobile:getAppearance | Get the device’s UI appearance style via xcrun simctl ui . It returns light , dark , unknown or unsupported (below iOS 12). |
||
| mobile:setAppearance | Set the device’s UI appearance style via xcrun simctl ui or Siri command. |
{style} |
{style: 'dark'} |
| mobile:getDeviceTime | Get time of the device under test. Moment.js | Docs is the full list of supported datetime format specifiers. Defaults to YYYY-MM-DDTHH:mm:ssZ which is ISO-8601. |
{format} |
{format: 'YYYY-MM'} |
| mobile:startAudioRecording | Start recording audio stream. Read Audio Capture From iOS Simulators and Real Devices for more details | ||
| mobile:stopAudioRecording | Stop and store the recording audio stream. Read Audio Capture From iOS Simulators and Real Devices for more details |
Android
| Command | Description | Argument | Argument Example |
|---|---|---|---|
| mobile:shell | Execute ADB shell commands (requires insecure feature adb_shell to be enabled) |
Read this page | {'command': 'echo', 'args': ['arg1', 'arg2']} |
| mobile:startLogsBroadcast | Starts Android logcat broadcast websocket on the same host and port where Appium is running at /ws/session/:sessionId:/appium/device/logcat endpoint |
||
| mobile:stopLogsBroadcast | Stops the logcat broadcasting websocket server started by mobile:startLogsBroadcast
|
||
| mobile:performEditorAction | Performs the given editor action on the focused input field. The following action names are supported: normal, unspecified, none, go, search, send, next, done, previous . |
{action} |
{action: "previous"} |
| mobile:getPermissions | Gets a list of permissions which are denied , granted or requested . |
{type, appPackage} |
{type: "granted", appPackage: "io.appium.android.apis"} |
| mobile:changePermissions | Grants or revokes permissions. | {action, appPackage, permissions} |
{action: "grant", appPackage: "io.appium.android.apis", permissions: "android.permission.READ_CONTACTS"} , {action: "revoke", appPackage: "io.appium.android.apis", permissions: ["android.permission.READ_CONTACTS", "android.permission.CAMERA"]}
|
| mobile:getNotifications | Get the list of items as JSON format in the status bar notifications. Please turn ‘Notification access’ on via Settings > App & notifications > Special app access (the actual path depends on the device model). Please read Appium Pro for more details. | ||
| mobile: listSms | Get the list of SMS messages as JSON format. | ||
| mobile:type | Send Unicode text to a focused element. | {text} |
{text: "happy testing"} |
| mobile:getDeviceTime | Get time of the device under test. Moment.js | Docs is the full list of supported datetime format. Defaults to YYYY-MM-DDTHH:mm:ssZ which is ISO-8601. |
{format} |
{format: 'YYYY-MM'} |
| mobile:deleteFile | Delete a file on the device under test. The remote path value should be the full path or a file inside an application bundle. | {remotePath} |
{remotePath: '@io.appium.example/path/in/bundle'} , {remotePath: '/tmp/data/file'}
|
| mobile:startService | Starts the given service by calling am start-service or am start-foreground-service under the hood since Appium 1.18.0. The intent argument is mandatory. user is the ID of the user the service should be started for (the current user ID is used by default). If foreground is set to true then the service will be started in foreground. |
{intent, user, foreground} |
{intent: 'my.app/my.activity', foreground: true} |
| mobile:stopService | Stops the given service by calling am stop-service under the hood since Appium 1.18.0. The intent argument is mandatory. user is the ID of the user the service should be stopped for (the current user ID is used by default). |
{intent, user} |
{intent: 'my.app/my.activity'} |
Android (UiAutomator2 only)
| Command | Description | Argument | Argument Example |
|---|---|---|---|
| mobile:batteryInfo | Reads the battery information from the device under test | ||
| mobile:acceptAlert | Accepts an on-screen alert | Optional button label to click on | |
| mobile:dismissAlert | Dismisses an on-screen alert | Optional button label to click on | |
| mobile:scrollBackTo | Scroll from one element to another | {elementId, elementToId} |
{elementId: 2, elementToId: 1} |
| mobile:scroll | Scroll the given scrollable element until the element identifier by strategy and selector becomes visible since Appium 1.18.0. An optional maxSwipes property can limit the number of scroll actions. It accepts an optional element property which should be the element identifier and scrollable. Without this property, Appium will select the first currently available scrollable container. Please read mobileScroll section in appium-uiautomator2-driver for more details. |
{element, strategy, selector, maxSwipes} |
{strategy: 'accessibility id', selector: 'target content description'} |
| mobile:viewportScreenshot | Like screenshot but only includes contents of viewport | ||
| mobile:viewportRect | Returns the coordinates and size of the viewports since Appium 1.18.0. The return type is Rectangle defined in general.js. | ||
| mobile:deepLink | Opens a deep-link URL for testing Instant Apps | {url, package} |
{url: "https://www.site.com/", package: "com.site.SomeAndroidPackage"} |
| mobile:deviceInfo | Gets device information like manufacturer, model, timezone and locale. Read GetDeviceInfo for more details. | ||
| mobile:type | Types the given Unicode string into focused field. The combination of unicodeKeyboard capability and the send keys works as replacing the text field content. The send key in W3C action works only for ASCII. This command helps such cases to append unicode text content against the focused field. |
{text} |
{text: 'happy testing'} |
Android (Espresso only)
| Command | Description | Argument | Argument Example |
|---|---|---|---|
| mobile:swipe | Perform the “swipe” view action | {element, direction} |
`{element: 2, direction: "down |
| mobile:swipe | Perform “GeneralSwipeAction” | {element, swiper, startCoordinates, endCoordinates, precisionDescriber} |
`{element: 3, swiper: "FAST |
| mobile:clickAction | Perform “ClickAction” | {element, tapper, coordinatesProvider, precisionDescriber, inputDevice, buttonState} |
{element: 2, tapper: 'Long', coordinatesProvider: 'BOTTOM_RIGHT', precisionDescriber: 'Thumb', inputDevice: 0, buttonState: 0} |
| mobile:isToastVisible | Check whether a toast message is visible. text is the mandatory argument. isRegexp is optional. text will be parsed as a regular expression pattern if isRegexp is true . isRegexp is false by default. It returns true if the text exists, or false otherwise. |
{text, isRegexp} |
{ text: 'A toast' } , { text: '^regex
|
| mobile:openDrawer | Open drawer by DrawerAction with gravity. gravity is option. The default is GravityCompat.START. This method blocks until the drawer is fully open. No operation if the drawer is already open. |
{element, gravity} |
{ element: element_id } , { element: element_id, gravity: 3 }
|
| mobile:closeDrawer | Close drawer by DrawerAction with gravity. gravity is option. The default is GravityCompat.START. This method blocks until the drawer is fully closed. No operation if the drawer is already closed. |
{element, gravity} |
{ element: element_id } , { element: elementId, gravity: 3 }
|
| mobile:setDate | Set date by PickerActions#setDate for DataPicker. | {element, year, monthOfYear, dayOfMonth} |
{element: elementId, year: 2018, monthOfYear: 12, dayOfMonth: 1} |
| mobile:setTime | Set time by PickerActions#setTime for TimePicker. | {element, hours, minutes} |
{element: elementId, hours: 12, minutes: 10} |
| mobile:navigateTo | Action to NavigationView by NavigationViewActions#navigateTo. The view must be a child of a DrawerLayout, of type NavigationView, visible on screen and displayed on screen. | {element, menuItemId} |
{element: elementId, menuItemId: 1} |
| mobile:scrollToPage | Action to ViewPager by ViewPagerActions. scrollTo must be one of first , last , left , right . scrollTo is used by default if scrollTo and scrollToPage are provided. |
{scrollTo, scrollToPage, smoothScroll} |
{element: elementId, scrollTo: 'left', smoothScroll: true} , {element: elementId, scrollToPage: 2}
|
| mobile:backdoor | Invoke arbitrary methods defined in Android app. The methods must be public in Java and must be open in Kotlin. target is activity , application or element . methods are methods you would like to invoke. element is mandatory if target is element . Read docstring of mobileBackdoor method here for more details |
{target, methods, element} |
{target: 'activity', methods: [{name: 'method1'}, {name: 'method2', args: [{value: 'hello appium', type: 'java.lang.String'}] }] } , {target: 'element', element: elementId, [{name: 'getTypeface'}, {name: 'isItalic'}]}
|
| mobile:flashElement | Flashes an element on the screen to visually confirm you are operating on the correct element. Can optionally set durationMillis (in ms) and repeatCount of animation |
{element, durationMillis, repeatCount} |
{element: "1234-abcd-5678", durationMillis: 1000, repeatCount: 10} |
| mobile:uiautomator | Drive areas which are not part of App Under Test, using uiautomator2 APIs. strategy can be one of: “clazz”, “res”, “text”, “textContains”, “textEndsWith”, “textStartsWith”,“desc”, “descContains”, “descEndsWith”, “descStartsWith” and “pkg”, taken from uiautomator By class. action can be one of: “click”, “longClick”, “getText”, “getContentDescription”, “getClassName”,“getResourceName”, “getVisibleBounds”, “getVisibleCenter”, “getApplicationPackage”,“getChildCount”, “clear”, “isCheckable”, “isChecked”, “isClickable”, “isEnabled”,“isFocusable”, “isFocused”, “isLongClickable”, “isScrollable” and “isSelected”, taken from uiautomator UiObject2. index is optional, if not given, will return all matching results |
{strategy, locator, index, action} |
{strategy: 'clazz', locator: 'android.widget.TextView', index: 2, action: "getText"} |
| mobile:webAtoms | Runs a chain of webatoms. withElement and perform are basic chain items. Please refer issue and Sample test code as references. |
{webviewElement, forceJavascriptEnabled, methodChain} |
(webdriverio) { webviewElement: webviewEl.value, forceJavascriptEnabled: true, methodChain: [...]}
|
| mobile:dismissAutofill | Disable autofill dialog in Android O+ | {element} |
{element: elementId} |
| mobile:deviceInfo | Gets device information like manufacturer, model, timezone and locale. Read GetDeviceInfo for more details. |
Support
Appium Server
| Platform | Driver | Platform Versions | Appium Version | Driver Version |
|---|---|---|---|---|
| iOS | XCUITest | 9.3+ | 1.6.0+ | All |
| UIAutomation | 8.0 to 9.3 | All | All | |
| Android | Espresso | ?+ | 1.9.0+ | All |
| UiAutomator2 | ?+ | 1.6.0+ | All | |
| UiAutomator | 4.3+ | All | All | |
| Mac | Mac | ?+ | 1.6.4+ | All |
| Windows | Windows | 10+ | 1.6.0+ | All |
Appium Clients
| Language | Support | Documentation |
|---|---|---|
| Java | All | seleniumhq.github.io |
| Python | All | selenium-python.readthedocs.io |
| Javascript (WebdriverIO) | All | |
| Javascript (WD) | All | github.com |
| Ruby | All | www.rubydoc.info |
| PHP | All | github.com |
| C# | All | github.com |
HTTP API Specifications
Endpoint
POST /session/:session_id/execute
URL Parameters
| name | description |
|---|---|
| session_id | ID of the session to route the command to |
JSON Parameters
| name | type | description |
|---|---|---|
| script | string |
The mobile command to execute |
| args | array |
The JSON serializable arguments |
Response
The command result ( any )