Execute Mobile Command

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

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 )

See Also

官方链接:Execute Mobile Command - Appium