appium-uiautomator2-driver 2.42.2 → 2.43.0

package/lib/commands/element.js

@@ -1,241 +1,262 @@
-// @ts-check
-
 import B from 'bluebird';
 import _ from 'lodash';
-import {util} from 'appium/support';
-import {PROTOCOLS, W3C_ELEMENT_KEY} from 'appium/driver';
-import {requireArgs} from '../utils';
-import {mixin} from './mixins';
+import {PROTOCOLS} from 'appium/driver';
+import {utils} from 'appium-android-driver';
 
 /**
- * @param {any} s
- * @returns {boolean}
+ * @this {AndroidUiautomator2Driver}
+ * @returns {Promise<import('@appium/types').Element>}
  */
-function toBool(s) {
-  return _.isString(s) ? s.toLowerCase() === 'true' : !!s;
+export async function active() {
+  return /** @type {import('@appium/types').Element} */ (
+    await this.uiautomator2.jwproxy.command(
+      '/element/active',
+      'GET'
+    )
+  );
 }
 
 /**
- * @type {import('./mixins').UIA2ElementMixin}
- * @satisfies {import('@appium/types').ExternalDriver}
+ * @this {AndroidUiautomator2Driver}
+ * @param {string} attribute
+ * @param {string} elementId
+ * @returns {Promise<string?>}
  */
-const ElementMixin = {
-  async active() {
-    return /** @type {import('@appium/types').Element} */ (
-      await this.uiautomator2.jwproxy.command(
-        '/element/active',
-        'GET'
-      )
-    );
-  },
-  async getAttribute(attribute, elementId) {
-    return String(
-      await this.uiautomator2.jwproxy.command(
-        `/element/${elementId}/attribute/${attribute}`,
-        'GET',
-        {}
-      )
-    );
-  },
-  async elementDisplayed(elementId) {
-    return toBool(await this.getAttribute('displayed', elementId));
-  },
-  async elementEnabled(elementId) {
-    return toBool(await this.getAttribute('enabled', elementId));
-  },
-  async elementSelected(elementId) {
-    return toBool(await this.getAttribute('selected', elementId));
-  },
-  async getName(elementId) {
-    return /** @type {string} */ (
-      await this.uiautomator2.jwproxy.command(
-        `/element/${elementId}/name`,
-        'GET',
-        {}
-      )
-    );
-  },
-  async getLocation(elementId) {
-    return /** @type {import('@appium/types').Position} */ (
-      await this.uiautomator2.jwproxy.command(
-        `/element/${elementId}/location`,
-        'GET',
-        {}
-      )
-    );
-  },
-  async getSize(elementId) {
-    return /** @type {import('@appium/types').Size} */ (
-      await this.uiautomator2.jwproxy.command(
-        `/element/${elementId}/size`,
-        'GET',
-        {}
-      )
-    );
-  },
-  async touchLongClick(element, x, y, duration) {
-    let params = {element, x, y, duration};
-    await this.uiautomator2.jwproxy.command(
-      `/touch/longclick`,
-      'POST',
-      {params}
-    );
-  },
-  async touchDown(element, x, y) {
-    let params = {element, x, y};
-    await this.uiautomator2.jwproxy.command(
-      `/touch/down`,
-      'POST',
-      {params}
-    );
-  },
-  async touchUp(element, x, y) {
-    let params = {element, x, y};
+export async function getAttribute(attribute, elementId) {
+  return String(
     await this.uiautomator2.jwproxy.command(
-      `/touch/up`,
-      'POST',
-      {params}
-    );
-  },
-  async touchMove(element, x, y) {
-    let params = {element, x, y};
-    await this.uiautomator2.jwproxy.command(
-      `/touch/move`,
-      'POST',
-      {params}
-    );
-  },
-  async doSetElementValue(params) {
+      `/element/${elementId}/attribute/${attribute}`,
+      'GET',
+      {}
+    )
+  );
+}
+
+/**
+ * @this {AndroidUiautomator2Driver}
+ * @param {string} elementId
+ * @returns {Promise<boolean>}
+ */
+export async function elementDisplayed(elementId) {
+  return toBool(await this.getAttribute('displayed', elementId));
+}
+
+/**
+ * @this {AndroidUiautomator2Driver}
+ * @param {string} elementId
+ * @returns {Promise<boolean>}
+ */
+export async function elementEnabled(elementId) {
+  return toBool(await this.getAttribute('enabled', elementId));
+}
+
+/**
+ * @this {AndroidUiautomator2Driver}
+ * @param {string} elementId
+ * @returns {Promise<boolean>}
+ */
+export async function elementSelected(elementId) {
+  return toBool(await this.getAttribute('selected', elementId));
+}
+
+/**
+ * @this {AndroidUiautomator2Driver}
+ * @param {string} elementId
+ * @returns {Promise<string>}
+ */
+export async function getName(elementId) {
+  return /** @type {string} */ (
     await this.uiautomator2.jwproxy.command(
-      `/element/${params.elementId}/value`,
-      'POST',
-      params
-    );
-  },
-  async setValueImmediate(keys, elementId) {
+      `/element/${elementId}/name`,
+      'GET',
+      {}
+    )
+  );
+}
+
+/**
+ * @this {AndroidUiautomator2Driver}
+ * @param {string} elementId
+ * @returns {Promise<import('@appium/types').Position>}
+ */
+export async function getLocation(elementId) {
+  return /** @type {import('@appium/types').Position} */ (
     await this.uiautomator2.jwproxy.command(
-      `/element/${elementId}/value`,
-      'POST',
-      {
-        elementId,
-        text: _.isArray(keys) ? keys.join('') : keys,
-        replace: false,
-      }
-    );
-  },
-  async getText(elementId) {
-    return String(
-      await this.uiautomator2.jwproxy.command(
-        `/element/${elementId}/text`,
-        'GET',
-        {}
-      )
-    );
-  },
-  async click(element) {
+      `/element/${elementId}/location`,
+      'GET',
+      {}
+    )
+  );
+}
+
+/**
+ * @this {AndroidUiautomator2Driver}
+ * @param {string} elementId
+ * @returns {Promise<import('@appium/types').Size>}
+ */
+export async function getSize(elementId) {
+  return /** @type {import('@appium/types').Size} */ (
     await this.uiautomator2.jwproxy.command(
-      `/element/${element}/click`,
-      'POST',
-      {element}
-    );
-  },
-  async getElementScreenshot(element) {
-    return String(
-      await this.uiautomator2.jwproxy.command(
-        `/element/${element}/screenshot`,
-        'GET',
-        {}
-      )
-    );
-  },
+      `/element/${elementId}/size`,
+      'GET',
+      {}
+    )
+  );
+}
 
-  async tap(elementId = null, x = null, y = null, count = 1) {
-    const areCoordinatesDefined = util.hasValue(x) && util.hasValue(y);
-    if (!util.hasValue(elementId) && !areCoordinatesDefined) {
-      throw new Error(`Either element id to tap or both absolute coordinates should be defined`);
-    }
+/**
+ * @this {AndroidUiautomator2Driver}
+ * @param {import('appium-android-driver').DoSetElementValueOpts} params
+ * @returns {Promise<void>}
+ */
+export async function doSetElementValue(params) {
+  await this.uiautomator2.jwproxy.command(
+    `/element/${params.elementId}/value`,
+    'POST',
+    params
+  );
+}
 
-    for (let i = 0; i < count; i++) {
-      if (util.hasValue(elementId) && !areCoordinatesDefined) {
-        // we are either tapping on the default location of the element
-        // or an offset from the top left corner
-        await this.uiautomator2.jwproxy.command(
-          `/element/${elementId}/click`,
-          'POST'
-        );
-      } else {
-        await this.uiautomator2.jwproxy.command(
-          `/appium/tap`,
-          'POST',
-          {
-            x,
-            y,
-            [W3C_ELEMENT_KEY]: elementId,
-          }
-        );
-      }
+/**
+ * @this {AndroidUiautomator2Driver}
+ * @param {string|string[]} keys
+ * @param {string} elementId
+ * @returns {Promise<void>}
+ */
+export async function setValueImmediate(keys, elementId) {
+  await this.uiautomator2.jwproxy.command(
+    `/element/${elementId}/value`,
+    'POST',
+    {
+      elementId,
+      text: _.isArray(keys) ? keys.join('') : keys,
+      replace: false,
     }
-  },
+  );
+}
+
+/**
+ * @this {AndroidUiautomator2Driver}
+ * @param {string} elementId
+ * @returns {Promise<string>}
+ */
+export async function getText(elementId) {
+  return String(
+    await this.uiautomator2.jwproxy.command(
+      `/element/${elementId}/text`,
+      'GET',
+      {}
+    )
+  );
+}
+
+/**
+ * @this {AndroidUiautomator2Driver}
+ * @param {string} element
+ * @returns {Promise<void>}
+ */
+export async function click(element) {
+  await this.uiautomator2.jwproxy.command(
+    `/element/${element}/click`,
+    'POST',
+    {element}
+  );
+}
 
-  async clear(elementId) {
+/**
+ * @this {AndroidUiautomator2Driver}
+ * @param {string} element
+ * @returns {Promise<string>}
+ */
+export async function getElementScreenshot(element) {
+  return String(
     await this.uiautomator2.jwproxy.command(
-      `/element/${elementId}/clear`,
-      'POST',
-      {
-        elementId,
-      }
+      `/element/${element}/screenshot`,
+      'GET',
+      {}
+    )
+  );
+}
+
+/**
+ * @this {AndroidUiautomator2Driver}
+ * @param {string} elementId
+ * @returns {Promise<void>}
+ */
+export async function clear(elementId) {
+  await this.uiautomator2.jwproxy.command(
+    `/element/${elementId}/clear`,
+    'POST',
+    {
+      elementId,
+    }
+  );
+}
+
+/**
+ * @this {AndroidUiautomator2Driver}
+ * @param {string} elementId
+ * @returns {Promise<import('@appium/types').Rect>}
+ */
+export async function getElementRect(elementId) {
+  const chromedriver = /** @type {import('appium-chromedriver').default} */ (this.chromedriver);
+  if (this.isWebContext()) {
+    this.log.debug(
+      `Detected downstream chromedriver protocol: ${chromedriver.jwproxy.downstreamProtocol}`
     );
-  },
-
-  async getElementRect(elementId) {
-    const chromedriver = /** @type {import('appium-chromedriver').default} */ (this.chromedriver);
-    if (this.isWebContext()) {
-      this.log.debug(
-        `Detected downstream chromedriver protocol: ${chromedriver.jwproxy.downstreamProtocol}`
-      );
-      if (chromedriver.jwproxy.downstreamProtocol === PROTOCOLS.MJSONWP) {
-        const [{x, y}, {width, height}] =
-          /** @type {[import('@appium/types').Position, import('@appium/types').Size]} */ (
-            await B.all([
-              chromedriver.jwproxy.command(`/element/${elementId}/location`, 'GET'),
-              chromedriver.jwproxy.command(`/element/${elementId}/size`, 'GET'),
-            ])
-          );
-        return {x, y, width, height};
-      }
-      return /** @type {import('@appium/types').Rect} */ (
-        await chromedriver.jwproxy.command(`/element/${elementId}/rect`, 'GET')
-      );
+    if (chromedriver.jwproxy.downstreamProtocol === PROTOCOLS.MJSONWP) {
+      const [{x, y}, {width, height}] =
+        /** @type {[import('@appium/types').Position, import('@appium/types').Size]} */ (
+          await B.all([
+            chromedriver.jwproxy.command(`/element/${elementId}/location`, 'GET'),
+            chromedriver.jwproxy.command(`/element/${elementId}/size`, 'GET'),
+          ])
+        );
+      return {x, y, width, height};
     }
     return /** @type {import('@appium/types').Rect} */ (
-      await this.uiautomator2.jwproxy.command(
-        `/element/${elementId}/rect`,
-        'GET'
-      )
+      await chromedriver.jwproxy.command(`/element/${elementId}/rect`, 'GET')
     );
-  },
-
-  /**
-   * Sends text to the given element by replacing its previous content
-   *
-   * @param {import('./types').ReplaceValueOptions} opts
-   * @throws {Error} If there was a faulre while setting the text
-   */
-  async mobileReplaceElementValue(opts) {
-    const {elementId, text} = requireArgs(['elementId', 'text'], opts);
+  }
+  return /** @type {import('@appium/types').Rect} */ (
     await this.uiautomator2.jwproxy.command(
-      `/element/${elementId}/value`,
-      'POST',
-      {
-        text,
-        replace: true,
-      }
-    );
-  },
-};
+      `/element/${elementId}/rect`,
+      'GET'
+    )
+  );
+}
+
+/**
+ * Sends text to the given element by replacing its previous content
+ * @this {AndroidUiautomator2Driver}
+ * @param {import('./types').ReplaceValueOptions} opts
+ * @throws {Error} If there was a faulre while setting the text
+ * @returns {Promise<void>}
+ */
+export async function mobileReplaceElementValue(opts) {
+  const {elementId, text} = utils.requireArgs(['elementId', 'text'], opts);
+  await this.uiautomator2.jwproxy.command(
+    `/element/${elementId}/value`,
+    'POST',
+    {
+      text,
+      replace: true,
+    }
+  );
+}
+
+// #region Internal Helpers
+
+/**
+ * @param {any} s
+ * @returns {boolean}
+ */
+function toBool(s) {
+  return _.isString(s) ? s.toLowerCase() === 'true' : !!s;
+}
 
-mixin(ElementMixin);
+// #endregion
 
 /**
- * @typedef {import('../uiautomator2').UiAutomator2Server} UiAutomator2Server
+ * @typedef {import('../driver').AndroidUiautomator2Driver} AndroidUiautomator2Driver
  */

package/lib/commands/execute.js

@@ -0,0 +1,120 @@
+import _ from 'lodash';
+import {errors, PROTOCOLS} from 'appium/driver';
+import {AndroidUiautomator2Driver} from '../driver';
+
+const MOBILE_SCRIPT_NAME_PREFIX = 'mobile:';
+
+/**
+ * @override
+ * @privateRemarks Because the "mobile" commands (execute methods) in this
+ * driver universally accept an options object, this method will _not_ call
+ * into `BaseDriver.executeMethod`.
+ * @this {AndroidUiautomator2Driver}
+ * @param {string} script
+ * @param {any[]} [args]
+ * @returns {Promise<any>}
+ */
+export async function execute(script, args) {
+  const mobileScriptName = toExecuteMethodName(script);
+  const isWebContext = this.isWebContext();
+  if (mobileScriptName && isWebContext || !isWebContext) {
+    if (mobileScriptName) {
+      const executeMethodArgs = preprocessExecuteMethodArgs(args);
+      this.log.info(`Executing method '${mobileScriptName}'`);
+      return await this.executeMobile(mobileScriptName, executeMethodArgs);
+    }
+    // Just pass the script name through and let it fail with a proper error message
+    return await this.executeMobile(`${script}`, {});
+  }
+  const endpoint =
+    /** @type {import('appium-chromedriver').Chromedriver} */ (this.chromedriver).jwproxy
+      .downstreamProtocol === PROTOCOLS.MJSONWP
+      ? '/execute'
+      : '/execute/sync';
+  return await /** @type {import('appium-chromedriver').Chromedriver} */ (
+    this.chromedriver
+  ).jwproxy.command(endpoint, 'POST', {
+    script,
+    args,
+  });
+}
+
+/**
+ * @override
+ * @this {AndroidUiautomator2Driver}
+ * @param {string} script Must be of the form `mobile: <something>`, which
+ * differs from its parent class implementation.
+ * @param {import('@appium/types').StringRecord} [opts={}]
+ * @returns {Promise<any>}
+ */
+export async function executeMobile(script, opts = {}) {
+  if (!(script in AndroidUiautomator2Driver.executeMethodMap)) {
+    const commandNames = _.map(
+      _.keys(AndroidUiautomator2Driver.executeMethodMap),
+      (value) => value.slice(8)
+    );
+    throw new errors.UnknownCommandError(
+      `Unknown mobile command "${script}". ` +
+        `Only ${commandNames.join(', ')} commands are supported.`
+    );
+  }
+  const methodName =
+    AndroidUiautomator2Driver.executeMethodMap[
+      /** @type {keyof import('../execute-method-map').Uiautomator2ExecuteMethodMap} */ (script)
+    ].command;
+
+  return await /** @type {(opts?: any) => Promise<unknown>} */ (this[methodName])(opts);
+}
+
+// #region Internal Helpers
+
+/**
+ * Messages the arguments going into an execute method.
+ * @remarks A similar method is implemented in `appium-xcuitest-driver`, but it
+ * appears the methods in here handle unwrapping of `Element` objects, so we do
+ * not do that here.
+ * @param {readonly any[] | readonly [StringRecord] | Readonly<StringRecord>} [args]
+ * @internal
+ * @returns {StringRecord<unknown>}
+ */
+function preprocessExecuteMethodArgs(args) {
+  if (_.isArray(args)) {
+    args = _.first(args);
+  }
+  const executeMethodArgs = /** @type {StringRecord<unknown>} */ (args ?? {});
+  /**
+   * Renames the deprecated `element` key to `elementId`.  Historically,
+   * all of the pre-Execute-Method-Map execute methods accepted an `element` _or_ and `elementId` param.
+   * This assigns the `element` value to `elementId` if `elementId` is not already present.
+   */
+  if (!('elementId' in executeMethodArgs) && 'element' in executeMethodArgs) {
+    executeMethodArgs.elementId = executeMethodArgs.element;
+    delete executeMethodArgs.element;
+  }
+
+  return executeMethodArgs;
+}
+
+/**
+ * Type guard to check if a script is an execute method.
+ * @param {any} script
+ * @internal
+ * @returns {string?}
+ */
+function toExecuteMethodName(script) {
+  return _.startsWith(script, MOBILE_SCRIPT_NAME_PREFIX)
+    ? script.replace(new RegExp(`${MOBILE_SCRIPT_NAME_PREFIX}\\s*`), `${MOBILE_SCRIPT_NAME_PREFIX} `)
+    : null;
+}
+
+// #endregion
+
+/**
+ * @typedef {import('../uiautomator2').UiAutomator2Server} UiAutomator2Server
+ * @typedef {import('appium-adb').ADB} ADB
+ */
+
+/**
+ * @template [T=any]
+ * @typedef {import('@appium/types').StringRecord<T>} StringRecord
+ */

package/lib/commands/find.js

@@ -1,7 +1,4 @@
-// @ts-check
-
 import CssConverter from '../css-converter';
-import {mixin} from './mixins';
 
 // we override the xpath search for this first-visible-child selector, which
 // looks like /*[@firstVisible="true"]
@@ -11,43 +8,40 @@ const MAGIC_SCROLLABLE_SEL = /\/\/\*\[@scrollable ?= ?('|")true\1\]/;
 const MAGIC_SCROLLABLE_BY = 'new UiSelector().scrollable(true)';
 
 /**
- * @type {import('./mixins').UIA2FindMixin}
- * @satisfies {import('@appium/types').ExternalDriver}
+ * @privateRemarks Overriding helpers.doFindElementOrEls functionality of appium-android-driver,
+ * this.element initialized in find.js of appium-android-drive.
+ *
+ * @this {AndroidUiautomator2Driver}
+ * @param {import('appium-android-driver').FindElementOpts} params
+ * @returns {Promise<Element | Element[]>}
  */
-const FindMixin = {
-  /**
-   * @privateRemarks Overriding helpers.doFindElementOrEls functionality of appium-android-driver,
-   * this.element initialized in find.js of appium-android-drive.
-   */
-  async doFindElementOrEls(params) {
-    const uiautomator2 = /** @type {import('../uiautomator2').UiAutomator2Server} */ (
-      this.uiautomator2
-    );
-    if (params.strategy === 'xpath' && MAGIC_FIRST_VIS_CHILD_SEL.test(params.selector)) {
-      let elementId = params.context;
-      return /** @type {Element} */ (
-        await uiautomator2.jwproxy.command(`/appium/element/${elementId}/first_visible`, 'GET', {})
-      );
-    }
-    if (params.strategy === 'xpath' && MAGIC_SCROLLABLE_SEL.test(params.selector)) {
-      params.strategy = '-android uiautomator';
-      params.selector = MAGIC_SCROLLABLE_BY;
-    }
-    if (params.strategy === 'css selector') {
-      params.strategy = '-android uiautomator';
-      params.selector = new CssConverter(
-        params.selector,
-        this.opts.appPackage
-      ).toUiAutomatorSelector();
-    }
-    return /** @type {Element|Element[]} */ (
-      await uiautomator2.jwproxy.command(`/element${params.multiple ? 's' : ''}`, 'POST', params)
+export async function doFindElementOrEls(params) {
+  const uiautomator2 = /** @type {import('../uiautomator2').UiAutomator2Server} */ (
+    this.uiautomator2
+  );
+  if (params.strategy === 'xpath' && MAGIC_FIRST_VIS_CHILD_SEL.test(params.selector)) {
+    let elementId = params.context;
+    return /** @type {Element} */ (
+      await uiautomator2.jwproxy.command(`/appium/element/${elementId}/first_visible`, 'GET', {})
     );
-  },
-};
-
-mixin(FindMixin);
+  }
+  if (params.strategy === 'xpath' && MAGIC_SCROLLABLE_SEL.test(params.selector)) {
+    params.strategy = '-android uiautomator';
+    params.selector = MAGIC_SCROLLABLE_BY;
+  }
+  if (params.strategy === 'css selector') {
+    params.strategy = '-android uiautomator';
+    params.selector = new CssConverter(
+      params.selector,
+      this.opts.appPackage
+    ).toUiAutomatorSelector();
+  }
+  return /** @type {Element|Element[]} */ (
+    await uiautomator2.jwproxy.command(`/element${params.multiple ? 's' : ''}`, 'POST', params)
+  );
+}
 
 /**
  * @typedef {import('@appium/types').Element} Element
+ * @typedef {import('../driver').AndroidUiautomator2Driver} AndroidUiautomator2Driver
  */