appium-android-driver 7.8.3 → 8.0.0

package/lib/commands/keyboard.js

@@ -1,24 +1,121 @@
-// @ts-check
+/* eslint-disable @typescript-eslint/no-unused-vars */
+import _ from 'lodash';
+import {errors} from 'appium/driver';
+import {requireArgs} from '../utils';
+import {UNICODE_IME, EMPTY_IME} from 'io.appium.settings';
 
-import {mixin} from './mixins';
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @returns {Promise<boolean>}
+ */
+export async function hideKeyboard() {
+  return await /** @type {import('appium-adb').ADB} */ (this.adb).hideKeyboard();
+}
+
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @returns {Promise<boolean>}
+ */
+export async function isKeyboardShown() {
+  const {isKeyboardShown} = await /** @type {import('appium-adb').ADB} */ (
+    this.adb
+  ).isSoftKeyboardPresent();
+  return isKeyboardShown;
+}
+
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @param {string|string[]} keys
+ * @returns {Promise<void>}
+ */
+export async function keys(keys) {
+  // Protocol sends an array; rethink approach
+  keys = _.isArray(keys) ? keys.join('') : keys;
+  await this.doSendKeys({
+    text: keys,
+    replace: false,
+  });
+}
 
 /**
- * @type {import('./mixins').KeyboardMixin & ThisType<import('../driver').AndroidDriver>}
- * @satisfies {import('@appium/types').ExternalDriver}
+ * @this {import('../driver').AndroidDriver}
+ * @param {import('./types').SendKeysOpts} params
+ * @returns {Promise<void>}
  */
-const KeyboardMixin = {
-  async hideKeyboard() {
-    return await /** @type {import('appium-adb').ADB} */ (this.adb).hideKeyboard();
-  },
+export async function doSendKeys(params) {
+  throw new errors.NotImplementedError('Not implemented');
+}
 
-  async isKeyboardShown() {
-    const {isKeyboardShown} = await /** @type {import('appium-adb').ADB} */ (
-      this.adb
-    ).isSoftKeyboardPresent();
-    return isKeyboardShown;
-  },
-};
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @param {string|number} keycode
+ * @param {number} [metastate]
+ * @returns {Promise<void>}
+ */
+export async function keyevent(keycode, metastate) {
+  // TODO deprecate keyevent; currently wd only implements keyevent
+  this.log.warn('keyevent will be deprecated use pressKeyCode');
+  return await this.pressKeyCode(keycode, metastate);
+}
 
-mixin(KeyboardMixin);
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @param {string|number} keycode
+ * @param {number} [metastate]
+ * @returns {Promise<void>}
+ */
+export async function pressKeyCode(keycode, metastate) {
+  throw new errors.NotImplementedError('Not implemented');
+}
+
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @param {string|number} keycode
+ * @param {number} [metastate]
+ * @returns {Promise<void>}
+ */
+export async function longPressKeyCode(keycode, metastate) {
+  throw new errors.NotImplementedError('Not implemented');
+}
+
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @param {import('./types').PerformEditorActionOpts} opts
+ * @returns {Promise<void>}
+ */
+export async function mobilePerformEditorAction(opts) {
+  const {action} = requireArgs('action', opts);
+  await this.settingsApp.performEditorAction(action);
+}
+
+// #region Internal Helpers
+
+/**
+ * @deprecated
+ * @this {import('../driver').AndroidDriver}
+ * @returns {Promise<string?>}
+ */
+export async function initUnicodeKeyboard() {
+  this.log.debug('Enabling Unicode keyboard support');
+
+  // get the default IME so we can return back to it later if we want
+  const defaultIME = await this.adb.defaultIME();
+
+  this.log.debug(`Unsetting previous IME ${defaultIME}`);
+  this.log.debug(`Setting IME to '${UNICODE_IME}'`);
+  await this.adb.enableIME(UNICODE_IME);
+  await this.adb.setIME(UNICODE_IME);
+  return defaultIME;
+}
+
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @returns {Promise<void>}
+ */
+export async function hideKeyboardCompletely() {
+  this.log.debug(`Hiding the on-screen keyboard by setting IME to '${EMPTY_IME}'`);
+  await this.adb.enableIME(EMPTY_IME);
+  await this.adb.setIME(EMPTY_IME);
+}
 
-export default KeyboardMixin;
+// #endregion

package/lib/commands/lock/exports.js

@@ -0,0 +1,139 @@
+import B from 'bluebird';
+import {
+  validateUnlockCapabilities,
+  FINGERPRINT_UNLOCK,
+  fastUnlock,
+  PIN_UNLOCK,
+  pinUnlock,
+  PIN_UNLOCK_KEY_EVENT,
+  pinUnlockWithKeyEvent,
+  PASSWORD_UNLOCK,
+  passwordUnlock,
+  PATTERN_UNLOCK,
+  patternUnlock,
+  fingerprintUnlock,
+  toCredentialType,
+  verifyUnlock,
+} from './helpers';
+import _ from 'lodash';
+
+
+/**
+ * @this {AndroidDriver}
+ * @param {import('../types').LockOpts} opts
+ * @returns {Promise<void>}
+ */
+export async function mobileLock(opts = {}) {
+  const {seconds} = opts;
+  return await this.lock(seconds);
+}
+
+/**
+ * @this {AndroidDriver}
+ * @param {number} [seconds]
+ * @returns {Promise<void>}
+ */
+export async function lock(seconds) {
+  await this.adb.lock();
+  if (Number.isNaN(seconds)) {
+    return;
+  }
+
+  const floatSeconds = parseFloat(String(seconds));
+  if (floatSeconds <= 0) {
+    return;
+  }
+  await B.delay(1000 * floatSeconds);
+  await this.unlock();
+}
+
+/**
+ * @this {AndroidDriver}
+ * @returns {Promise<boolean>}
+ */
+export async function isLocked() {
+  return await this.adb.isScreenLocked();
+}
+
+/**
+ * @this {AndroidDriver}
+ * @returns {Promise<void>}
+ */
+export async function unlock() {
+  await unlockWithOptions.bind(this)();
+}
+
+/**
+ * @this {AndroidDriver}
+ * @param {import('../types').UnlockOptions} [opts={}]
+ * @returns {Promise<void>}
+ */
+export async function mobileUnlock(opts = {}) {
+  const {key, type, strategy, timeoutMs} = opts;
+  if (!key && !type) {
+    await this.unlock();
+  } else {
+    await unlockWithOptions.bind(this)({
+      unlockKey: key,
+      unlockType: type,
+      unlockStrategy: strategy,
+      unlockSuccessTimeout: timeoutMs,
+    });
+  }
+}
+
+// #region Internal Helpers
+
+/**
+ * @this {AndroidDriver}
+ * @param {AndroidDriverCaps?} [caps=null]
+ * @returns {Promise<void>}
+ */
+export async function unlockWithOptions(caps = null) {
+  if (!(await this.adb.isScreenLocked())) {
+    this.log.info('Screen already unlocked, doing nothing');
+    return;
+  }
+
+  const capabilities = caps ?? this.opts;
+  this.log.debug('Screen is locked, trying to unlock');
+  if (!capabilities.unlockType && !capabilities.unlockKey) {
+    this.log.info(
+      `Neither 'unlockType' nor 'unlockKey' capability is provided. ` +
+        `Assuming the device is locked with a simple lock screen.`,
+    );
+    await this.adb.dismissKeyguard();
+    return;
+  }
+
+  const {unlockType, unlockKey, unlockStrategy, unlockSuccessTimeout} =
+    validateUnlockCapabilities(capabilities);
+  if (
+    unlockKey &&
+    unlockType !== FINGERPRINT_UNLOCK &&
+    (_.isNil(unlockStrategy) || _.toLower(unlockStrategy) === 'locksettings') &&
+    (await this.adb.isLockManagementSupported())
+  ) {
+    await fastUnlock.bind(this)({
+      credential: unlockKey,
+      credentialType: toCredentialType(/** @type {import('../types').UnlockType} */ (unlockType)),
+    });
+  } else {
+    const unlockMethod = {
+      [PIN_UNLOCK]: pinUnlock,
+      [PIN_UNLOCK_KEY_EVENT]: pinUnlockWithKeyEvent,
+      [PASSWORD_UNLOCK]: passwordUnlock,
+      [PATTERN_UNLOCK]: patternUnlock,
+      [FINGERPRINT_UNLOCK]: fingerprintUnlock,
+    }[unlockType];
+    await unlockMethod.bind(this)(capabilities);
+  }
+  await verifyUnlock.bind(this)(unlockSuccessTimeout);
+}
+
+// #endregion
+
+/**
+ * @typedef {import('@appium/types').Capabilities<import('../../constraints').AndroidDriverConstraints>} AndroidDriverCaps
+ * @typedef {import('../../driver').AndroidDriver} AndroidDriver
+ */

package/lib/commands/lock/helpers.js

@@ -0,0 +1,379 @@
+import {util} from '@appium/support';
+import {sleep, waitForCondition} from 'asyncbox';
+import _ from 'lodash';
+
+export const PIN_UNLOCK = 'pin';
+export const PIN_UNLOCK_KEY_EVENT = 'pinWithKeyEvent';
+export const PASSWORD_UNLOCK = 'password';
+export const PATTERN_UNLOCK = 'pattern';
+export const FINGERPRINT_UNLOCK = 'fingerprint';
+const UNLOCK_TYPES = /** @type {const}  */ ([
+  PIN_UNLOCK,
+  PIN_UNLOCK_KEY_EVENT,
+  PASSWORD_UNLOCK,
+  PATTERN_UNLOCK,
+  FINGERPRINT_UNLOCK,
+]);
+export const KEYCODE_NUMPAD_ENTER = 66;
+export const UNLOCK_WAIT_TIME = 100;
+export const INPUT_KEYS_WAIT_TIME = 100;
+const NUMBER_ZERO_KEYCODE = 7;
+
+/**
+ *
+ * @param {any} value
+ * @returns {value is string}
+ */
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value !== '';
+}
+
+/**
+ * Wait for the display to be unlocked.
+ * Some devices automatically accept typed 'pin' and 'password' code
+ * without pressing the Enter key. But some devices need it.
+ * This method waits a few seconds first for such automatic acceptance case.
+ * If the device is still locked, then this method will try to send
+ * the enter key code.
+ *
+ * @param {import('appium-adb').ADB} adb The instance of ADB
+ */
+async function waitForUnlock(adb) {
+  await sleep(UNLOCK_WAIT_TIME);
+  if (!(await adb.isScreenLocked())) {
+    return;
+  }
+
+  await adb.keyevent(KEYCODE_NUMPAD_ENTER);
+  await sleep(UNLOCK_WAIT_TIME);
+}
+
+/**
+ *
+ * @param {import('../types').UnlockType} unlockType
+ * @returns {string}
+ */
+export function toCredentialType(unlockType) {
+  const result = {
+    [PIN_UNLOCK]: 'pin',
+    [PIN_UNLOCK_KEY_EVENT]: 'pin',
+    [PASSWORD_UNLOCK]: 'password',
+    [PATTERN_UNLOCK]: 'pattern',
+  }[unlockType];
+  if (result) {
+    return result;
+  }
+  throw new Error(`Unlock type '${unlockType}' is not known`);
+}
+
+/**
+ * @template {AndroidDriverCaps} T
+ * @param {T} caps
+ * @returns {T}
+ */
+export function validateUnlockCapabilities(caps) {
+  const {unlockKey, unlockType} = caps ?? {};
+  if (!isNonEmptyString(unlockType)) {
+    throw new Error('A non-empty unlock key value must be provided');
+  }
+
+  if ([PIN_UNLOCK, PIN_UNLOCK_KEY_EVENT, FINGERPRINT_UNLOCK].includes(unlockType)) {
+    if (!/^[0-9]+$/.test(_.trim(unlockKey))) {
+      throw new Error(`Unlock key value '${unlockKey}' must only consist of digits`);
+    }
+  } else if (unlockType === PATTERN_UNLOCK) {
+    if (!/^[1-9]{2,9}$/.test(_.trim(unlockKey))) {
+      throw new Error(
+        `Unlock key value '${unlockKey}' must only include from two to nine digits in range 1..9`,
+      );
+    }
+    if (/([1-9]).*?\1/.test(_.trim(unlockKey))) {
+      throw new Error(
+        `Unlock key value '${unlockKey}' must define a valid pattern where repeats are not allowed`,
+      );
+    }
+  } else if (unlockType === PASSWORD_UNLOCK) {
+    // Dont trim password key, you can use blank spaces in your android password
+    // ¯\_(ツ)_/¯
+    if (!/.{4,}/g.test(String(unlockKey))) {
+      throw new Error(
+        `The minimum allowed length of unlock key value '${unlockKey}' is 4 characters`,
+      );
+    }
+  } else {
+    throw new Error(
+      `Invalid unlock type '${unlockType}'. ` +
+        `Only the following unlock types are supported: ${UNLOCK_TYPES}`,
+    );
+  }
+  return caps;
+}
+
+/**
+ * @this {AndroidDriver}
+ * @param {import('../types').FastUnlockOptions} opts
+ */
+export async function fastUnlock(opts) {
+  const {credential, credentialType} = opts;
+  this.log.info(`Unlocking the device via ADB using ${credentialType} credential '${credential}'`);
+  const wasLockEnabled = await this.adb.isLockEnabled();
+  if (wasLockEnabled) {
+    await this.adb.clearLockCredential(credential);
+    // not sure why, but the device's screen still remains locked
+    // if a preliminary wake up cycle has not been performed
+    await this.adb.cycleWakeUp();
+  } else {
+    this.log.info('No active lock has been detected. Proceeding to the keyguard dismissal');
+  }
+  try {
+    await this.adb.dismissKeyguard();
+  } finally {
+    if (wasLockEnabled) {
+      await this.adb.setLockCredential(credentialType, credential);
+    }
+  }
+}
+
+/**
+ *
+ * @param {string} key
+ * @returns {string}
+ */
+export function encodePassword(key) {
+  return `${key}`.replace(/\s/gi, '%s');
+}
+
+/**
+ *
+ * @param {string} key
+ * @returns {string[]}
+ */
+export function stringKeyToArr(key) {
+  return `${key}`.trim().replace(/\s+/g, '').split(/\s*/);
+}
+
+/**
+ * @this {AndroidDriver}
+ * @param {AndroidDriverCaps} capabilities
+ * @returns {Promise<void>}
+ */
+export async function fingerprintUnlock(capabilities) {
+  if ((await this.adb.getApiLevel()) < 23) {
+    throw new Error('Fingerprint unlock only works for Android 6+ emulators');
+  }
+  await this.adb.fingerprint(String(capabilities.unlockKey));
+  await sleep(UNLOCK_WAIT_TIME);
+}
+
+/**
+ * @this {AndroidDriver}
+ * @param {AndroidDriverCaps} capabilities
+ * @returns {Promise<void>}
+ */
+export async function pinUnlock(capabilities) {
+  this.log.info(`Trying to unlock device using pin ${capabilities.unlockKey}`);
+  await this.adb.dismissKeyguard();
+  const keys = stringKeyToArr(String(capabilities.unlockKey));
+  if ((await this.adb.getApiLevel()) >= 21) {
+    const els = await this.findElOrEls('id', 'com.android.systemui:id/digit_text', true);
+    if (_.isEmpty(els)) {
+      // fallback to pin with key event
+      return await pinUnlockWithKeyEvent.bind(this)(capabilities);
+    }
+    const pins = {};
+    for (const el of els) {
+      const text = await this.getAttribute('text', util.unwrapElement(el));
+      pins[text] = el;
+    }
+    for (const pin of keys) {
+      const el = pins[pin];
+      await this.click(util.unwrapElement(el));
+    }
+  } else {
+    for (const pin of keys) {
+      const el = await this.findElOrEls('id', `com.android.keyguard:id/key${pin}`, false);
+      if (el === null) {
+        // fallback to pin with key event
+        return await pinUnlockWithKeyEvent.bind(this)(capabilities);
+      }
+      await this.click(util.unwrapElement(el));
+    }
+  }
+  await waitForUnlock(this.adb);
+}
+
+/**
+ * @this {AndroidDriver}
+ * @param {AndroidDriverCaps} capabilities
+ * @returns {Promise<void>}
+ */
+export async function pinUnlockWithKeyEvent(capabilities) {
+  this.log.info(`Trying to unlock device using pin with keycode ${capabilities.unlockKey}`);
+  await this.adb.dismissKeyguard();
+  const keys = stringKeyToArr(String(capabilities.unlockKey));
+
+  // Some device does not have system key ids like 'com.android.keyguard:id/key'
+  // Then, sending keyevents are more reliable to unlock the screen.
+  for (const pin of keys) {
+    // 'pin' is number (0-9) in string.
+    // Number '0' is keycode '7'. number '9' is keycode '16'.
+    await this.adb.shell(['input', 'keyevent', String(parseInt(pin, 10) + NUMBER_ZERO_KEYCODE)]);
+  }
+  await waitForUnlock(this.adb);
+}
+
+/**
+ * @this {AndroidDriver}
+ * @param {AndroidDriverCaps} capabilities
+ * @returns {Promise<void>}
+ */
+export async function passwordUnlock(capabilities) {
+  const {unlockKey} = capabilities;
+  this.log.info(`Trying to unlock device using password ${unlockKey}`);
+  await this.adb.dismissKeyguard();
+  // Replace blank spaces with %s
+  const key = encodePassword(String(unlockKey));
+  // Why adb ? It was less flaky
+  await this.adb.shell(['input', 'text', key]);
+  // Why sleeps ? Avoid some flakyness waiting for the input to receive the keys
+  await sleep(INPUT_KEYS_WAIT_TIME);
+  await this.adb.shell(['input', 'keyevent', String(KEYCODE_NUMPAD_ENTER)]);
+  // Waits a bit for the device to be unlocked
+  await waitForUnlock(this.adb);
+}
+
+/**
+ *
+ * @param {number} key
+ * @param {import('@appium/types').Position} initPos
+ * @param {number} piece
+ * @returns {import('@appium/types').Position}
+ */
+export function getPatternKeyPosition(key, initPos, piece) {
+  /*
+  How the math works:
+  We have 9 buttons divided in 3 columns and 3 rows inside the lockPatternView,
+  every button has a position on the screen corresponding to the lockPatternView since
+  it is the parent view right at the middle of each column or row.
+  */
+  const cols = 3;
+  const pins = 9;
+  const xPos = (key, x, piece) => Math.round(x + (key % cols || cols) * piece - piece / 2);
+  const yPos = (key, y, piece) =>
+    Math.round(y + (Math.ceil((key % pins || pins) / cols) * piece - piece / 2));
+  return {
+    x: xPos(key, initPos.x, piece),
+    y: yPos(key, initPos.y, piece),
+  };
+}
+
+/**
+ * @param {string[]|number[]} keys
+ * @param {import('@appium/types').Position} initPos
+ * @param {number} piece
+ * @returns {import('../types').TouchAction[]}
+ */
+export function getPatternActions(keys, initPos, piece) {
+  /** @type {import('../types').TouchAction[]} */
+  const actions = [];
+  /** @type {number[]} */
+  const intKeys = keys.map((key) => (_.isString(key) ? _.parseInt(key) : key));
+  /** @type {import('@appium/types').Position|undefined} */
+  let lastPos;
+  for (const key of intKeys) {
+    const keyPos = getPatternKeyPosition(key, initPos, piece);
+    if (!lastPos) {
+      actions.push({action: 'press', options: {element: undefined, x: keyPos.x, y: keyPos.y}});
+      lastPos = keyPos;
+      continue;
+    }
+    const moveTo = {x: 0, y: 0};
+    const diffX = keyPos.x - lastPos.x;
+    if (diffX > 0) {
+      moveTo.x = piece;
+      if (Math.abs(diffX) > piece) {
+        moveTo.x += piece;
+      }
+    } else if (diffX < 0) {
+      moveTo.x = -1 * piece;
+      if (Math.abs(diffX) > piece) {
+        moveTo.x -= piece;
+      }
+    }
+    const diffY = keyPos.y - lastPos.y;
+    if (diffY > 0) {
+      moveTo.y = piece;
+      if (Math.abs(diffY) > piece) {
+        moveTo.y += piece;
+      }
+    } else if (diffY < 0) {
+      moveTo.y = -1 * piece;
+      if (Math.abs(diffY) > piece) {
+        moveTo.y -= piece;
+      }
+    }
+    actions.push({
+      action: 'moveTo',
+      // @ts-ignore lastPos should be defined
+      options: {element: undefined, x: moveTo.x + lastPos.x, y: moveTo.y + lastPos.y},
+    });
+    lastPos = keyPos;
+  }
+  actions.push({action: 'release'});
+  return actions;
+}
+
+/**
+ * @this {AndroidDriver}
+ * @param {number?} [timeoutMs=null]
+ */
+export async function verifyUnlock(timeoutMs = null) {
+  try {
+    await waitForCondition(async () => !(await this.adb.isScreenLocked()), {
+      waitMs: timeoutMs ?? 2000,
+      intervalMs: 500,
+    });
+  } catch (ign) {
+    throw new Error('The device has failed to be unlocked');
+  }
+  this.log.info('The device has been successfully unlocked');
+}
+
+/**
+ * @this {AndroidDriver}
+ * @param {AndroidDriverCaps} capabilities
+ */
+export async function patternUnlock(capabilities) {
+  const {unlockKey} = capabilities;
+  this.log.info(`Trying to unlock device using pattern ${unlockKey}`);
+  await this.adb.dismissKeyguard();
+  const keys = stringKeyToArr(String(unlockKey));
+  /* We set the device pattern buttons as number of a regular phone
+    *  | • • • |     | 1 2 3 |
+    *  | • • • | --> | 4 5 6 |
+    *  | • • • |     | 7 8 9 |
+
+  The pattern view buttons are not seeing by the uiautomator since they are
+  included inside a FrameLayout, so we are going to try clicking on the buttons
+  using the parent view bounds and math.
+  */
+  const apiLevel = await this.adb.getApiLevel();
+  const el = await this.findElOrEls(
+    'id',
+    `com.android.${apiLevel >= 21 ? 'systemui' : 'keyguard'}:id/lockPatternView`,
+    false,
+  );
+  const initPos = await this.getLocation(util.unwrapElement(el));
+  const size = await this.getSize(util.unwrapElement(el));
+  // Get actions to perform
+  const actions = getPatternActions(keys, initPos, size.width / 3);
+  // Perform gesture
+  await this.performTouch(actions);
+  // Waits a bit for the device to be unlocked
+  await sleep(UNLOCK_WAIT_TIME);
+}
+
+/**
+ * @typedef {import('@appium/types').Capabilities<import('../../constraints').AndroidDriverConstraints>} AndroidDriverCaps
+ * @typedef {import('../../driver').AndroidDriver} AndroidDriver
+ */