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.

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

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:

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 following custom command extensions to execute platform specific scenarios:

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

Examples

// Java
driver.executeScript("mobile: performEditorAction", ImmutableMap.of("action", "Go"));

# Python
driver.execute_script('mobile: performEditorAction', {'action': 'previous'})

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

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.

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

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

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 perfomance 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: 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 diplay 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

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)

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

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

When UIA2 driver is installed it automatically downloads Chromedriver, so there is a possibility of network or other issues leading to an installation failure.

By default Chromedriver is retrieved from https://chromedriver.storage.googleapis.com/. To use a mirror of the above URL change the value of CHROMEDRIVER_CDNURL environemnt variable:

CHROMEDRIVER_CDNURL=https://npmmirror.com/mirrors/chromedriver appium driver install uiautomator2

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

In case you would like skip the download of Chromedriver entirely, 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 experince 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 Accessiblity-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 significatly 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.

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

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.

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