Awesome

Appium UiAutomator2 Driver

Appium UiAutomator2 Driver is a test automation framework for Android devices. Appium UiAutomator2 Driver automates native, hybrid and mobile web apps, tested on emulators and real devices. Appium UiAutomator2 Driver is part of the Appium mobile test automation tool. The driver operates in scope of W3C WebDriver protocol with several custom extensions to cover operating-system specific scenarios.

UiAutomator2 Driver proxies most of the commands to UiAutomator2 server, which uses Google's UiAutomator framework under the hood. Some commands are proxied directly to appium-adb and other helpers built on top of Android platform tools.

Note

Since version 2.0.0 UiAutomator2 driver has dropped the support of Appium 1, and is only compatible to Appium 2. Use the appium driver install uiautomator2 command to add it to your Appium 2 dist.

Requirements

On top of standard Appium requirements UiAutomator2 driver also expects the following prerequisites:

• Windows, Linux and macOS are supported as hosts
• Android SDK Platform tools must be installed. Android Studio IDE also provides a convenient UI to install and manage the tools.
• ANDROID_HOME or ANDROID_SDK_ROOT environment variable must be set
• Java JDK must be installed and JAVA_HOME environment variable must be set. Android SDK below API 30 requires Java 8. Android SDK 30 and above requires Java 9 or newer.
• Emulator platform image must be installed if you plan to run your tests on it. Android Studio IDE also provides a convenient UI to install and manage emulators.
• Real Android devices must have USB debugging enabled and should be visible as online in adb devices -l output.
• The minimum version of Android API must be 5.0 (API level 21) (6.0 is recommended as version 5 has some known compatibility issues).

Doctor

Since driver version 2.39.0 you can automate the validation for the most of the above requirements as well as various optional ones needed by driver extensions by running the appium driver doctor uiautomator2 server command.

Capabilities

General

Driver/Server

App

App Localization

ADB

Emulator (Android Virtual Device)

App Signing

Device Locking

MJPEG

Web Context

Other

Element Attributes

UiAutomator2 driver supports the following element attributes:

Element Location

UiAutomator2 driver supports the following location strategies:

[!WARNING] Google is going to deprecate and remove UiCollection, UiObject, UiScrollable, and UiSelector support from the UiAutomator framework. This will render all -android uiautomator-based locators invalid, so please keep it in mind while using them or plan to use them in the future.

BiDi Protocol Support

UIAutomator2 driver has partial support of the BiDi Protocol since version 3.7.10. Check the Supported BiDi Commands And Events document for more details.

Parallel Tests

It is possible to execute tests in parallel using UiAutomator2 driver. Appium allows to do this on per-process (multiple server processes running on different ports managing single session) or per-request basis (single server process managing multiple sessions, more preferable, uses less resources and ensures better control over running sessions).

Note: If you are not going to run your tests in parallel then consider enabling the --session-override Appium server argument. It forces the server to close all pending sessions before a new one could be opened, which allows you to avoid possible issues with such sessions silently running/expiring in the background.

Important Real Device Capabilities

• udid: The unique device id.
• systemPort: Set a unique system port number for each parallel session. Otherwise you might get a port conflict such as in this issue.
• chromedriverPort: The unique chromedriver port if testing web views or Chrome.
• mjpegServerPort: Set a unique MJPEG server port for each parallel session if you are going to record a video.

Important Emulator Capabilities

• avd: The unique emulator name.
• systemPort: Set a unique system port number for each parallel session.
• chromedriverPort: The unique chromedriver port (if testing web views or Chrome).
• mjpegServerPort: Set a unique MJPEG server port for each parallel session if you are going to record a video.

Settings API

UiAutomator2 driver supports Appium Settings API. Along with the common settings the following driver-specific settings are currently available:

Platform-Specific Extensions

Beside of standard W3C APIs the driver provides the below custom command extensions to execute platform specific scenarios. Use the following source code examples in order to invoke them from your client code:

// Java 11+
var result = driver.executeScript("mobile: <methodName>", Map.ofEntries(
    Map.entry("arg1", "value1"),
    Map.entry("arg2", "value2")
    // you may add more pairs if needed or skip providing the map completely
    // if all arguments are defined as optional
));

// WebdriverIO
const result = await driver.executeScript('mobile: <methodName>', [{
    arg1: "value1",
    arg2: "value2",
}]);

# Python
result = driver.execute_script('mobile: <methodName>', {
    'arg1': 'value1',
    'arg2': 'value2',
})

# Ruby
result = @driver.execute_script 'mobile: <methodName>', {
    arg1: 'value1',
    arg2: 'value2',
}

// Dotnet
object result = driver.ExecuteScript("mobile: <methodName>", new Dictionary<string, object>() {
    {"arg1", "value1"},
    {"arg2", "value2"}
});

mobile: shell

Executes the given shell command on the device under test via ADB connection. This extension exposes a potential security risk and thus is only enabled when explicitly activated by the adb_shell server command line feature specifier.

Arguments

Returned Result

Depending on the includeStderr value this API could either return a string, which is equal to the stdout stream content of the given command or a dictionary whose elements are stdout and stderr and values are contents of the corresponding outgoing streams. If the command exits with a non-zero return code then an exception is going to be thrown. The exception message will be equal to the command stderr.

mobile: execEmuConsoleCommand

Executes a command through emulator telnet console interface and returns its output. The emulator_console server feature must be enabled in order to use this method.

Arguments

Returned Result

The actual command output. An error is thrown if command execution fails.

Mobile Gesture Commands

UiAutomator2 provides several extensions that allow to automate popular mobile gesture shortcuts:

• mobile: dragGesture
• mobile: flingGesture
• mobile: doubleClickGesture
• mobile: clickGesture
• mobile: longClickGesture
• mobile: pinchCloseGesture
• mobile: pinchOpenGesture
• mobile: swipeGesture
• mobile: scrollGesture

These gestures are documented in the Automating Mobile Gestures tutorial. Check W3C Actions API and Low-Level Insights on Android Input Events if you need to automate more complicated gestures.

mobile: scroll

Scrolls the given scrollable element until an element identified by strategy and selector becomes visible. This function returns immediately if the destination element is already visible in the view port. Otherwise it would scroll to the very beginning of the scrollable control and tries to reach the destination element by scrolling its parent to the end step by step. The scroll direction (vertical or horizontal) is detected automatically.

Arguments

mobile: deepLink

Start URI that may take users directly to the specific content in the app. Read Reliably Opening Deep Links Across Platforms and Devices for more details.

Arguments

mobile: startLogsBroadcast

Starts Android logcat broadcast websocket on the same host and port where Appium server is running at /ws/session/:sessionId:/appium/logcat endpoint. The method will return immediately if the web socket is already listening. Each connected webcoket listener will receive logcat log lines as soon as they are visible to Appium. Read Using Mobile Execution Commands to Continuously Stream Device Logs with Appium for more details.

mobile: stopLogsBroadcast

Stops the previously started logcat broadcasting websocket server. This method will return immediately if no server is running. Read Using Mobile Execution Commands to Continuously Stream Device Logs with Appium for more details.

mobile: deviceidle

This is a wrapper to 'adb shell dumpsys deviceidle' interface. Read Diving Into Android 'M' Doze for more details. This API only exists since Android 6.

Arguments

mobile: acceptAlert

Tries to accept an Android alert. This method might not always be reliable as there is no single standard for how Android alerts should look like within the Accessibility representation.

Arguments

mobile: dismissAlert

Tries to dismiss an Android alert. This method might not always be reliable as there is no single standard for how Android alerts should look like within the Accessibility representation.

Arguments

mobile: batteryInfo

Retrieves the battery information from the device under test.

Returned Result

The extension returns a dictionary whose entries are:

mobile: deviceInfo

Retrieves the information about the device under test, like the device model, serial number, network connectivity info, etc.

Returned Result

The extension returns a dictionary whose entries are the device properties. Check https://github.com/appium/appium-uiautomator2-server/blob/master/app/src/main/java/io/appium/uiautomator2/handler/GetDeviceInfo.java to get the full list of returned keys and their corresponding values.

mobile: getDeviceTime

Retrieves the current device's timestamp.

Arguments

Returned Result

The device timestamp string formatted according to the given specifiers

mobile: changePermissions

Changes package permissions in runtime.

Arguments

mobile: getPermissions

Gets runtime permissions list for the given application package.

Arguments

Returned Result

Array of strings, where each string is a permission name. the array could be empty.

mobile: performEditorAction

Performs IME action on the currently focused edit element.

Very often Android developers use onEditorAction callback with actionId argument to implement actions handling, for example, when Search or Done button is pressed on the on-screen keyboard. This mobile extension is supposed to emulate the invokation of such callback on the focused element.

Arguments

mobile: startScreenStreaming

Starts device screen broadcast by creating MJPEG server. Multiple calls to this method have no effect unless the previous streaming session is stopped. This method only works if the adb_screen_streaming feature is enabled on the server side. It is also required that GStreamer with gst-plugins-base, gst-plugins-good and gst-plugins-bad packages are installed and available in PATH on the server machine.

Arguments

mobile: stopScreenStreaming

Stop the previously started screen streaming. If no screen streaming server has been started then nothing is done.

mobile: getNotifications

Retrieves Android notifications via Appium Settings helper. Appium Settings app itself must be manually granted to access notifications under device Settings in order to make this feature working. Different vendors might require more than just the normal Notification permissions at the usual Apps menu. Try to look in places like Privacy menus if you are getting zero items retrieved while expecting some results.

Appium Settings helper keeps all the active notifications plus notifications that appeared while it was running in the internal buffer, but no more than 100 items altogether. Newly appeared notifications are always added to the head of the notifications array. The isRemoved flag is set to true for notifications that have been removed. See https://developer.android.com/reference/android/service/notification/StatusBarNotification and https://developer.android.com/reference/android/app/Notification.html for more information on available notification properties and their values.

Returned Result

The example output is:

{
   "statusBarNotifications":[
     {
       "isGroup":false,
       "packageName":"io.appium.settings",
       "isClearable":false,
       "isOngoing":true,
       "id":1,
       "tag":null,
       "notification":{
         "title":null,
         "bigTitle":"Appium Settings",
         "text":null,
         "bigText":"Keep this service running, so Appium for Android can properly interact with several system APIs",
         "tickerText":null,
         "subText":null,
         "infoText":null,
         "template":"android.app.Notification$BigTextStyle"
       },
       "userHandle":0,
       "groupKey":"0|io.appium.settings|1|null|10133",
       "overrideGroupKey":null,
       "postTime":1576853518850,
       "key":"0|io.appium.settings|1|null|10133",
       "isRemoved":false
     }
   ]
}

mobile: openNotifications

Opens notifications drawer on the device under test. Does nothing if the drawer is already opened. Available since driver version 2.23

mobile: listSms

Retrieves the list of the most recent SMS properties list via Appium Settings helper. Messages are sorted by date in descending order.

Arguments

Returned Result

The example output is:

 {
   "items":[
     {
       "id":"2",
       "address":"+123456789",
       "person":null,
       "date":"1581936422203",
       "read":"0",
       "status":"-1",
       "type":"1",
       "subject":null,
       "body":"\"text message2\"",
       "serviceCenter":null
     },
     {
       "id":"1",
       "address":"+123456789",
       "person":null,
       "date":"1581936382740",
       "read":"0",
       "status":"-1",
       "type":"1",
       "subject":null,
       "body":"\"text message\"",
       "serviceCenter":null
     }
   ],
   "total":2
 }

mobile: type

Types the given Unicode string. It is expected that the focus is already put to the destination input field before this method is called. The main difference between this method and the sendKeys one is that it emulates true typing like it was done from an on-screen keyboard. It also properly supports Unicode input characters.

Arguments

mobile: sensorSet

Emulate changing of sensor values on the connected emulator. This extension does not work on real devices.

Arguments

mobile: pullFile

Pulls a remote file from the device.

Arguments

Returned Result

Base64-encoded string, which represents the content of the remote file.

mobile: pushFile

Pushes a local file to the device.

Arguments

mobile: pullFolder

Pulls a remote folder from the device.

Arguments

Returned Result

Base64-encoded string, which represents the zipped content of the remote folder.

mobile: deleteFile

Deletes a file on the remote device.

Arguments

mobile: isAppInstalled

Verify whether an application is installed on the device under test.

Arguments

Returned Result

True or false

mobile: queryAppState

Queries the current state of the app.

Arguments

Returned Result

The following numbers could returned:

• The app is not installed: 0
• The app is installed and is not running: 1
• The app is running in background: 3
• The app is running in foreground: 4

mobile: activateApp

Activates the given application or launches it if necessary. The action literally simulates clicking the corresponding application icon on the dashboard.

Arguments

mobile: removeApp

Remove the corresponding application if is installed. The call is ignored if the app is not installed.

Arguments

Returned Result

True is the app has been found on the device and successfully removed. Otherwise false.

mobile: terminateApp

Terminates the app and waits until the app is terminated up to the given timeout by checking the app state to ensure if the app process is actually stopped.

The app state check can be skipped if the given timeout is lower or equal to zero since UIAutomator driver 2.9.0. The skip helps when you want to terminate the app process but do not want to check the process existence because the app under test may, for example, restart it automatically.

Arguments

Returned Result

True if the app has been successfully terminated.

mobile: installApp

Installs the given application package to the device under test. It might raise the INSTALL_FAILED_VERSION_DOWNGRADE error if the installation was a version downgrade.

Arguments

mobile: clearApp

Deletes all data associated with a package. Calls adb shell pm clear under the hood. The app should be accessible, should not be running, and should exist on the device under test for this extension to work properly.

Arguments

Returned Result

Stdout of the corresponding adb command.

mobile: startActivity

Starts the given activity intent. Invokes am start/am start-activity command under the hood. This method extends the functionality of the Start Activity app management API.

Arguments

Returned Result

The actual stdout of the downstream am command.

Example

Use the code snippet below to represent the following shell command: shell am start-activity -W -n io.appium.android.apis/io.appium.android.apis.ApiDemos -S -a android.intent.action.MAIN -c android.intent.category.LAUNCHER -f 0x10200000', which is usually similar to what is called in a new session request. If you replace 'io.appium.android.apis/io.appium.android.apis.ApiDemos' with your expected launchable activity, it would be the alternative method to start the activity in session.

Please check how appium adds flags for more details to understand how Appium builds flags.

# Ruby
driver.execute_script 'mobile: startActivity', {
    wait: true,
    stop: true,
    action: 'android.intent.action.MAIN',
    component: 'io.appium.android.apis/io.appium.android.apis.ApiDemos',
    categories: ['android.intent.category.LAUNCHER'],
    flags: '0x10200000'
}

mobile: startService

Starts the given service intent. Invokes am startservice or am start-service command under the hood.

Arguments

Returned Result

The actual stdout of the downstream am command.

mobile: stopService

Stops the given service intent. Invokes am stopservice or am stop-service command under the hood.

Arguments

mobile: broadcast

Send a broadcast Intent. Invokes am broadcast command under the hood.

Arguments

Returned Result

The actual stdout of the downstream am command.

mobile: getContexts

Retrieves a WebViews mapping based on CDP endpoints

Arguments

Returned Result

The following json demonstrates the example of WebviewsMapping object. Note that description in page can be an empty string most likely when it comes to Mobile Chrome)

 {
   "proc": "@webview_devtools_remote_22138",
   "webview": "WEBVIEW_22138",
   "info": {
     "Android-Package": "io.appium.settings",
     "Browser": "Chrome/74.0.3729.185",
     "Protocol-Version": "1.3",
     "User-Agent": "Mozilla/5.0 (Linux; Android 10; Android SDK built for x86 Build/QSR1.190920.001; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/74.0.3729.185 Mobile Safari/537.36",
     "V8-Version": "7.4.288.28",
     "WebKit-Version": "537.36 (@22955682f94ce09336197bfb8dffea991fa32f0d)",
     "webSocketDebuggerUrl": "ws://127.0.0.1:10900/devtools/browser"
   },
   "pages": [
     {
       "description": "{\"attached\":true,\"empty\":false,\"height\":1458,\"screenX\":0,\"screenY\":336,\"visible\":true,\"width\":1080}",
       "devtoolsFrontendUrl": "http://chrome-devtools-frontend.appspot.com/serve_rev/@22955682f94ce09336197bfb8dffea991fa32f0d/inspector.html?ws=127.0.0.1:10900/devtools/page/27325CC50B600D31B233F45E09487B1F",
       "id": "27325CC50B600D31B233F45E09487B1F",
       "title": "Releases · appium/appium · GitHub",
       "type": "page",
       "url": "https://github.com/appium/appium/releases",
       "webSocketDebuggerUrl": "ws://127.0.0.1:10900/devtools/page/27325CC50B600D31B233F45E09487B1F"
     }
   ],
   "webviewName": "WEBVIEW_com.io.appium.setting"
 }

mobile: installMultipleApks

Install applications via install-multiple option. Please read more details in the corresponding section of the adb --help command output.

Arguments

mobile: lock

Lock the device (and optionally unlock it after a certain amount of time). Only simple (e.g. without a password) locks are supported.

Arguments

mobile: unlock

Unlocks the device if it is locked. Noop if the device's screen is not locked.

Arguments

mobile: isLocked

Determine whether the device is locked.

Returned Result

Either true or false

mobile: setGeolocation

Sets emulated geolocation coordinates on the device under test.

Arguments

mobile: getGeolocation

Retrieves current geolocation coordinates from the device under test. If coordinates are mocked/emulated then these coordinates would be returned.

Returned Result

A map with the following entries:

mobile: resetGeolocation

Resets mocked geolocation provider to the default/system one. Only works for real devices.

mobile: refreshGpsCache

Sends a request to refresh the GPS cache on the device under test. By default the location tracking is configured for low battery consumption, so you might need to call this extension periodically to get the updated geo location if the actual (or mocked) device location is changed too frequently. The feature only works if the device under test has Google Play Services installed. In case the vanilla LocationManager is used the device API level must be at version 30 (Android R) or higher.

Arguments

mobile: startMediaProjectionRecording

Starts a new recording of the device activity using Media Projection API. This API is available since Android 10 (API level 29) and allows to record device screen and audio in high quality. Video and audio encoding is done by Android itself. The recording is done by Appium Settings helper.

Arguments

Returned Result

true if a new recording has successfully started. false if another recording is currently running.

mobile: isMediaProjectionRecordingRunning

Check if a media projection recording is currently running

Returned Result

true if a recording is running.

mobile: stopMediaProjectionRecording

Stops a recording and retrieves the recently recorded media. If no recording has been started before then an error is thrown. If the recording has been already finished before this API has been called then the most recent recorded media is returned.

Arguments

Returned Result

Base64-encoded content of the recorded media file if remotePath argument is falsy or an empty string.

mobile: getConnectivity

Returns connectivity states for different services

Arguments

Returned Result

A map is returned containing the following possible items (depending on which values have been passed to services argument):

mobile: setConnectivity

Set the connectivity state for different services. At least one valid service name must be provided in arguments. Missing values tell the driver to not change the corresponding service's state.

Note

Switching Wi-Fi and mobile data states reliably work on emulators for all Android versions. Real devices support proper state switching only since Android 11.

Note

UiAutomator2 REST server app is running on the device under test and might be terminated/disconnected by Android thus failing the driver session as a result of using this API. The only way to restore the session would be to quit it after the network state is changed and then reopen it with noReset capability being set to true when the connectivity is restored.

Arguments

mobile: getAppStrings

Retrieves string resources for the given app language. An error is thrown if strings cannot be fetched or no strings exist for the given language abbreviation. Available since driver version 2.15.0

Arguments

Returned Result

App strings map, where keys are resource identifiers.

mobile: hideKeyboard

Tries to hide the on-screen keyboard. Throws an exception if the keyboard cannot be hidden. Does nothing if the keyboard is already hidden.

Returned Result

true if the keyboard was successfully hidden or false if it was already invisible.

mobile: isKeyboardShown

Checks if the system on-screen keyboard is visible.

Returned Result

true if the keyboard is visible

mobile: pressKey

Emulates single key press on the key with the given code. Available since driver version 2.17.0

Arguments

mobile: backgroundApp

Puts the app to the background and waits the given number of seconds. Then restores the app if necessary. The call is blocking. Available since driver version 2.19.0

Arguments

mobile: getCurrentActivity

Returns the name of the currently focused app activity. Available since driver version 2.20

Returned Result

The activity class name. Could be null

mobile: getCurrentPackage

Returns the name of the currently focused app package identifier. Available since driver version 2.20

Returned Result

The package class name. Could be null

mobile: getDisplayDensity

Returns the display density value measured in DPI. Available since driver version 2.21

Returned Result

The actual DPI value as integer number

mobile: getSystemBars

Returns properties of various system bars. Available since driver version 2.21

Returned Result

A dictionary whose entries are:

• statusBar
• navigationBar

Values are dictionaries with the following properties:

• visible: Whether the bar is visible (equals to false if the bar is not present in the system info output)
• x: Bar x coordinate (might be zero if the bar is not present in the system info output)
• y: Bar y coordinate (might be zero if the bar is not present in the system info output)
• width: Bar width (might be zero if the bar is not present in the system info output)
• height: Bar height (might be zero if the bar is not present in the system info output)

mobile: fingerprint

Emulate fingerprint on Android Emulator. Only works on API 23+. Available since driver version 2.22

Arguments

mobile: sendSms

Emulate sending an SMS to the given phone number. Only works on emulators. Available since driver version 2.22

Arguments

mobile: gsmCall

Emulate a GSM call to the given phone number. Only works on emulators. Available since driver version 2.22

Arguments

mobile: gsmSignal

Emulate GSM signal strength change event. Only works on emulators. Available since driver version 2.22

Arguments

mobile: gsmVoice

Emulate GSM voice state change event. Only works on emulators. Available since driver version 2.22

Arguments

mobile: powerAC

Emulate AC power state change. Only works on emulators. Available since driver version 2.22

Arguments

mobile: powerCapacity

Emulate power capacity change. Only works on emulators. Available since driver version 2.22

Arguments

mobile: networkSpeed

Emulate different network connection speed modes. Only works on emulators. Available since driver version 2.22

Arguments

mobile: replaceElementValue

Sends a text to the given element by replacing its previous content. Available since driver version 2.22

Arguments

mobile: toggleGps

Switches GPS setting state. This API only works reliably since Android 12 (API 31). Available since driver version 2.23

mobile: isGpsEnabled

Returns true if GPS is enabled on the device under test. Available since driver version 2.23

mobile: getPerformanceDataTypes

Fetches the list of supported performance data types that could be used as dataType argument value to mobile: getPerformanceData extension. Available since driver version 2.24

Returned Result

List of strings, where each item is data type name.

mobile: getClipboard

Retrieves the plaintext content of the device's clipboard. Available since driver version 3.7

Returned Result

Base64-encoded content of the clipboard or an empty string if the clipboard is empty.

mobile: setClipboard

Allows to set the plain text content of the device's clipboard. Available since driver version 3.7

Arguments

mobile: getPerformanceData

Retrieves performance data about the given Android subsystem. The data is parsed from the output of the dumpsys utility. Available since driver version 2.24

Arguments

Returned Result

The output depends on the selected subsystem. It is organized into a table, where the first row represents column names and the following rows represent the sampled data for each column. Example output for different data types:

• batteryinfo:

[
  [power],
  [23]
]

• memoryinfo:

[
  [totalPrivateDirty, nativePrivateDirty, dalvikPrivateDirty, eglPrivateDirty, glPrivateDirty, totalPss, nativePss, dalvikPss, eglPss, glPss, nativeHeapAllocatedSize, nativeHeapSize],
  [18360, 8296, 6132, null, null, 42588, 8406, 7024, null, null, 26519, 10344]
]

• networkinfo:

// emulator
[
  [bucketStart, activeTime, rxBytes, rxPackets, txBytes, txPackets, operations, bucketDuration],
  [1478091600000, null, 1099075, 610947, 928, 114362, 769, 0, 3600000],
  [1478095200000, null, 1306300, 405997, 509, 46359, 370, 0, 3600000]
]
// real devices
[
  [st, activeTime, rb, rp, tb, tp, op, bucketDuration],
  [1478088000, null, null, 32115296, 34291, 2956805, 25705, 0, 3600],
  [1478091600, null, null, 2714683, 11821, 1420564, 12650, 0, 3600],
  [1478095200, null, null, 10079213, 19962, 2487705, 20015, 0, 3600],
  [1478098800, null, null, 4444433, 10227, 1430356, 10493, 0, 3600]
]

• cpuinfo:

[
  [user, kernel],
  [0.9, 1.3]
]

mobile: statusBar

Performs commands on the system status bar. A thin wrapper over adb shell cmd statusbar CLI. Works on Android 8 (Oreo) and newer. Available since driver version 2.25

Arguments

Status Bar Commands

• expandNotifications: Open the notifications panel.
• expandSettings: Open the notifications panel and expand quick settings if present.
• collapse: Collapse the notifications and settings panel.
• addTile: Add a TileService of the specified component.
• removeTile: Remove a TileService of the specified component.
• clickTile: Click on a TileService of the specified component.
• getStatusIcons: Returns the list of status bar icons and the order they appear in. Each list item is separated with a new line character.

Returned Result

The actual downstream command output. It depends on the selected command and might be empty.

mobile: scheduleAction

mobile: unscheduleAction

mobile: getActionHistory

These extensions allow to deal with short-living UI elements. Read the documentation on Scheduled Actions for more details and code examples.

mobile: screenshots

Retrieves a screenshot of each display available to Android. This functionality is only supported since Android 10.

Arguments

Returns

A dictionary where each key is the display identifier and the value has the following keys:

• id: The same display identifier
• name: Display name
• isDefault: Whether this display is the default one
• payload: The actual PNG screenshot data encoded to base64 string

mobile: setUiMode

Set the device UI appearance. A thin wrapper over adb shell cmd uimode CLI. Works on Android 10 and newer. Available since driver version 2.34

Arguments

mobile: getUiMode

Gets the device UI appearance for the given mode. A thin wrapper over adb shell cmd uimode CLI. Works on Android 10 and newer. Available since driver version 2.34

Arguments

Returned Result

The actual mode value. Supported values for different UI modes are:

• night: yes,no,auto,custom_schedule,custom_bedtime
• car: yes,no

mobile: sendTrimMemory

Simulates the onTrimMemory() event for the given package, which allows to verify the app functinality under different RAM-related circumstances. Read Manage your app's memory for more details. Available since driver version 2.41

Arguments

mobile: injectEmulatorCameraImage

Simulates an image injection into the VirtualScene emulator camera background. Calls to this extension should seamlessly change the foreground picture in the VirtualScene emulator camera view to the supplied one. This extension could, for example, be useful if you need to verify QR codes scanning by the application under test. Available since driver version 3.2.0

Arguments

Required Preconditions

This feature only works on Android emulators. It is mandatory to provide a value (it could also be an empty map to use defaults) to the appium:injectedImageProperties capability in order to prepare the emulator for image injection if this extension is used on a newly created or resetted device.

There is also a possiblity to perform a manual configuration of the necessary preconditions if you don't want to restart the emulator on session startup. For that replace the content of the Toren1BD.posters file located in $ANDROID_HOME/emulator/resources folder with the following text:

poster wall
size 2 2
position -0.807 0.320 5.316
rotation 0 -150 0
default poster.png

poster table
size 1 1
position 0 0 -1.5
rotation 0 0 0

Save the changed file and re(start) the emulator to pick up the changes. You may also customize values for different image properties under poster table in the above text snippet.

mobile: bluetooth

Allows to control the bluetooth adapter in the device under test. An error is thrown if the device has no default bluetooth adapter. Available since driver version 3.4.0

Arguments

mobile: nfc

Allows to control the NFC adapter in the device under test. An error is thrown if the device has no default NFC adapter. Available since driver version 3.4.0

Arguments

Applications Management

UiAutomator2 driver supports Appium endpoints for applications management:

• Check if app is installed (mobile: isAppInstalled)
• Install/upgrade app (mobile: installApp)
• Activate app (mobile: activateApp)
  • Since UIAutomator2 driver v2.2.0, the server calls am start/am start-activity to start the application on devices with API level 24+. monkey tool is called on devices below API level 24.
  • UIAutomator2 driver v2.1.2 and lower versions call the monkey tool on all devices.
  • The monkey tool turns on auto rotation, so please consider using mobile: startActivity if you would like to keep your current rotation preferences.
• Uninstall app (mobile: removeApp)
• Terminate app (mobile: terminateApp)
• Start app activity (mobile: startActivity)
• Query the current app state (mobile: queryAppState)
• Background app (mobile: backgroundApp)

Refer to the corresponding Appium client tutorial to find out the names of the corresponding wrappers for these APIs.

Useful links:

• https://appiumpro.com/editions/9-testing-android-app-upgrades
• https://github.com/appium/python-client/blob/master/appium/webdriver/extensions/applications.py
• https://github.com/appium/java-client/blob/master/src/main/java/io/appium/java_client/InteractsWithApps.java

Files Management

UiAutomator2 driver supports Appium endpoints for files management:

• Push file (mobile: pushFile)
• Pull file (mobile: pullFile)
• Pull folder (mobile: pullFolder)

Refer to the corresponding Appium client tutorial to find out the names of the corresponding wrappers for these APIs.

Useful links:

• https://github.com/appium/java-client/blob/master/src/main/java/io/appium/java_client/InteractsWithFiles.java
• https://github.com/appium/python-client/blob/master/appium/webdriver/extensions/remote_fs.py

Clipboard Management

UiAutomator2 driver supports Appium endpoints for clipboard management:

• Set clipboard content (POST /appium/device/set_clipboard')
• Get clipboard content (POST /appium/device/get_clipboard)
• mobile: getClipboard
• mobile: setClipboard

Useful links:

• https://github.com/appium/python-client/blob/master/appium/webdriver/extensions/clipboard.py
• https://github.com/appium/java-client/blob/master/src/main/java/io/appium/java_client/clipboard/HasClipboard.java
• https://appiumpro.com/editions/16-automating-the-clipboard-on-ios-and-android

Hybrid Mode

UIA2 driver supports automation of web pages opened in mobile Chrome or Chromium, and hybrid apps that use Chrome-based web views, by managing a Chromedriver instance and proxying commands to it when necessary.

The following endpoints are used to control the current context:

• POST /session/:sessionId/context: To set the current context. The body contains a single mandatory name parameter, which has the name of the context to be set. The name of the default context is NATIVE_APP.
• GET /session/:sessionId/context: To retrieve the name of the current context
• GET /session/:sessionId/contexts: To retrieve the list of available context names
• mobile: getContexts

By default, the driver starts in the native context, which means that most of REST API commands are being forwarded to the downstream appium-uiautomator2-server. This server is running on the device under test, and trasforms API commands to appropriate low-level UiAutomator framework calls. There is always only one native context, although multiple web contexts are possible. Each web context could contain zero or more pages/windows. It is possible to start UIA2 driver session in web context by default by setting the browserName capability value or by enabling the appium:autoWebview capability.

Web context(s) could be detected if a browser or a web view is active on the device. If a context is switched to a web one then UIA2 driver spins up a Chromedriver instance for it and forwards most of the commands to that Chromedriver instance. Note that web views must be properly configured and debuggable in order to connect to them or get their names in the list of available contexts. The availability of a particular web view could be easily verified by using Chrome Remote Debugger. You could switch between different contexts (and windows in them) at any time during the session.

The appium-chromedriver package bundled with UIA2 always tries to download the most recent version of Chromedriver known to it. Google requires that the used Chromedriver version must always match to the version of the browser or a web view engine being automated. If these versions do not match then Chromedriver fails its creation, and context switch API shows a failure message similar to:

An unknown server-side error occurred while processing the command.
Original error: unknown error: Chrome version must be >= 55.0.2883.0

To work around this issue it is necessary to provide UIA2 driver with a proper Chromedriver binary that matches to the Chrome engine version running on the device under test. Read the Chromedriver/Chrome compatibility topic below to know more about finding a matching Chromedriver executable.

There are several ways to provide a customized Chromedriver to UIA2 driver:

When installing the driver

Note: This only works for driver versions below 3.8.0

Specify the Chromedriver version in the CHROMEDRIVER_VERSION environment variable:

CHROMEDRIVER_VERSION=2.20 appium install driver uiautomator2

When starting a session (manual discovery)

Chromedriver version can be specified in session capabilities, by providing the appium:chromedriverExecutable capability, containing the full path to a matching Chromedriver executable, which must be manually downloaded and put to the server file system.

When starting a session (automated discovery)

UIA2 driver could also try to detect the version of the target Chrome engine and download matching chromedriver for it automatically if it does not exist on the local file system. Read the Automatic discovery of compatible Chromedriver topic below for more details.

Chromedriver/Chrome Compatibility

Since version 2.46 Google has changed their rules for Chromedriver versioning, so now the major Chromedriver version corresponds to the major web view/browser version, that it can automate. Follow the Version Selection document in order to manually find the Chromedriver, that supports your current browser/web view if its major version is equal or above 73.

To find the minimum supported browsers for older Chromedriver versions (below 73), get the Chromium source code, check out the release commit, and check the variable kMinimumSupportedChromeVersion in the file src/chrome/test/chromedriver/chrome/version.cc. (To find the release commits, you could use git log --pretty=format:'%h | %s%d' | grep -i "Release Chromedriver version".)

The complete list of available Chromedriver releases and release notes is located at Chromedriver Storage.

The list of Chromedriver versions and their matching minimum Chrome versions known to appium-chromedriver package is stored at https://raw.githubusercontent.com/appium/appium-chromedriver/master/config/mapping.json

Automatic Discovery of Compatible Chromedriver

UIA2 driver is able to pick the correct Chromedriver for the version of Chrome/web view under test. While appium-chromedriver only comes bundled with the Chromedriver most recently released at the time of the corresponding package version's release, more Chromedriver versions could be downloaded and placed into a custom location indicated to UIA2 driver via the appium:chromedriverExecutableDir capability.

A custom mapping of Chromedrivers to the minimum Chrome/web view version they support could be given to UIA2 driver through the appium:chromedriverChromeMappingFile capability. This should be the absolute path to a file with the mapping in it. The contents of the file needs to be parsable as a JSON object, like:

{
  "2.42": "63.0.3239",
  "2.41": "62.0.3202"
}

There is a possibility to automatically download the necessary chromedriver(s) into appium:chromedriverExecutableDir from the official Google storage. The script will automatically search for the newest chromedriver version that supports the given browser/web view, download it (the hash sum is verified as well for the downloaded archive) and add to the appium:chromedriverChromeMappingFile mapping. Everything, which is needed to be done from your side is to execute the server with chromedriver_autodownload feature enabled (like appium server --allow-insecure chromedriver_autodownload).

Troubleshooting Chromedriver Download Issues

Check the Custom binaries url section of appium-chromedriver README for more details on how to customize the download CDN.

It may also be necessary to adjust network proxy and firewall settings for the above to work.

If you use a UIA2 driver below version 3.8.0, and you would like skip the automated download of Chromedriver upon driver install, do it by defining the APPIUM_SKIP_CHROMEDRIVER_INSTALL environment variable:

APPIUM_SKIP_CHROMEDRIVER_INSTALL=1 appium driver install uiautomator2

W3C Support in Web Context

Chromedriver did not follow the W3C standard until version 75. If you encounter proxy command error like this issue, please update your Chromedriver version. Old Android devices can't use newer Chromedriver versions. You could avoid the error if you enforce Mobile JSON Wire Protocol for Chromedriver. This could be done by providing {'w3c': False} item to appium:chromeOptions capability value. Since major version 75 W3C mode is the default one for Chromedriver, although it could be still switched to JSONWP one as described above (keep in mind that eventually Chromedriver will drop the support of JSON Wire protocol completely). The history of W3C support in Chromedriver is available for reading at downloads section.

Troubleshooting

Activity Startup

If you experience issues with application activities being not found or not starting then consider checking How To Troubleshoot Activities Startup article.

Poor Elements Interaction Performance

If you observe automated tests need at least 10 seconds or more to locate/interact with a single element then consider changing the default value for waitForIdleTimeout setting. By default, UiAutomator framework (and all other Accessibility-based frameworks) always waits for the accessibility event stream to become idle before interacting with it (the default timeout there is 10000ms). This is needed to make sure all animations/transitions are finished before you, for example, interact with an element by clicking it. In case the application under test constantly runs some background animations or hogs the accessibility event stream in some other way these waits may significantly slow down the automation flow.

Setting the value of waitForIdleTimeout to zero 0 ms should completely disable any waits, and enforce interactions to happen immediately ignoring the accessibility event stream state. The downside of that would be that all interactions are never going to be delayed, so clicks and other actions might happen at wrong places of the application UI. That is why is it important to check the app under test first and fix its source to get rid of activities hogging the event loop. Sometimes it makes sence to disable animations completely for the app build under test, which could speed up your flows significantly in some situations.

Warning waitForIdleTimeout is a setting, not a capability.

Session Startup Issues

Sometimes various legacy driver parts might be cached on the device under test (like settings.apk), which would prevent a new/upgraded driver version from starting a session. Run

appium driver run uiautomator2 reset

in order to cleanup the cached UIA2 driver binaries from all connected devices on the current machine.

Socket Hangup Error

This type of error means the driver is unable to connect to the UiAutomator2 REST server, which is running on the device under test. There might be multiple causes to this issue:

• The automation session gets unexpectedly deleted if your test code sends the DELETE /session/<id> request to it, also the corresponding session and the server itself are terminated as a result. Sending further commands to the same server would create the error above because it is not listening anymore and must be newly started by the instrumentation first. Such issues usually happen if the session management is not configured properly in your code, so one starts a new session while an existing one is still running and has not been quit properly, or there is a timeout while waiting for a new command. Fixing session management logic (e.g. make sure each session is being properly created in the test setup section and is terminated in the test teardown) or changing/disabling the commands' timeout (check the newCommandTimeout capability) might help to address such type of errors.
• The server has been unexpectedly killed by Android OS itself. There might be several reasons to that. Usually fetching the logcat output and finding occurrences of io.appium.uiautomator2.server traces with error or exception label might help to figure out what happens. Sometimes it is necessary to turn off some internal phone optimizations, sometimes the server crashes because of an internal UiAutomator framework bug, sometimes because of a bug in the server code itself. Each case should be investigated separately if the search over the internet shows no matches…
• The connectivity between the phone and the host is unstable. Nothing much to add on this one. Maybe the phone has a defect, or the USB cable is damaged, or the installed Android SDK is out of date…

Element(s) Cannot be Found

All element location strategies in UIA2 driver work similarly under the hood except of the xpath one. If some element is not found, but you see/assume it is present in the page source then make sure no race condition happens. Add a timer and wait for a couple of seconds before giving up on the element location. In case the lookup still fails after the timeout and your non-xpath locator is used then, most likely, it contains a typo, or the destination element is not present. There is not much that could be done in UIA2 to change/influence that, since it passes such lookup calls directly to Google's UiAutomator framework.

In case of xpath locators you could try to change values of the following settings:

1. allowInvisibleElements
2. ignoreUnimportantViews
3. enableMultiWindows

By default, the first setting is set to false, which hides elements that are not visible from the page source and from the xpath location. Changing the setting value to true would add such invisible elements to the page source and make them locatable.

The second one is enabled by default (e.g. true). By disabling it the page source could receive more elements that are normally hidden, because of their unimportance.

The third setting being set to true extends the page source by adding the actual content of other windows that are currently present on the device's screen. For example, the on-screen keyboard in Android is not a part of the current app hierarchy, but rather belongs to a separate window.

In case of id locators you could try to change the value of the following setting:

1. disableIdLocatorAutocompletion

The general resources naming convention for Android apps is <app_id>:id/<resource_name>. This should guarantee uniqueness of each identifier accross the user interface. Although, this is only a convention and it is still allowed to have various resource names that do not follow it. If you have gotten one of such applications for automated testing then consider assigning disableIdLocatorAutocompletion setting value to true, so UiAutomator2 driver does not automatically rewrite supplied id values by adding <app_id>:id/ prefixes to them.

Warning Default values for settings above have been selected to optimize xpath lookup and page source generation performance. Having these settings always different from their default values may sometimes significantly (especially in case of huge accessbility hierarchies) reduce xpath lookup and page source generation speed.

Warning All items above are settings, not capabilities.

ClassCastException: java.util.ArrayList$ListItr cannot be cast to org.eclipse.wst.xml.xpath2.processor

This exception happens due to a known bug in the Eclipse's Psychopath library used by UiAutomator2 driver to support XPath2 syntax. The issue has been observed while using following:: or preceding:: axes in xpath queries. Unfortunately, this library has not been maintained for quite a while, and there is no good open source alternative to it. The only known workaround would be to forcefully switch the driver's XPath processor to the standard Android's Apache Harmony-based XPath1, which does not have this issue (but also does not support XPath2 syntax). See the Appium issue #16142 for more details.

A gesture, like scroll or swipe, does not have any effect / It is unclear how to do it

The UiAutomator2 driver provides multiple options for touch gestures automation. For simple gestures, like swipe, scroll, drag, double click, fling or pinch use the corresponding gesture shortcuts. You may also use UiScrollable-based UiAutomator locators to automate various scrolling behaviours. For more sophisticated gestures consider using W3C actions.

Make sure you don't use deprecated JWP touch actions APIs. They have been removed from the UIA2 driver since version 3.

If the action code in the client source looks good and satisfies the above requirements, but its execution still does not deliver the expected result then the following debugging meassures might be applied:

• Enable Show taps and Pointer location Developer options in the device Settings. After running your automation code with the above options enabled you would be able to see the exact pointer trace path and check the velocity of the gesture. It also works for multi-touch gestures. Compare the trace to how the same gesture is usually done manually and apply the necessary updates to your code.
• Check the device logcat output for possible error messages. Usually a single gesture consists of hundreds of atomic steps. If any of these steps receives incorrect/unsupported parameters then the whole gesture might fail. The log has details about each step being executed and arguments passed to it.
• Make sure the gesture has valid coordinates and respects pauses between pointer state changes. For example, it is always mandatory to provide a valid element or valid absolute coordinates to any gesture at the beginning. Android only registers a long touch/click if the pointer has been depressed for longer than 500ms. For shorter actions a simple click is registered instead.
• Do not mix webview and native elements in actions arguments. It simply won't work. Native actions could only consume native elements. A single possibility to perform a native action on a web element would be to traslate its coordinates into the native context and pass these coordinates as native action arguments.

Check the below tutorials for more details on how to build reliable action chains:

• Automating Complex Gestures with the W3C Actions API
• Swiping your way through Appium by Wim Selles #AppiumConf2021
• Low-Level Insights on Android Input Events

window/tab hanlding in WEBVIEW context implemented by chrome custom tabs

Chrome custom tabs could have its own window handlings as same as regular Selenium Web automation.

Appium lets you switch the context from NATIVE_APP to WEBVIEW_xyz, for example, to interact with the WEBVIEW contents over chromedriver. Then, if the WEBVIEW was chrome custom tabs implementation, the WEBVIEW context may require you to switch the window handler properly to interact with contents in a handler. It is worth to try out this idea if chrome://inspect or mobile: getContexts shows you available pages more than availale contexts.

# Ruby
# Change the context to WebView (Attach to a chromedriver session)
driver.set_context('WEBVIEW_XYZ')

# Get available tabs/windows in the chrome instance
driver.window_handles

# Change the tab/window in the "chrome" instance
driver.switch_to.window('a window_handle name')

# interact with the tab/window

Usage Examples

# Python3 + PyTest
import pytest

from appium import webdriver
# Options are available in Python client since v2.6.0
from appium.options.android import UiAutomator2Options


def generate_options():
    common_caps = {
        # A real device udid could be retrieved from `adb devices -l` output
        # If it is ommitted then the first available device will be used
        'appium:udid': '123456',
        # ...or run the test on an emulator
        # 'appium:avd': 'emulator-5554',
    }
    app_options = UiAutomator2Options().load_capabilities(common_caps)
    app_options.app = '/Projects/myapp.apk'
    # It might also be necessary to provide more info about app activities
    # Read [How To Troubleshoot Activities Startup](docs/activity-startup.md)
    # for more details
    # app_options.appPackage = 'com.mypackage'
    # app_options.appActivity = '.myMainActivity'
    # app_options.appWaitActivity = '.mySplashScreenActivity'
    chrome_options = UiAutomator2Options().load_capabilities(common_caps)
    chrome_options.browser_name = 'chrome'
    # Read [Hybrid Mode](#hybrid-mode)
    chrome_options.chromedriver_executable = '/Project/chromedriver_linux64'
    return [app_options, chrome_options]


@pytest.fixture(params=generate_options())
def driver(request):
    # The default URL is http://127.0.0.1:4723/wd/hub in Appium1
    drv = webdriver.Remote('http://localhost:4723', options=request.param)
    yield drv
    drv.quit()


def test_edit_text(driver):
    locator = 'android.view.TextEdit' if driver.current_context == 'NATIVE_APP' else 'input'
    edit_field = driver.find_element_by_class_name(locator)
    edit_field.send_keys('hello world')
    assert edit_field.text == 'hello world'
    edit_field.clear()
    assert edit_field.text == ''

API Notes

lock behaves differently in Android than it does in iOS. In Android it does not take any arguments, and locks the screen and returns immediately.

Development

npm install appium-uiautomator2-driver
npm run watch

Unit tests:

npm run test

Functional tests:

npm run e2e-test