Endpoints
The Espresso driver comes with a set of many available endpoints, which are primarily inherited from the Appium base driver, and can be found in their Appium docs reference pages. Refer to the documentation of your Appium client for how to call specific endpoints.
The driver also defines several additional endpoints listed below. Please note that most of the driver-specific functionality is available using Execute Methods instead.
All endpoints listed below are supported since driver version 2.13.10, unless otherwise specified.
JSON Wire Protocol¶
availableIMEEngines¶
JSONWP documentation: /session/:sessionId/ime/available_engines
Retrieves all IME (input method editor) engines available on the device under test.
Response¶
string[] - a list of available IME engines
getActiveIMEEngine¶
JSONWP documentation: /session/:sessionId/ime/active_engine
Retrieves the name of the active IME engine.
Response¶
string - the name of the active IME engine
isIMEActivated¶
JSONWP documentation: /session/:sessionId/ime/activated
Determines if IME input is available and active.
Response¶
boolean - true if IME is active, otherwise false
deactivateIMEEngine¶
JSONWP documentation: /session/:sessionId/ime/deactivate
Deactivates the currently active IME engine.
Response¶
null
activateIMEEngine¶
JSONWP documentation: /session/:sessionId/ime/activate
Activates an IME engine.
Parameters¶
| Name | Type | Description |
|---|---|---|
engine |
string |
Name of the IME engine to activate |
Response¶
null
getWindowSize¶
JSONWP documentation: /session/:sessionId/window/:windowhandle/size
Retrieves the size of the current window. The :windowhandle property is ignored, as the driver
always uses the currently active window.
Deprecated
Please use the getWindowRect endpoint instead
Response¶
Record<string, number> - object containing the width and height properties of the current
window
keys¶
JSONWP documentation: /session/:sessionId/keys
Sends a sequence of key strokes to the active element.
Deprecated
Please use the keyUp and keyDown W3C Actions instead
Parameters¶
| Name | Type | Description |
|---|---|---|
value |
string |
Keys to be sent |
Response¶
null
getLocation¶
JSONWP documentation: /session/:sessionId/element/:elementId/location
Returns the element's location on the page.
Deprecated
Please use the getElementRect endpoint instead
Response¶
Record<string, number> - object containing the x and y values of the element's top-left
coordinates
getLocationInView¶
JSONWP documentation: /session/:sessionId/element/:elementId/location_in_view
Returns the element's location on the page screen once it has been scrolled into view.
Deprecated
Please use the getElementRect endpoint instead
Response¶
Record<string, number> - object containing the x and y values of the element's top-left
coordinates
getSize¶
JSONWP documentation: /session/:sessionId/element/:elementId/size
Returns the element's size in pixels.
Deprecated
Please use the getElementRect endpoint instead
Response¶
Record<string, number> - object containing the width and height properties of the element
setGeoLocation¶
JSONWP documentation: /session/:sessionId/location
Sets the current location of the device under test.
Deprecated
Please use the mobile: setGeolocation execute
method instead
Parameters¶
| Name | Type | Description |
|---|---|---|
location |
Record<string, float> |
New device latitude, longitude and altitude |
The location parameter is an object with the following properties:
| Name | Type | Description |
|---|---|---|
altitude |
float |
Altitude of the device location |
latitude |
float |
Latitude of the device location |
longitude |
float |
Longitude of the device location |
Response¶
null
Mobile JSON Wire Protocol¶
getNetworkConnection¶
MJSONWP documentation: Device Modes
Retrieves the current state of network types (data, Wi-Fi, airplane mode).
Deprecated
Please use the mobile: getConnectivity execute
method instead
Response¶
NetworkConnectionState - a number indicating the current network state:
| Value | Data | Wi-Fi | Airplane Mode |
|---|---|---|---|
0 |
OFF | OFF | OFF |
1 |
OFF | OFF | ON |
2 |
OFF | ON | OFF |
4 |
ON | OFF | OFF |
6 |
ON | ON | OFF |
setNetworkConnection¶
MJSONWP documentation: Device Modes
Sets the state of network types (data, Wi-Fi, airplane mode).
Deprecated
Please use the mobile: setConnectivity execute
method instead
Parameters¶
Name |
Type |
Description |
|---|---|---|
parameters |
{"type":NetworkConnectionState} |
Object containing the type key, whose value is the desired network state |
Response¶
NetworkConnectionState - the new network state
Appium Protocol¶
startRecordingScreen¶
Starts recording the device screen using Android's screenrecord tool. On emulators this
functionality is only supported starting from Android 8 (Oreo / API level 27). The recording can be
stopped either using the stopRecordingScreen endpoint, or by stopping the
session itself.
Parameters¶
| Name | Type | Description |
|---|---|---|
options? |
Record<string, any> |
Options for starting the screen recording |
The following keys are supported:
Name |
Type | Description |
|---|---|---|
videoSize? |
string |
Dimensions of the resulting video, formatted as <width>x<height>. By default, the device's native display resolution is used, or 1280x720 if the native resolution is unsupported. For best results, use a size supported by your device's AVC encoder. |
bugReport? |
boolean |
Whether to add a video overlay with debugging information, such as a timestamp. Only supported since Android 9 (Pie / API level 28). |
timeLimit? |
float or string |
Maximum recording time in seconds. Set to 180 (3 minutes) by default. The maximum supported value is 1800 seconds (30 minutes). A single recording chunk can be at most 180 seconds long, so if a greater value is specified, the driver will attempt to use multiple chunks and combine them using ffmpeg. In such cases, if ffmpeg is not available on PATH, only the most recent chunk will be retained. |
bitRate? |
integer or string |
Bitrate of the video, in bits per second. Set to 20000000 (20Mbps) by default. |
forceRestart? |
boolean |
Whether to skip returning the results of any currently running screenrecording process, and start a new one right away |
If forceRestart is false or unset (the default value), all the keys supported by the
stopRecordingScreen endpoint can also be used, in order to handle the upload of the result from the
currently running screenrecord process.
Response¶
string - the Base64-encoded string of a previous screen recording, if one existed and
forceRestart and remotePath were not set, otherwise an empty string
stopRecordingScreen¶
Stops the active screen recording process started by startRecordingScreen, either returning its payload or uploading it to a remote location. On emulators this functionality is only supported starting from Android 9 (Pie / API level 28).
Parameters¶
| Name | Type | Description |
|---|---|---|
options? |
Record<string, any> |
Options for stopping the screen recording |
The following keys are supported:
Name |
Type |
Description |
|---|---|---|
remotePath? |
string |
Path to a remote location where the resulting video file should be uploaded. Supported path protocols are HTTP(S) and FTP (deprecated). An exception is thrown if the file is too big to fit in the process memory. |
user? |
string |
Username used for authentication to remotePath |
pass? |
string |
Password used for authentication to remotePath |
method? |
string |
Name of the HTTP(S) multipart upload method. Set to PUT by default. |
headers? |
Record<string, any> |
Additional headers to use for the HTTP(S) multipart upload |
fileFieldName? |
string |
Name of the form field for storing the file content blob for HTTP(S) uploads. Set to file by default. |
formFields? |
Record<string, any> or Array<[string, any]> |
Additional form fields to use for the HTTP(S) multipart upload |
Response¶
string - the Base64-encoded string of the screen recording, or an empty string if remotePath is
set or no active screen recording process is found
startActivity¶
Starts the specified app activity. The activity can only be executed in scope of the current app package.
Deprecated
Please use the mobile: startActivity execute
method instead
Parameters¶
Name |
Type | Description |
|---|---|---|
appPackage? |
string |
Package of app whose activity should be started. If omitted, the appPackage value of the app under test is used. |
appActivity |
string |
Activity to be started |
appWaitPackage? |
string |
Package to be waited on upon launching the specified activity. Set to appPackage if omitted. |
appWaitActivity? |
string |
Activity to be waited on upon launching the specified activity. Set to appActivity if omitted. |
Response¶
null
getCurrentActivity¶
Retrieves the name of the currently focused app activity.
Deprecated
Please use the mobile: getCurrentActivity
execute method instead
Response¶
string - name of the focused app activity. Could be null
getCurrentPackage¶
Retrieves the package name of the currently focused app.
Deprecated
Please use the mobile: getCurrentPackage
execute method instead
Response¶
string - name of the focused app package. Could be null
queryAppState¶
Retrieves the state of the specified app.
Deprecated
Please use the mobile: queryAppState execute
method instead
Parameters¶
| Name | Type | Description |
|---|---|---|
appId |
string |
Package identifier of the app |
Response¶
integer - a number indicating the app state:
| Number | Description |
|---|---|
0 |
Not installed |
1 |
Not running |
3 |
Running in background |
4 |
Running in foreground |
background¶
Moves the active app to the background and optionally restores it into the foreground after a specified duration. The call is blocking.
Deprecated
Please use the mobile: backgroundApp execute
method instead
Parameters¶
| Name | Type | Description |
|---|---|---|
seconds |
float |
Number of seconds after which to restore the app to foreground. If set to 0 or a negative value, automatic restoration is skipped. |
Response¶
boolean | string - the log output of launching the app if it was originally launched using
startActivity, otherwise true
getStrings¶
Retrieves string resources for the specified app language. An error is thrown if strings cannot be fetched, or no strings exist for the specified language.
Deprecated
Please use the mobile: getAppStrings execute
method instead
Parameters¶
Name |
Type | Description |
|---|---|---|
language? |
string |
Language whose strings should be retrieved. If omitted, the default system language is used (affected by the appium:language capability) |
stringFile? |
string |
Path to the app whose strings should be retrieved. If not specified, the app under test is used. |
Response¶
Record<string, string> - mapping of resource identifiers to localized strings
getClipboard¶
Retrieves the content of the primary clipboard on the device under test.
Deprecated
Please use the mobile: getClipboard execute
method instead
Parameters¶
Name |
Type | Description |
|---|---|---|
contentType? |
string |
The type to retrieve the content as. The only supported and default value is plaintext. |
Response¶
string - the clipboard content as a Base64 string. An empty string is returned if the clipboard
contains no data.
lock¶
Locks the device and optionally unlocks it after a specified duration. Only simple (e.g. without a password) locks are supported.
Deprecated
Please use the mobile: lock execute method instead
Parameters¶
| Name | Type | Description |
|---|---|---|
seconds? |
float |
Number of seconds after which to unlock the device. If omitted or set to 0, automatic unlock is skipped. |
Response¶
null
unlock¶
Unlocks the device if it is locked. Only simple (e.g. without a password) locks are supported.
Deprecated
Please use the mobile: unlock execute method instead
Response¶
null
isLocked¶
Determines whether the device is locked.
Deprecated
Please use the mobile: isLocked execute method instead
Response¶
boolean - true if the device is locked, otherwise false
getPerformanceData¶
Retrieves performance data about the given Android subsystem. The data is parsed from the output of
the dumpsys utility.
Deprecated
Please use the mobile: getPerformanceData
execute method instead
Parameters¶
Name |
Type | Description |
|---|---|---|
packageName |
string |
Name of the package identifier to fetch the data for |
dataType |
string |
Subsystem name to return the data for. Supported values can be retrieved using the getPerformanceDataTypes endpoint. |
Response¶
Array<Array<any>[]> - table formatted as an array of arrays, where the first subarray represents
column names, and the following subarrays represent data for those columns. The returned columns
and their data depend on the specified dataType.
For example, a response for the cpuinfo datatype could look as follows:
getPerformanceDataTypes¶
Retrieves supported performance data types, which can be used as the dataType argument for the
getPerformanceData endpoint.
Deprecated
Please use the mobile: getPerformanceDataTypes
execute method instead
Response¶
Array<string> - list of supported data types
fingerprint¶
Emulates authentication using a virtual fingerprint with the specified ID. Only supported on emulators running Android 6 (Marshmallow / API level 23) or later.
Virtual fingerprints should first be registered by opening the Android fingerprint registration settings and running this command with the ID that the fingerprint should be assigned to. Once registered, the command and ID can be used in fingerprint authentication prompts.
Deprecated
Please use the mobile: fingerprint execute method
instead
Parameters¶
| Name | Type | Description |
|---|---|---|
fingerprintId |
integer or string |
Identifier of a virtual fingerprint |
Response¶
null
getSystemBars¶
Retrieves properties of various bars in the system UI.
Deprecated
Please use the mobile: getSystemBars
execute method instead
Response¶
Record<string, Record<string, any>> - mapping of system bar names to their properties. The
following system bar names are included:
statusBarnavigationBar
All system bars include the following properties:
| Name | Type | Description |
|---|---|---|
visible |
boolean |
Whether the bar is visible |
x |
integer |
Left X coordinate of the bar. Could be 0 if the bar is not visible |
y |
integer |
Top Y coordinate of the bar. Could be 0 if the bar is not visible |
width |
integer |
Bar width. Could be 0 if the bar is not visible |
height |
integer |
Bar height. Could be 0 if the bar is not visible |
getDisplayDensity¶
Retrieves the density of the current display in DPI.
Deprecated
Please use the mobile: getDisplayDensity
execute method instead
Response¶
integer - the display density in DPI
openNotifications¶
Opens the notification tray on the device under test. Does nothing if the tray is already opened.
Deprecated
Please use the mobile: statusBar execute method
instead
Response¶
null
pressKeyCode¶
Emulates a single key press of the specified key. Creates a new KeyEvent
and passes it to UiController.injectKeyEvent()
under the hood.
Deprecated
Please use the mobile: pressKey execute method
instead
Parameters¶
| Name | Type | Description |
|---|---|---|
keycode |
integer |
Code of the key to press. Must match the numerical value for a supported KeyEvent KEYCODE_ constant. |
metastate |
integer |
One or more meta keys that should be simultaneously pressed. Must match the combined numerical value for one or more supported KeyEvent META_ constants. |
flags |
integer |
Flags to apply during the press. Must match the combined numerical value for one or more supported KeyEvent FLAG_ constants. |
Response¶
null
longPressKeyCode¶
Emulates a single long key press of the specified key. Creates a new KeyEvent
and passes it to UiController.injectKeyEvent()
under the hood.
Deprecated
Please use the mobile: pressKey execute method
instead
Parameters¶
| Name | Type | Description |
|---|---|---|
keycode |
integer |
Code of the key to press. Must match the numerical value for a supported KeyEvent KEYCODE_ constant. |
metastate |
integer |
One or more meta keys that should be simultaneously pressed. Must match the combined numerical value for one or more supported KeyEvent META_ constants. |
flags |
integer |
Flags to apply during the press. Must match the combined numerical value for one or more supported KeyEvent FLAG_ constants. |
Response¶
null
setValueImmediate¶
Sets the value of an element using adb.
Deprecated
Please use the setValue endpoint instead
Parameters¶
| Name | Type | Description |
|---|---|---|
text |
string |
Text to send to an element |
Response¶
null
replaceValue¶
Replaces the value of an element using adb.
Deprecated
Please use the setValue endpoint instead
Parameters¶
| Name | Type | Description |
|---|---|---|
text |
string |
Text to send to an element, replacing existing text |
Response¶
null