Skip to content

Commit d0d24c4

Browse files
mykola-mokhnachmykola-mokhnach
authored
feat: Expose several mobile commands that are available in android-driver (#881)
1 parent 6f742d2 commit d0d24c4

File tree

3 files changed

+363
-5
lines changed

3 files changed

+363
-5
lines changed

‎README.md

+333-2
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ The Espresso package consists of two main parts:
2121

2222
## Comparison with UiAutomator2
2323

24-
The key difference between [UiAutomator2 Driver](https://github.com/appium/appium-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](https://developer.android.com/reference/android/support/test/espresso/IdlingResource) which blocks the framework from running commands until the UI thread is free. There is limited support to automate out of app areas using the mobile command [uiautomator](https://github.com/appium/appium-espresso-driver/blob/b2b0883ab088a131a47d88f6aeddd8ff5882087d/lib/commands/general.js#L188)
24+
The key difference between [UiAutomator2 Driver](https://github.com/appium/appium-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](https://developer.android.com/reference/android/support/test/espresso/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](#mobile-uiautomator) command.
2525

2626

2727
## Requirements
@@ -1127,7 +1127,6 @@ List of fully qualified class names of currently registered idling resources or
11271127
- Wait for the UI thread to become idle, in other words, wait for the APP to become [idle](https://developer.android.com/reference/androidx/test/espresso/UiController#loopMainThreadUntilIdle()).
11281128
- 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.
11291129

1130-
11311130
### mobile: unlock
11321131

11331132
Unlocks the device if it is locked. Noop if the device's screen is not locked.
@@ -1141,6 +1140,24 @@ type | string | yes | The unlock type. See the documentation on [appium:unlockTy
11411140
strategy | string | no | Unlock strategy. See the documentation on [appium:unlockStrategy](#device-locking) capability for more details | uiautomator
11421141
timeoutMs | number | no | Unlock timeout. See the documentation on [appium:unlockSuccessTimeout](#device-locking) capability for more details | 5000
11431142

1143+
### mobile: isLocked
1144+
1145+
Determine whether the device is locked.
1146+
1147+
#### Returned Result
1148+
1149+
Either `true` or `false`
1150+
1151+
### mobile: lock
1152+
1153+
Lock the device (and optionally unlock it after a certain amount of time). Only simple (e.g. without a password) locks are supported.
1154+
1155+
#### Arguments
1156+
1157+
Name | Type | Required | Description | Example
1158+
--- | --- | --- | --- | ---
1159+
seconds | number|string | no | The number of seconds after which to unlock the device. Set to `0` or leave it empty to require manual unlock (e.g. do not block and automatically unlock afterwards). | 5
1160+
11441161
### mobile: startMediaProjectionRecording
11451162

11461163
Starts a new recording of the device activity using [Media Projection](https://developer.android.com/reference/android/media/projection/MediaProjection) 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.
@@ -1204,6 +1221,320 @@ Checks if the system on-screen keyboard is visible.
12041221

12051222
`true` if the keyboard is visible
12061223

1224+
### mobile: pressKey
1225+
1226+
Emulates single key press on the key with the given code. Available since driver version 2.23
1227+
1228+
#### Arguments
1229+
1230+
Name | Type | Required | Description | Example
1231+
--- | --- | --- | --- | ---
1232+
keycode | number | yes | A valid Android key code. See [KeyEvent documentation](https://developer.android.com/reference/android/view/KeyEvent) for the list of available key codes | 0x00000099 (which is KEYCODE_NUMPAD_9)
1233+
metastate | number | no | An integer in which each bit set to 1 represents a pressed meta key. See [KeyEvent documentation](https://developer.android.com/reference/android/view/KeyEvent) for more details. | 0x00000010 (which is META_ALT_LEFT_ON)
1234+
flags | number | no | Flags for the particular key event. See [KeyEvent documentation](https://developer.android.com/reference/android/view/KeyEvent) for more details. | 0x00000001 (which is FLAG_WOKE_HERE)
1235+
isLongPress | boolean | no | Whether to emulate long key press. `false` by default. | true
1236+
1237+
### mobile: getConnectivity
1238+
1239+
Returns connectivity states for different services
1240+
1241+
#### Arguments
1242+
1243+
Name | Type | Required | Description | Example
1244+
--- | --- | --- | --- | ---
1245+
services | string or string[] | no | One or more services to get the connectivity for. Supported service names are: wifi, data, airplaneMode. If no service names are provided then all supported names are assumed by default. | [wifi, data]
1246+
1247+
#### Returned Result
1248+
1249+
A map is returned containing the following possible items (depending on which values have been passed to `services` argument):
1250+
1251+
Name | Type | Description
1252+
--- | --- | ---
1253+
wifi | boolean | True if wifi is enabled
1254+
data | boolean | True if mobile data connection is enabled
1255+
airplaneMode | boolean | True if Airplane Mode is enabled
1256+
1257+
### mobile: setConnectivity
1258+
1259+
Set the connectivity state for different services. At least one valid service name must be provided in arguments.
1260+
Missing values tell the driver to not change the corresponding service's state.
1261+
1262+
> **Note**
1263+
>
1264+
> Switching Wi-Fi and mobile data states reliably work on emulators for all Android versions.
1265+
> Real devices support proper state switching only since Android 11.
1266+
1267+
> **Note**
1268+
>
1269+
> Espresso REST server app is running on the device under test and might be terminated/disconnected by Android
1270+
> thus failing the driver session as a result of using this API. The only way to restore the session would be to quit it
1271+
> after the network state is changed and then reopen it with `noReset` capability being set to `true` when the connectivity
1272+
> is restored.
1273+
1274+
#### Arguments
1275+
1276+
Name | Type | Required | Description | Example
1277+
--- | --- | --- | --- | ---
1278+
wifi | booolean | no | Either to enable or disable Wi-Fi. | false
1279+
data | booolean | no | Either to enable or disable mobile data. | false
1280+
airplaneMode | booolean | no | Either to enable or disable Airplane Mode. | false
1281+
1282+
### mobile: getAppStrings
1283+
1284+
Retrieves string resources for the given app language. An error is thrown if strings cannot be fetched or no strings exist
1285+
for the given language abbreviation. Available since driver version 2.23
1286+
1287+
#### Arguments
1288+
1289+
Name | Type | Required | Description | Example
1290+
--- | --- | --- | --- | ---
1291+
language | string | no | The language abbreviation to fetch app strings mapping for. If no language is provided then strings for the default language on the device under test would be returned | fr
1292+
1293+
#### Returned Result
1294+
1295+
App strings map, where keys are resource identifiers.
1296+
1297+
### mobile: backgroundApp
1298+
1299+
Puts the app to the background and waits the given number of seconds. Then restores the app
1300+
if necessary. The call is blocking. Available since driver version 2.23
1301+
1302+
#### Arguments
1303+
1304+
Name | Type | Required | Description | Example
1305+
--- | --- | --- | --- | ---
1306+
seconds | number | no | The amount of seconds to wait between putting the app to background and restoring it. Any negative value means to not restore the app after putting it to background (the default behavior). | 5
1307+
1308+
### mobile: getCurrentActivity
1309+
1310+
Returns the name of the currently focused app activity. Available since driver version 2.23
1311+
1312+
#### Returned Result
1313+
1314+
The activity class name. Could be `null`
1315+
1316+
### mobile: getCurrentPackage
1317+
1318+
Returns the name of the currently focused app package identifier. Available since driver version 2.23
1319+
1320+
#### Returned Result
1321+
1322+
The package class name. Could be `null`
1323+
1324+
### mobile: getDisplayDensity
1325+
1326+
Returns the display density value measured in DPI. Available since driver version 2.23
1327+
1328+
#### Returned Result
1329+
1330+
The actual DPI value as integer number
1331+
1332+
### mobile: getSystemBars
1333+
1334+
Returns properties of various system bars. Available since driver version 2.23
1335+
1336+
#### Returned Result
1337+
1338+
A dictionary whose entries are:
1339+
- `statusBar`
1340+
- `navigationBar`
1341+
1342+
Values are dictionaries with the following properties:
1343+
- `visible`: Whether the bar is visible (equals to `false` if the bar is not present in the system info output)
1344+
- `x`: Bar x coordinate (might be zero if the bar is not present in the system info output)
1345+
- `y`: Bar y coordinate (might be zero if the bar is not present in the system info output)
1346+
- `width`: Bar width (might be zero if the bar is not present in the system info output)
1347+
- `height`: Bar height (might be zero if the bar is not present in the system info output)
1348+
1349+
### mobile: fingerprint
1350+
1351+
Emulate [fingerprint](https://learn.microsoft.com/en-us/xamarin/android/platform/fingerprint-authentication/enrolling-fingerprint) on Android Emulator. Only works on API 23+. Available since driver version 2.23
1352+
1353+
#### Arguments
1354+
1355+
Name | Type | Required | Description | Example
1356+
--- | --- | --- | --- | ---
1357+
fingerprintId | number | yes | The value is the id for the finger that was "scanned". It is a unique integer that you assign for each virtual fingerprint. When the app is running you can run this same command each time the emulator prompts you for a fingerprint, you can run the adb command and pass it the fingerprintId to simulate the fingerprint scan. | 1
1358+
1359+
### mobile: sendSms
1360+
1361+
Emulate sending an SMS to the given phone number. Only works on emulators. Available since driver version 2.23
1362+
1363+
#### Arguments
1364+
1365+
Name | Type | Required | Description | Example
1366+
--- | --- | --- | --- | ---
1367+
phoneNumber | string | yes | The phone number to send SMS to | 0123456789
1368+
message | string | yes | The SMS message payload | Hello
1369+
1370+
### mobile: gsmCall
1371+
1372+
Emulate a GSM call to the given phone number. Only works on emulators. Available since driver version 2.23
1373+
1374+
#### Arguments
1375+
1376+
Name | Type | Required | Description | Example
1377+
--- | --- | --- | --- | ---
1378+
phoneNumber | string | yes | The phone number to call to | 0123456789
1379+
action | call or accept or cancel or hold | yes | One of possible actions to take | accept
1380+
1381+
### mobile: gsmSignal
1382+
1383+
Emulate GSM signal strength change event. Only works on emulators. Available since driver version 2.23
1384+
1385+
#### Arguments
1386+
1387+
Name | Type | Required | Description | Example
1388+
--- | --- | --- | --- | ---
1389+
strength | 0 or 1 or 2 or 3 or 4 | yes | One of possible signal strength values, where 4 is the best signal. | 3
1390+
1391+
### mobile: gsmVoice
1392+
1393+
Emulate GSM voice state change event. Only works on emulators. Available since driver version 2.23
1394+
1395+
#### Arguments
1396+
1397+
Name | Type | Required | Description | Example
1398+
--- | --- | --- | --- | ---
1399+
state | on or off or denied or searching or roaming or home or unregistered | yes | Voice state | off
1400+
1401+
### mobile: powerAC
1402+
1403+
Emulate AC power state change. Only works on emulators. Available since driver version 2.23
1404+
1405+
#### Arguments
1406+
1407+
Name | Type | Required | Description | Example
1408+
--- | --- | --- | --- | ---
1409+
state | on or off | yes | AC Power state | off
1410+
1411+
### mobile: powerCapacity
1412+
1413+
Emulate power capacity change. Only works on emulators. Available since driver version 2.23
1414+
1415+
#### Arguments
1416+
1417+
Name | Type | Required | Description | Example
1418+
--- | --- | --- | --- | ---
1419+
percent | 0 to 100 | yes | Percentage value in range [0, 100] | 50
1420+
1421+
### mobile: networkSpeed
1422+
1423+
Emulate different network connection speed modes. Only works on emulators. Available since driver version 2.23
1424+
1425+
#### Arguments
1426+
1427+
Name | Type | Required | Description | Example
1428+
--- | --- | --- | --- | ---
1429+
speed | gsm or scsd or gprs or edge or umts or hsdpa or lte or evdo or full | yes | Mobile network speed mode name | edge
1430+
1431+
### mobile: replaceElementValue
1432+
1433+
Sends a text to the given element by replacing its previous content. Available since driver version 2.23
1434+
1435+
#### Arguments
1436+
1437+
Name | Type | Required | Description | Example
1438+
--- | --- | --- | --- | ---
1439+
elementId | string | yes | Hexadecimal identifier of the destination text input | 123456-3456-3435-3453453
1440+
text | string | yes | The text to enter. It could also contain Unicode characters. If the text ends with `\\n` (the backslash must be escaped, so the char is NOT translated into `0x0A`) then the Enter key press is going to be emulated after it is entered (the `\\n` substring itself will be cut off from the typed text). | yolo
1441+
1442+
### mobile: toggleGps
1443+
1444+
Switches GPS setting state. This API only works reliably since Android 12 (API 31). Available since driver version 2.23
1445+
1446+
### mobile: isGpsEnabled
1447+
1448+
Returns `true` if GPS is enabled on the device under test. Available since driver version 2.23
1449+
1450+
### mobile: getPerformanceDataTypes
1451+
1452+
Fetches the list of supported perfomance data types that could be used as `dataType` argument value to [mobile: getPerformanceData](#mobile-getperformancedata) extension. Available since driver version 2.23
1453+
1454+
#### Returned Result
1455+
1456+
List of strings, where each item is data type name.
1457+
1458+
### mobile: getPerformanceData
1459+
1460+
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
1461+
1462+
#### Arguments
1463+
1464+
Name | Type | Required | Description | Example
1465+
--- | --- | --- | --- | ---
1466+
packageName | string | yes | The name of the package identifier to fetch the data for | com.myapp
1467+
dataType | string | yes | One of supported subsystem names. The full list of supported values is returned by [mobile: getPerformanceDataTypes](#mobile-getperformancedatatypes) extension. | batteryinfo or cpuinfo or memoryinfo or networkinfo
1468+
1469+
#### Returned Result
1470+
1471+
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.
1472+
Example output for different data types:
1473+
1474+
- batteryinfo:
1475+
```
1476+
[
1477+
[power],
1478+
[23]
1479+
]
1480+
```
1481+
- memoryinfo:
1482+
```
1483+
[
1484+
[totalPrivateDirty, nativePrivateDirty, dalvikPrivateDirty, eglPrivateDirty, glPrivateDirty, totalPss, nativePss, dalvikPss, eglPss, glPss, nativeHeapAllocatedSize, nativeHeapSize],
1485+
[18360, 8296, 6132, null, null, 42588, 8406, 7024, null, null, 26519, 10344]
1486+
]
1487+
```
1488+
- networkinfo:
1489+
```
1490+
// emulator
1491+
[
1492+
[bucketStart, activeTime, rxBytes, rxPackets, txBytes, txPackets, operations, bucketDuration],
1493+
[1478091600000, null, 1099075, 610947, 928, 114362, 769, 0, 3600000],
1494+
[1478095200000, null, 1306300, 405997, 509, 46359, 370, 0, 3600000]
1495+
]
1496+
// real devices
1497+
[
1498+
[st, activeTime, rb, rp, tb, tp, op, bucketDuration],
1499+
[1478088000, null, null, 32115296, 34291, 2956805, 25705, 0, 3600],
1500+
[1478091600, null, null, 2714683, 11821, 1420564, 12650, 0, 3600],
1501+
[1478095200, null, null, 10079213, 19962, 2487705, 20015, 0, 3600],
1502+
[1478098800, null, null, 4444433, 10227, 1430356, 10493, 0, 3600]
1503+
]
1504+
```
1505+
- cpuinfo:
1506+
```
1507+
[
1508+
[user, kernel],
1509+
[0.9, 1.3]
1510+
]
1511+
```
1512+
1513+
### mobile: statusBar
1514+
1515+
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
1516+
1517+
#### Arguments
1518+
1519+
Name | Type | Required | Description | Example
1520+
--- | --- | --- | --- | ---
1521+
command | string | yes | One of [supported status bar commands](#status-bar-commands). | expandNotifications
1522+
component | string | no | The name of the tile component. It is only required for (add\|remove\|click)Tile commands. | com.package.name/.service.QuickSettingsTileComponent
1523+
1524+
#### Status Bar Commands
1525+
1526+
- expandNotifications: Open the notifications panel.
1527+
- expandSettings: Open the notifications panel and expand quick settings if present.
1528+
- collapse: Collapse the notifications and settings panel.
1529+
- addTile: Add a TileService of the specified component.
1530+
- removeTile: Remove a TileService of the specified component.
1531+
- clickTile: Click on a TileService of the specified component.
1532+
- getStatusIcons: Returns the list of status bar icons and the order they appear in. Each list item is separated with a new line character.
1533+
1534+
#### Returned Result
1535+
1536+
The actual downstream command output. It depends on the selected command and might be empty.
1537+
12071538

12081539
## Backdoor Extension Usage
12091540

0 commit comments

Comments
 (0)