feat: Improve the documentation on unlock (#979)

mykola-mokhnach · web-flow · commit 15ae78b3dbe6 · 2024-02-08T08:33:20.000+01:00
diff --git a/README.md b/README.md
@@ -154,11 +154,10 @@ appium:noSign | Set it to `true` in order to skip application signing. By defaul
 
 Capability Name | Description
 --- | ---
-appium:skipUnlock | Whether to skip the check for lock screen presence (`true`). By default Espresso driver tries to detect if the device's screen is locked before starting the test and to unlock that (which sometimes might be unstable). Note, that this operation takes some time, so it is highly recommended to set this capability to `false` and disable screen locking on devices under test.
-appium:unlockType | Set one of the possible types of Android lock screens to unlock. Read the [Unlock tutorial](https://github.com/appium/appium-android-driver/blob/master/docs/UNLOCK.md) for more details.
-appium:unlockKey | Allows to set an unlock key. Read the [Unlock tutorial](https://github.com/appium/appium-android-driver/blob/master/docs/UNLOCK.md) for more details.
-appium:unlockStrategy | Either 'locksettings' (default) or 'uiautomator'. Setting it to 'uiautomator' will enforce the driver to avoid using special ADB shortcuts in order to speed up the unlock procedure.
-appium:unlockSuccessTimeout | Maximum number of milliseconds to wait until the device is unlocked. `2000` ms by default
+appium:skipUnlock | Whether to skip the check for lock screen presence (`true`). By default Espresso driver tries to detect if the device's screen is locked before starting the test and to unlock that (which sometimes might be unstable). Note, that this operation takes some time, so it is recommended to set this capability to `false` and disable screen locking on devices under test. Read the [Unlock tutorial](./docs/unlock/main.md) for more details.
+appium:unlockType | Set one of the possible types of Android lock screens to unlock. Read the [Unlock tutorial](./docs/unlock/main.md) for more details.
+appium:unlockKey | Allows to set an unlock key. Read the [Unlock tutorial](./docs/unlock/main.md) for more details.
+appium:unlockSuccessTimeout | Maximum number of milliseconds to wait until the device is unlocked. `2000` ms by default. Read the [Unlock tutorial](./docs/unlock/main.md) for more details.
 
 ### Web Context
 
@@ -1190,7 +1189,6 @@ Name | Type | Required | Description | Example
 --- | --- | --- | --- | ---
 key | string | yes | The unlock key. See the documentation on [appium:unlockKey](#device-locking) capability for more details | 12345
 type | string | yes | The unlock type. See the documentation on [appium:unlockType](#device-locking) capability for more details | password
-strategy | string | no | Unlock strategy. See the documentation on [appium:unlockStrategy](#device-locking) capability for more details | uiautomator
 timeoutMs | number | no | Unlock timeout. See the documentation on [appium:unlockSuccessTimeout](#device-locking) capability for more details | 5000
 
 ### mobile: isLocked
diff --git a/docs/unlock/main.md b/docs/unlock/main.md
@@ -0,0 +1,77 @@
+# Unlock
+
+Espresso driver allows dealing with the Android lock screen using various APIs.
+This article describes the available APIs and their options.
+
+## Unlock On Session Startup
+
+Espresso driver provides the following [capabilities](../../README.md#device-locking) to deal
+with the system lock screen:
+
+- appium:unlockSuccessTimeout
+- appium:skipUnlock
+- appium:unlockType
+- appium:unlockKey
+
+These capabilities could be used to unlock the device under test during the driver session initialization
+as well as deal with different lock screen types.
+
+### appium:unlockSuccessTimeout
+
+Maximum number of milliseconds to wait until the device is unlocked. `2000` ms by default
+
+### appium:skipUnlock
+
+The `appium:skipUnlock` capability is enabled by default and makes the driver to detect and handle the lock screen
+upon session startup _if it is present_. If the lock screen cannot be detected upon session startup then nothing will be
+done. By default, it is assumed the device has a "simple" lock screen, which could be removed by waking up the device.
+In case the device has a different type of the lock screen configured in its settings then the information about it
+must be provided in the below capability values.
+
+### appium:unlockType and appium:unlockKey
+
+This capability supports the following possible values:
+
+#### pin
+
+Assumes the device is protected with a PIN code. Expects the `appium:unlockKey` to contain a valid pin consisting
+of digits in range 0-9, for example `1111`.
+
+#### password
+
+Assumes the device is protected with a password. Expects the `appium:unlockKey` to contain a valid password consisting
+of latin characters, for example `abcd1234`.
+
+#### pattern
+
+Assumes the device is protected with a secret pattern. Check the example below for more details on the `appium:unlockKey`
+value for this particular unlock type.
+
+##### Example
+
+Let say you have a device that is locked with a pattern similar to the one on the image below,
+and you want to run a test over that device.
+
+<img src="./screen1.png" />
+
+We treat the pattern pins similarly to numbers on a digital phone dial. So, in this case the *unlockKey* is `729854163`
+
+<img src="./screen2.png" />
+
+and capabilities are:
+
+```json
+{
+  "appium:unlockType": "pattern",
+  "appium:unlockKey": "729854163"
+}
+```
+
+## Mid-Session Unlock
+
+There is also a possibility to interact with the device's lock screen while the test session is running.
+Use the following mobile extensions for this purpose:
+
+- [mobile: lock](../../README.md#mobile-lock)
+- [mobile: unlock](../../README.md#mobile-unlock)
+- [mobile: isLocked](../../README.md#mobile-islocked)
diff --git a/docs/unlock/screen1.png b/docs/unlock/screen1.png
diff --git a/docs/unlock/screen2.png b/docs/unlock/screen2.png
diff --git a/lib/commands/actions.js b/lib/commands/actions.js
@@ -0,0 +1,18 @@
+/**
+ * @this {import('../driver').EspressoDriver}
+ * @param {import('@appium/types').StringRecord[]} actions
+ * @returns {Promise<void>}
+ */
+export async function performActions(actions) {
+  this.log.debug(`Received the following W3C actions: ${JSON.stringify(actions, null, '  ')}`);
+  // This is needed because Selenium API uses MOUSE as the default pointer type
+  const preprocessedActions = actions.map((action) =>
+    Object.assign(
+      {},
+      action,
+      action.type === 'pointer' ? {parameters: {pointerType: 'touch'}} : {}
+    )
+  );
+  this.log.debug(`Preprocessed actions: ${JSON.stringify(preprocessedActions, null, '  ')}`);
+  await this.espresso.jwproxy.command('/actions', 'POST', {actions: preprocessedActions});
+}
diff --git a/lib/driver.ts b/lib/driver.ts
@@ -22,6 +22,7 @@ import * as miscCmds from './commands/misc';
 import * as servicesCmds from './commands/services';
 import * as screenshotCmds from './commands/screenshot';
 import * as idlingResourcesCmds from './commands/idling-resources';
+import * as actionsCmds from './commands/actions';
 import { DEFAULT_ADB_PORT } from 'appium-adb';
 import { AndroidDriver, utils } from 'appium-android-driver';
 import { SETTINGS_HELPER_ID } from 'io.appium.settings';
@@ -697,6 +698,8 @@ export class EspressoDriver extends AndroidDriver implements ExternalDriver<
     return !this.opts.app && this.helpers.isPackageOrBundle(this.opts.appPackage!);
   }
 
+  performActions = actionsCmds.performActions;
+
   executeMobile = executeCmds.executeMobile;
 
   launchApp = appManagementCmds.launchApp;
diff --git a/package.json b/package.json
@@ -73,7 +73,7 @@
   ],
   "dependencies": {
     "appium-adb": "^12.0.0",
-    "appium-android-driver": "^8.1.6",
+    "appium-android-driver": "^8.3.0",
     "asyncbox": "^3.0.0",
     "bluebird": "^3.5.0",
     "io.appium.settings": "^5.7.2",
