appium-uiautomator2-driver 2.29.11 → 2.31.0

package/lib/commands/element.js

@@ -1,144 +1,241 @@
-import _ from 'lodash';
-import { util } from 'appium/support';
-import { PROTOCOLS, W3C_ELEMENT_KEY } from 'appium/driver';
-import { requireArgs } from '../utils';
+// @ts-check
 
-let commands = {}, helpers = {}, extensions = {};
+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';
 
-function toBool (s) {
-  return _.isString(s) ? (s.toLowerCase() === 'true') : !!s;
+/**
+ * @param {any} s
+ * @returns {boolean}
+ */
+function toBool(s) {
+  return _.isString(s) ? s.toLowerCase() === 'true' : !!s;
 }
 
-commands.active = async function active () {
-  return await this.uiautomator2.jwproxy.command('/element/active', 'GET');
-};
-
-commands.getAttribute = async function (attribute, elementId) {
-  return await this.uiautomator2.jwproxy.command(`/element/${elementId}/attribute/${attribute}`, 'GET', {});
-};
-
-commands.elementDisplayed = async function (elementId) {
-  return toBool(await this.getAttribute('displayed', elementId));
-};
-
-commands.elementEnabled = async function (elementId) {
-  return toBool(await this.getAttribute('enabled', elementId));
-};
-
-commands.elementSelected = async function (elementId) {
-  return toBool(await this.getAttribute('selected', elementId));
-};
-
-commands.getName = async function (elementId) {
-  return await this.uiautomator2.jwproxy.command(`/element/${elementId}/name`, 'GET', {});
-};
-
-commands.getLocation = async function (elementId) {
-  return await this.uiautomator2.jwproxy.command(`/element/${elementId}/location`, 'GET', {});
-};
-
-commands.getSize = async function (elementId) {
-  return await this.uiautomator2.jwproxy.command(`/element/${elementId}/size`, 'GET', {});
-};
-
-commands.touchLongClick = async function (element, x, y, duration) {
-  let params = {element, x, y, duration};
-  return await this.uiautomator2.jwproxy.command(`/touch/longclick`, 'POST', {params});
-};
-
-commands.touchDown = async function (element, x, y) {
-  let params = {element, x, y};
-  return await this.uiautomator2.jwproxy.command(`/touch/down`, 'POST', {params});
-};
-
-commands.touchUp = async function (element, x, y) {
-  let params = {element, x, y};
-  return await this.uiautomator2.jwproxy.command(`/touch/up`, 'POST', {params});
-};
-
-commands.touchMove = async function (element, x, y) {
-  let params = {element, x, y};
-  return await this.uiautomator2.jwproxy.command(`/touch/move`, 'POST', {params});
-};
-
-helpers.doSetElementValue = async function (params) {
-  return await this.uiautomator2.jwproxy.command(`/element/${params.elementId}/value`, 'POST', params);
-};
-
-commands.setValueImmediate = async function (keys, elementId) {
-  return await this.uiautomator2.jwproxy.command(`/element/${elementId}/value`, 'POST', {
-    elementId,
-    text: _.isArray(keys) ? keys.join('') : keys,
-    replace: false
-  });
-};
-
-commands.getText = async function (elementId) {
-  return await this.uiautomator2.jwproxy.command(`/element/${elementId}/text`, 'GET', {});
-};
-
-commands.click = async function (element) {
-  return await this.uiautomator2.jwproxy.command(`/element/${element}/click`, 'POST', {element});
-};
-
-commands.getElementScreenshot = async function (element) {
-  return await this.uiautomator2.jwproxy.command(`/element/${element}/screenshot`, 'GET', {});
-};
-
-commands.tap = async function (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`);
-  }
-
-  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,
-      });
+/**
+ * @type {import('./mixins').UIA2ElementMixin}
+ * @satisfies {import('@appium/types').ExternalDriver}
+ */
+const ElementMixin = {
+  async active() {
+    return /** @type {import('@appium/types').Element} */ (
+      await /** @type {UiAutomator2Server} */ (this.uiautomator2).jwproxy.command(
+        '/element/active',
+        'GET'
+      )
+    );
+  },
+  async getAttribute(attribute, elementId) {
+    return String(
+      await /** @type {UiAutomator2Server} */ (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 /** @type {UiAutomator2Server} */ (this.uiautomator2).jwproxy.command(
+        `/element/${elementId}/name`,
+        'GET',
+        {}
+      )
+    );
+  },
+  async getLocation(elementId) {
+    return /** @type {import('@appium/types').Position} */ (
+      await /** @type {UiAutomator2Server} */ (this.uiautomator2).jwproxy.command(
+        `/element/${elementId}/location`,
+        'GET',
+        {}
+      )
+    );
+  },
+  async getSize(elementId) {
+    return /** @type {import('@appium/types').Size} */ (
+      await /** @type {UiAutomator2Server} */ (this.uiautomator2).jwproxy.command(
+        `/element/${elementId}/size`,
+        'GET',
+        {}
+      )
+    );
+  },
+  async touchLongClick(element, x, y, duration) {
+    let params = {element, x, y, duration};
+    await /** @type {UiAutomator2Server} */ (this.uiautomator2).jwproxy.command(
+      `/touch/longclick`,
+      'POST',
+      {params}
+    );
+  },
+  async touchDown(element, x, y) {
+    let params = {element, x, y};
+    await /** @type {UiAutomator2Server} */ (this.uiautomator2).jwproxy.command(
+      `/touch/down`,
+      'POST',
+      {params}
+    );
+  },
+  async touchUp(element, x, y) {
+    let params = {element, x, y};
+    await /** @type {UiAutomator2Server} */ (this.uiautomator2).jwproxy.command(
+      `/touch/up`,
+      'POST',
+      {params}
+    );
+  },
+  async touchMove(element, x, y) {
+    let params = {element, x, y};
+    await /** @type {UiAutomator2Server} */ (this.uiautomator2).jwproxy.command(
+      `/touch/move`,
+      'POST',
+      {params}
+    );
+  },
+  async doSetElementValue(params) {
+    await /** @type {UiAutomator2Server} */ (this.uiautomator2).jwproxy.command(
+      `/element/${params.elementId}/value`,
+      'POST',
+      params
+    );
+  },
+  async setValueImmediate(keys, elementId) {
+    await /** @type {UiAutomator2Server} */ (this.uiautomator2).jwproxy.command(
+      `/element/${elementId}/value`,
+      'POST',
+      {
+        elementId,
+        text: _.isArray(keys) ? keys.join('') : keys,
+        replace: false,
+      }
+    );
+  },
+  async getText(elementId) {
+    return String(
+      await /** @type {UiAutomator2Server} */ (this.uiautomator2).jwproxy.command(
+        `/element/${elementId}/text`,
+        'GET',
+        {}
+      )
+    );
+  },
+  async click(element) {
+    await /** @type {UiAutomator2Server} */ (this.uiautomator2).jwproxy.command(
+      `/element/${element}/click`,
+      'POST',
+      {element}
+    );
+  },
+  async getElementScreenshot(element) {
+    return String(
+      await /** @type {UiAutomator2Server} */ (this.uiautomator2).jwproxy.command(
+        `/element/${element}/screenshot`,
+        '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`);
     }
-  }
-};
 
-commands.clear = async function (elementId) {
-  return await this.uiautomator2.jwproxy.command(`/element/${elementId}/clear`, 'POST', {elementId});
-};
-
-commands.getElementRect = async function (elementId) {
-  if (this.isWebContext()) {
-    this.log.debug(`Detected downstream chromedriver protocol: ${this.chromedriver.jwproxy.downstreamProtocol}`);
-    if (this.chromedriver.jwproxy.downstreamProtocol === PROTOCOLS.MJSONWP) {
-      const {x, y} = await this.chromedriver.jwproxy.command(`/element/${elementId}/location`, 'GET');
-      const {width, height} = await this.chromedriver.jwproxy.command(`/element/${elementId}/size`, 'GET');
-      return {x, y, width, height};
+    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 /** @type {UiAutomator2Server} */ (this.uiautomator2).jwproxy.command(
+          `/element/${elementId}/click`,
+          'POST'
+        );
+      } else {
+        await /** @type {UiAutomator2Server} */ (this.uiautomator2).jwproxy.command(
+          `/appium/tap`,
+          'POST',
+          {
+            x,
+            y,
+            [W3C_ELEMENT_KEY]: elementId,
+          }
+        );
+      }
     }
-    return await this.chromedriver.jwproxy.command(`/element/${elementId}/rect`, 'GET');
-  }
-  return await this.uiautomator2.jwproxy.command(`/element/${elementId}/rect`, 'GET');
-};
-
-/**
- * @typedef {Object} ReplaceValueOptions
- * @property {string} elementId The id of the element whose content will be replaced
- * @property {string} text The actual text to set
- */
+  },
+
+  async clear(elementId) {
+    await /** @type {UiAutomator2Server} */ (this.uiautomator2).jwproxy.command(
+      `/element/${elementId}/clear`,
+      'POST',
+      {
+        elementId,
+      }
+    );
+  },
+
+  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')
+      );
+    }
+    return /** @type {import('@appium/types').Rect} */ (
+      await /** @type {UiAutomator2Server} */ (this.uiautomator2).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);
+    await /** @type {UiAutomator2Server} */ (this.uiautomator2).jwproxy.command(
+      `/element/${elementId}/value`,
+      'POST',
+      {
+        text,
+        replace: true,
+      }
+    );
+  },
+};
+
+mixin(ElementMixin);
 
 /**
- * Sends text to the given element by replacing its previous content
- *
- * @param {ReplaceValueOptions} opts
- * @throws {Error} If there was a faulre while setting the text
+ * @typedef {import('../uiautomator2').UiAutomator2Server} UiAutomator2Server
  */
-commands.mobileReplaceElementValue = async function mobileReplaceElementValue (opts = {}) {
-  const {elementId, text} = requireArgs(['elementId', 'text'], opts);
-  return await this.uiautomator2.jwproxy.command(`/element/${elementId}/value`, 'POST', {text, replace: true});
-};
-
-Object.assign(extensions, commands, helpers);
-export { commands, helpers };
-export default extensions;

package/lib/commands/find.js

@@ -1,6 +1,7 @@
-import CssConverter from '../css-converter';
+// @ts-check
 
-const helpers = {};
+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"]
@@ -10,25 +11,43 @@ const MAGIC_SCROLLABLE_SEL = /\/\/\*\[@scrollable ?= ?('|")true\1\]/;
 const MAGIC_SCROLLABLE_BY = 'new UiSelector().scrollable(true)';
 
 /**
- * Overriding helpers.doFindElementOrEls functionality of appium-android-driver,
- * this.element initialized in find.js of appium-android-drive.
+ * @type {import('./mixins').UIA2FindMixin}
+ * @satisfies {import('@appium/types').ExternalDriver}
  */
-helpers.doFindElementOrEls = async function (params) {
-  if (params.strategy === 'xpath' && MAGIC_FIRST_VIS_CHILD_SEL.test(params.selector)) {
-    let elementId = params.context;
-    return await this.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 await this.uiautomator2.jwproxy.command(`/element${params.multiple ? 's' : ''}`, 'POST', params);
+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 { helpers };
-export default helpers;
+mixin(FindMixin);
+
+/**
+ * @typedef {import('@appium/types').Element} Element
+ */