Awesome

Appium Espresso Driver

Appium's Espresso Driver is a test automation server for Android that uses Espresso as the underlying test technology. The Espresso Driver is a part of the Appium framework. The driver operates in scope of W3C WebDriver protocol with several custom extensions to cover operating-system specific scenarios.

The Espresso package consists of two main parts:

• The driver part (written in Node.js) ensures the communication between the Espresso server and Appium. Also includes several handlers that directly use ADB and/or other system tools without a need to talk to the server.
• The server part (written in Kotlin with some parts of Java), which is running on the device under test and transforms REST API calls into low-level Espresso commands.

Note

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

Comparison with UiAutomator2

The key difference between UiAutomator2 Driver and Espresso Driver is that UiAutomator2 is a black-box testing framework, and Espresso is a "grey-box" testing framework. The Espresso Driver itself is black-box (no internals of the code are exposed to the tester), but the Espresso framework itself has access to the internals of Android applications. This distinction has a few notable benefits. It can find elements that aren't rendered on the screen, it can identify elements by the Android View Tag, and it makes use of IdlingResource which blocks the framework from running commands until the UI thread is free. There is a limited support of out-of-app areas automation via the mobile: uiautomator command.

Requirements

On top of standard Appium requirements Espresso 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. Java major version must be 11 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).
• Gradle must be installed in order to build Espresso server.
• Both the server package and the application under test must be signed with the same digital signature. Appium does sign them automatically upon session creation, so this could only be an issue if one wants to test an application, which is already installed on the device (using noReset=true capability).
• The package under test must not have mangled class names (e.g. Proguard must not be enabled for it)

Doctor

Since driver version 2.31.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 espresso server command.

Scripts

• appium driver run espresso print-espresso-path prints the path to the Appium Espresso server root. You can modify the gradle file directly if Espresso Build Config was not sufficient.
• appium driver run espresso build-espresso builds the espresso server since driver version 2.18.0. It helps building the espresso server outside of the Appium process. Available environment variables are below:
  • SHOW_GRADLE_LOG configures if the command shows the gradle task logs. true or 1 sets it as enabled, but others set it as disabled. Defaults to disabled.
  • TEST_APP_PACKAGE configures the target application to build the espresso server for.
  • ESPRESSO_BUILD_CONFIG is an absolute path to the Espresso Build Config as JSON format file.
    • e.g. SHOW_GRADLE_LOG=true TEST_APP_PACKAGE=your.test.pkg ESPRESSO_BUILD_CONFIG=/path/to/the/config.json appium driver run build-espresso

Capabilities

General

Driver/Server

App

App Localization

ADB

Emulator (Android Virtual Device)

App Signing

Device Locking

Web Context

Other

Settings API

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

Jetpack Compose Support

Jetpack Compose is Android’s modern toolkit for building native UI. Espresso driver supports basic interactions with Compose-based applications since version 1.46.0.

Appium UiAutomator2 driver allows to interact with Jetpack Compose elements via the accessibility layer by providing testTag modifier attribute or the displayed text, but this Espresso driver allows you to access Jetpack Compose elements directly.

Interaction With Compose Elements

Espresso driver has the concept of subdrivers. This works quite similarly to the concept of contexts, while contexts are used to switch between native and web, and subdrivers are still under the native one. Each subdriver operates its own elements cache, so it is not be possible to mix Espresso and Compose elements.

In order to change between subdrivers use the driver setting. Setting its value to compose modifies driver behavior in the way it interacts with Compose elements rather that with classic Android views. It is possible to switch between espresso and compose modes at any point of time. When compose mode is active the the following webdriver commands behave differently (as of driver version 1.50.0):

• findElement(s): Element finding commands only support Compose-based locators. Read Compose Elements Location for more details.
• getPageSource: The returned page source is retrieved from Compose and all elements there contain Compose-specific attributes.
• click, isDisplayed, isEnabled, clear, getText, sendKeys, getElementRect, getValue, isSelected: These commands should properly support compose elements.
• getAttribute: Accepts and returns Compose-specific element attributes. See Compose Element Attributes for the full list of supported Compose element attributes.
• getElementScreenshot: Fetches a screenshot of the given Compose element. Available since driver version 2.14.0
• mobile: swipe: Performs swipe gesture on the given element in the given direction. The swiper argument is not supported in Compose mode. Available since driver version 2.15.0

Calling other driver element-specific APIs not listed above would most likely throw an exception as Compose and Espresso elements are being stored in completely separated internal caches and must not be mixed.

You could also check end-to-end tests for more examples on how to setup test capabilities and on the Compose usage in general:

• https://github.com/appium/appium-espresso-driver/blob/master/test/functional/commands/jetpack-componse-element-values-e2e-specs.js
• https://github.com/appium/appium-espresso-driver/blob/master/test/functional/commands/jetpack-compose-attributes-e2e-specs.js
• https://github.com/appium/appium-espresso-driver/blob/master/test/functional/commands/jetpack-compose-e2e-specs.js
• https://github.com/appium/appium-espresso-driver/blob/master/test/functional/commands/jetpack-compose-e2e-specs.js

Espresso Build Config

Espresso server is in tight connection with the application under test. That is why it is important that the server uses the same versions of common dependencies and there are no conflicts. Espresso driver allows to configure several build options via espressoBuildConfig capability. The configuration JSON supports the following entries:

toolsVersions

This entry allows to explicitly set the versions of different server components. The following map entries are supported:

additionalAppDependencies

The value of this entry must be a non empty array of dependent module names with their versions. The scripts adds all these items as api lines of dependencies category in the library build.gradle.kts script. Example: ["xerces.xercesImpl:2.8.0", "xerces.xmlParserAPIs:2.6.2"]

additionalAndroidTestDependencies

The value of this entry must be a non empty array of dependent module names with their versions. The scripts adds all these items as androidTestImplementation lines of dependencies category in the app build.gradle.kts script. Example: ["xerces.xercesImpl:2.8.0", "xerces.xmlParserAPIs:2.6.2"]

Full JSON Example

{
  "toolsVersions": {
    "androidGradlePlugin": "4.0.0"
  },
  "additionalAndroidTestDependencies": ["xerces.xercesImpl:2.8.0", "xerces.xmlParserAPIs:2.6.2"]
}

Intent Options

By default Espresso creates the following intent to start the app activity:

{
  "action": "ACTION_MAIN",
  "flags": "ACTIVITY_NEW_TASK",
  "className": "<fullyQualifiedAppActivity>"
}

Although, it is possible to fully customize these options by providing the intentOptions capability. Read Intent documentation for more details on this topic. The value of this capability is expected to be a map with the following entries:

Activity Options

Espresso driver allows to customize several activity startup options using activityOptions capability. The capability value is expected to be a map with the following entries:

Espresso Element Attributes

Espresso driver supports the following element attributes in espresso subdriver:

Compose Element Attributes

Espresso driver supports the following element attributes in compose subdriver:

Espresso Elements Location

Espresso driver supports the following location strategies in espresso subdriver:

Compose Elements Location

Espresso driver supports the following location strategies in compose subdriver:

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.of(
    "arg1", "value1",
    "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

Returns

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

Returns

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

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

Changes package permissions in runtime.

Arguments

mobile: getPermissions

Gets runtime permissions list for the given application package.

Arguments

Returns

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

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

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

Returns

The extension returns a dictionary whose entries are the device properties. Check https://github.com/appium/appium-espresso-driver/blob/master/espresso-server/app/src/androidTest/java/io/appium/espressoserver/lib/handlers/GetDeviceInfo.kt to get the full list of returned keys and their corresponding values.

mobile: swipe

Perform swipe action. Invokes Espresso swipe action under the hood.

Arguments

mobile: isToastVisible

Checks whether a toast notification with the given text is currently visible.

Arguments

Returns

Either true or false

mobile: openDrawer

Opens the DrawerLayout drawer with the gravity. This method blocks until the drawer is fully open. No operation if the drawer is already open.

Arguments

mobile: closeDrawer

Closes the DrawerLayout drawer with the gravity. This method blocks until the drawer is fully closed. No operation if the drawer is already closed.

Arguments

mobile: scrollToPage

Perform scrolling to the given page. Invokes one of the ViewPagerActions under the hood. Which action is invoked depends on the given arguments.

Arguments

mobile: navigateTo

Invokes navigateTo action under the hood.

Arguments

mobile: clickAction

Perform general click action.

Arguments

mobile: getContexts

Retrieves a WebViews mapping based on CDP endpoints

Arguments

Returns

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

Returns

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

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

Arguments

Returns

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

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

Arguments

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: 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: 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 Espresso driver 2.13.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 with intent options, activity options and locale. Activity could only be executed in scope of the current app package.

Arguments

mobile: startService

Starts the given service intent.

Arguments

mobile: stopService

Stops the given service intent.

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

Retrieves the current device's timestamp.

Arguments

Returns

The device timestamp string formatted according to the given specifiers

mobile: setDate

Set the given date for a picker control. Invokes https://developer.android.com/reference/androidx/test/espresso/contrib/PickerActions#setdate under the hood.

Arguments

mobile: setTime

Set the given time for a picker control. Invokes https://developer.android.com/reference/androidx/test/espresso/contrib/PickerActions#settime under the hood.

Arguments

mobile: flashElement

Highlights the given element in the UI by adding flashing to it

Arguments

mobile: dismissAutofill

Dismisses autofill picker if it is visible on the screen.

mobile: backdoor

Gives a possibility to invoke methods from your application under test.

Arguments

Returns

The result of the last method in the chain

mobile: uiautomator

Allows to execute a limited set of UiAutomator commands to allow out-of-app interactions with accessibility elements.

Arguments

Returns

The result of the selected action applied to found elements. If index is provided then the array will only contain one item. If the index is greater than the count of found elements then an exception will be thrown.

mobile: uiautomatorPageSource

Allows to retrieve accessibility elements hierarchy tree with UiAutomator framework. The extension calls dumpWindowHierarchy under the hood.

Returns

The UI accessibility hierarchy represented as XML document.

mobile: webAtoms

Allows to run a chain of Espresso web atoms on a web view element.

Arguments

Returns

Chain items are executed sequentially and the next item is executed on the result of the previous item. The final result is returned to the caller.

mobile: registerIdlingResources

Registers one or more idling resources.

Arguments

mobile: unregisterIdlingResources

Unregisters one or more idling resources.

Arguments

mobile: listIdlingResources

Lists all the previously registered idling resources.

Returns

List of fully qualified class names of currently registered idling resources or an empty list if no resources have been registered yet.

mobile: waitForUIThread

• Wait for the UI thread to become idle, in other words, wait for the APP to become idle.
• Use case: On compose and native combination screens, it's possible for the Espresso API to block the UI thread, which can cause the app to freeze. To resolve this issue, it's recommended to explicitly call the mobile:waitForUIThread API, which can help to unfreeze the UI thread.

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

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

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 2.44

Arguments

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

Arguments

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

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

Arguments

Returned Result

App strings map, where keys are resource identifiers.

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

Arguments

mobile: getCurrentActivity

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

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

Returned Result

The package class name. Could be null

mobile: getDisplayDensity

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

Returned Result

The actual DPI value as integer number

mobile: getSystemBars

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

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

Arguments

mobile: sendSms

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

Arguments

mobile: gsmCall

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

Arguments

mobile: gsmSignal

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

Arguments

mobile: gsmVoice

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

Arguments

mobile: powerAC

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

Arguments

mobile: powerCapacity

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

Arguments

mobile: networkSpeed

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

Arguments

mobile: replaceElementValue

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

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

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

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

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

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

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

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

Backdoor Extension Usage

Espresso driver allows to directly invoke a method from your application under test using mobile: backdoor extension. If target is set to application then methods will be invoked on the application class. If target is set to activity then methods will be invoked on the current application activity. If target is set to element then methods will be invoked on the selected view element. Only 'public' methods can be invoked ('open' modifier is necessary in Kotlin). The following primitive types are supported for method arguments: "int", "boolean", "byte", "short", "long", "float", "char". Object wrappers over primitive types with fully qualified names "java.lang.*" are also supported: "java.lang.CharSequence", "java.lang.String", "java.lang.Integer", "java.lang.Float", "java.lang.Double", "java.lang.Boolean", "java.lang.Long", "java.lang.Short", "java.lang.Character", etc.

For example, in the following arguments map

{
   "target": "activity",
   "methods":
   [
     {
       "name": "someMethod",
     },
     {
       "name": "anotherMethod",
       "args": [
         {"value": "foo", "type": "java.lang.CharSequence"},
         {"value": 1, "type": "int"}
       ]
     }
   ]
}

the anotherMethod will be called on the object returned by someMethod, which has no arguments and which was executed on the current activity instance. Also anotherMethod accepts to arguments of type java.lang.CharSequence and int. The result of anotherMethod will be serialized and returned to the client.

Parallel Tests

It is possible to execute tests in parallel using Espresso 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). Check Parallel Android Tests article for more details.

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.

Troubleshooting

• If you observe Espresso server crash on startup and various exceptions about missing class/method in the logcat output then consider updating appium:espressoBuildConfig capability with module versions that match your application under test. This might require some experimentation, as different apps have different module requirements. Check, for example, issue #812
• If you experince issues with application activities being not found or not starting then consider checking How To Troubleshoot Activities Startup article.
• Espresso requires the debug APK and app-under-test APK (AUT) to have the same signature. It automatically signs the AUT with the io.appium.espressoserver.test signature. This may be problematic if you're using an outdated Android SDK tools and/or an outdated Java version.
• If there are problems starting a session, set the capability forceEspressoRebuild to true and retry. This will force rebuilding of Espresso Server. If the following session startup is successfull, set it back to false, so the session startup performance is back to normal.
• If you experience session startup failures due to exceptions similar to Resources$NotFoundException then try to adjust your ProGuard rules:

  -dontwarn com.google.android.material.**
  -keep class com.google.android.material.** { *; }
  
  -dontwarn androidx.**
  -keep class androidx.** { *; }
  -keep interface androidx.** { *; }
  
  -dontwarn android.support.v4.**
  -keep class android.support.v4.** { *; }
  
  -dontwarn android.support.v7.**
  -keep class android.support.v7.** { *; }
  

  Please read #449 for more details on this topic.
• When you want to build without compose dependencies
  • Espresso driver has Jetpack Compose dependencies to support Jetpack Compose. It could break the application under test's dependencies. The typical case is when the application under test does not have the Jetpack Compose dependencies. Then, you can try out no compose dependencies branch). In Appium 2.0, the branch is available as appium driver install --source=local /path/to/the/appium-espress-driver with the no-compose-deps branch instead of npm installation.

Contributing

Contents of Repo

• espresso-server/: Android Java code that gets built into a test apk. The test apk runs a NanoHTTP server that implements the WebDriver protocol.
• lib/: NodeJS code that constitutes the Appium driver, which is responsible for handling capabilities and starting up the Espresso instrumentation context. Once the Espresso server is up, this code is responsible for proxying user requests to it.

Running

• To build the Espresso server and the NodeJS code, run npm run build
• To just build the Espresso server, run npm run build:server or cd espresso-server && ./gradlew clean assembleDebug assembleAndroidTest. The server can also be built from Android Studio.
  • To build the espresso server for a custom target package ./gradlew -PappiumTargetPackage=io.appium.android.apis assembleAndroidTest
• To just build NodeJS code, run npm run build:node

Tests

• Espresso server unit tests are located at io.appium.espressoserver.test and can be run in Android Studio
• NodeJS unit tests are run with npm run test
• End-to-end tests are run with npm run e2e-test (remember to run npm run build before running this command so that it has up-to-date Espresso Server and NodeJS code)