appium-uiautomator2-driver 6.7.5 → 6.7.6

package/lib/commands/element.ts

@@ -0,0 +1,151 @@
+import {PROTOCOLS} from 'appium/driver';
+import B from 'bluebird';
+import _ from 'lodash';
+import type {DoSetElementValueOpts} from 'appium-android-driver';
+import type {Element as AppiumElement, Position, Rect, Size} from '@appium/types';
+import type {AndroidUiautomator2Driver} from '../driver';
+import type {Chromedriver} from 'appium-chromedriver';
+
+/**
+ * Gets the currently active element.
+ */
+export async function active(this: AndroidUiautomator2Driver): Promise<AppiumElement> {
+  return (await this.uiautomator2.jwproxy.command('/element/active', 'GET')) as AppiumElement;
+}
+
+/**
+ * Gets an element attribute value.
+ */
+export async function getAttribute(this: AndroidUiautomator2Driver, attribute: string, elementId: string): Promise<string> {
+  return String(await this.uiautomator2.jwproxy.command(`/element/${elementId}/attribute/${attribute}`, 'GET', {}));
+}
+
+/**
+ * Returns whether the element is displayed.
+ */
+export async function elementDisplayed(this: AndroidUiautomator2Driver, elementId: string): Promise<boolean> {
+  return toBool(await this.getAttribute('displayed', elementId));
+}
+
+/**
+ * Returns whether the element is enabled.
+ */
+export async function elementEnabled(this: AndroidUiautomator2Driver, elementId: string): Promise<boolean> {
+  return toBool(await this.getAttribute('enabled', elementId));
+}
+
+/**
+ * Returns whether the element is selected.
+ */
+export async function elementSelected(this: AndroidUiautomator2Driver, elementId: string): Promise<boolean> {
+  return toBool(await this.getAttribute('selected', elementId));
+}
+
+/**
+ * Gets the element tag name.
+ */
+export async function getName(this: AndroidUiautomator2Driver, elementId: string): Promise<string> {
+  return (await this.uiautomator2.jwproxy.command(`/element/${elementId}/name`, 'GET', {})) as string;
+}
+
+/**
+ * Gets the element location.
+ */
+export async function getLocation(this: AndroidUiautomator2Driver, elementId: string): Promise<Position> {
+  return (await this.uiautomator2.jwproxy.command(`/element/${elementId}/location`, 'GET', {})) as Position;
+}
+
+/**
+ * Gets the element size.
+ */
+export async function getSize(this: AndroidUiautomator2Driver, elementId: string): Promise<Size> {
+  return (await this.uiautomator2.jwproxy.command(`/element/${elementId}/size`, 'GET', {})) as Size;
+}
+
+/**
+ * Sets the value of an element using the upstream driver API.
+ */
+export async function doSetElementValue(this: AndroidUiautomator2Driver, params: DoSetElementValueOpts): Promise<void> {
+  await this.uiautomator2.jwproxy.command(`/element/${params.elementId}/value`, 'POST', params);
+}
+
+/**
+ * Sends text to an element without replacement.
+ */
+export async function setValueImmediate(
+  this: AndroidUiautomator2Driver,
+  keys: string | string[],
+  elementId: string,
+): Promise<void> {
+  await this.uiautomator2.jwproxy.command(`/element/${elementId}/value`, 'POST', {
+    elementId,
+    text: _.isArray(keys) ? keys.join('') : keys,
+    replace: false,
+  });
+}
+
+/**
+ * Gets the element text.
+ */
+export async function getText(this: AndroidUiautomator2Driver, elementId: string): Promise<string> {
+  return String(await this.uiautomator2.jwproxy.command(`/element/${elementId}/text`, 'GET', {}));
+}
+
+/**
+ * Clicks the given element.
+ */
+export async function click(this: AndroidUiautomator2Driver, element: string): Promise<void> {
+  await this.uiautomator2.jwproxy.command(`/element/${element}/click`, 'POST', {element});
+}
+
+/**
+ * Takes a screenshot of the element.
+ */
+export async function getElementScreenshot(this: AndroidUiautomator2Driver, element: string): Promise<string> {
+  return String(await this.uiautomator2.jwproxy.command(`/element/${element}/screenshot`, 'GET', {}));
+}
+
+/**
+ * Clears the element text.
+ */
+export async function clear(this: AndroidUiautomator2Driver, elementId: string): Promise<void> {
+  await this.uiautomator2.jwproxy.command(`/element/${elementId}/clear`, 'POST', {elementId});
+}
+
+/**
+ * Gets the element rectangle.
+ */
+export async function getElementRect(this: AndroidUiautomator2Driver, elementId: string): Promise<Rect> {
+  if (!this.isWebContext()) {
+    return (await this.uiautomator2.jwproxy.command(`/element/${elementId}/rect`, 'GET')) as Rect;
+  }
+
+  const chromedriver = this.chromedriver as Chromedriver;
+  if (chromedriver.jwproxy.downstreamProtocol === PROTOCOLS.MJSONWP) {
+    const [{x, y}, {width, height}] = (await B.all([
+      chromedriver.jwproxy.command(`/element/${elementId}/location`, 'GET'),
+      chromedriver.jwproxy.command(`/element/${elementId}/size`, 'GET'),
+    ])) as [Position, Size];
+    return {x, y, width, height};
+  }
+  return (await chromedriver.jwproxy.command(`/element/${elementId}/rect`, 'GET')) as Rect;
+}
+
+/**
+ * Replaces the element text.
+ */
+export async function mobileReplaceElementValue(
+  this: AndroidUiautomator2Driver,
+  elementId: string,
+  text: string,
+): Promise<void> {
+  await this.uiautomator2.jwproxy.command(`/element/${elementId}/value`, 'POST', {
+    text,
+    replace: true,
+  });
+}
+
+function toBool(value: any): boolean {
+  return _.isString(value) ? value.toLowerCase() === 'true' : !!value;
+}
+

package/lib/commands/gestures.ts

@@ -0,0 +1,234 @@
+import {errors} from 'appium/driver';
+import {util} from 'appium/support';
+import _ from 'lodash';
+import type {Element as AppiumElement, Position} from '@appium/types';
+import type {RelativeRect} from './types';
+import type {AndroidUiautomator2Driver} from '../driver';
+
+/**
+ * Performs a simple click/tap gesture.
+ */
+export async function mobileClickGesture(
+  this: AndroidUiautomator2Driver,
+  elementId?: AppiumElement | string,
+  x?: number,
+  y?: number,
+): Promise<void> {
+  await this.uiautomator2.jwproxy.command('/appium/gestures/click', 'POST', {
+    origin: toOrigin(elementId),
+    offset: toPoint(x, y),
+  });
+}
+
+/**
+ * Performs a long click with an optional duration.
+ */
+export async function mobileLongClickGesture(
+  this: AndroidUiautomator2Driver,
+  elementId?: AppiumElement | string,
+  x?: number,
+  y?: number,
+  duration?: number,
+): Promise<void> {
+  await this.uiautomator2.jwproxy.command('/appium/gestures/long_click', 'POST', {
+    origin: toOrigin(elementId),
+    offset: toPoint(x, y),
+    duration,
+  });
+}
+
+/**
+ * Performs a double-click gesture.
+ */
+export async function mobileDoubleClickGesture(
+  this: AndroidUiautomator2Driver,
+  elementId?: AppiumElement | string,
+  x?: number,
+  y?: number,
+): Promise<void> {
+  await this.uiautomator2.jwproxy.command('/appium/gestures/double_click', 'POST', {
+    origin: toOrigin(elementId),
+    offset: toPoint(x, y),
+  });
+}
+
+/**
+ * Drags from a start point to an end point.
+ */
+export async function mobileDragGesture(
+  this: AndroidUiautomator2Driver,
+  elementId?: AppiumElement | string,
+  startX?: number,
+  startY?: number,
+  endX?: number,
+  endY?: number,
+  speed?: number,
+): Promise<void> {
+  await this.uiautomator2.jwproxy.command('/appium/gestures/drag', 'POST', {
+    origin: toOrigin(elementId),
+    start: toPoint(startX, startY),
+    end: toPoint(endX, endY),
+    speed,
+  });
+}
+
+/**
+ * Performs a fling gesture and reports if further scrolling is possible.
+ */
+export async function mobileFlingGesture(
+  this: AndroidUiautomator2Driver,
+  direction: string,
+  elementId?: AppiumElement | string,
+  left?: number,
+  top?: number,
+  width?: number,
+  height?: number,
+  speed?: number,
+): Promise<boolean> {
+  return (await this.uiautomator2.jwproxy.command('/appium/gestures/fling', 'POST', {
+    origin: toOrigin(elementId),
+    area: toRect(left, top, width, height),
+    direction,
+    speed,
+  })) as boolean;
+}
+
+/**
+ * Performs a pinch-close gesture.
+ */
+export async function mobilePinchCloseGesture(
+  this: AndroidUiautomator2Driver,
+  percent: number,
+  elementId?: AppiumElement | string,
+  left?: number,
+  top?: number,
+  width?: number,
+  height?: number,
+  speed?: number,
+): Promise<void> {
+  await this.uiautomator2.jwproxy.command('/appium/gestures/pinch_close', 'POST', {
+    origin: toOrigin(elementId),
+    area: toRect(left, top, width, height),
+    percent,
+    speed,
+  });
+}
+
+/**
+ * Performs a pinch-open gesture.
+ */
+export async function mobilePinchOpenGesture(
+  this: AndroidUiautomator2Driver,
+  percent: number,
+  elementId?: AppiumElement | string,
+  left?: number,
+  top?: number,
+  width?: number,
+  height?: number,
+  speed?: number,
+): Promise<void> {
+  await this.uiautomator2.jwproxy.command('/appium/gestures/pinch_open', 'POST', {
+    origin: toOrigin(elementId),
+    area: toRect(left, top, width, height),
+    percent,
+    speed,
+  });
+}
+
+/**
+ * Performs a swipe gesture for the given direction and percent.
+ */
+export async function mobileSwipeGesture(
+  this: AndroidUiautomator2Driver,
+  direction: string,
+  percent: number,
+  elementId?: AppiumElement | string,
+  left?: number,
+  top?: number,
+  width?: number,
+  height?: number,
+  speed?: number,
+): Promise<void> {
+  await this.uiautomator2.jwproxy.command('/appium/gestures/swipe', 'POST', {
+    origin: toOrigin(elementId),
+    area: toRect(left, top, width, height),
+    direction,
+    percent,
+    speed,
+  });
+}
+
+/**
+ * Performs a scroll gesture and reports if further scrolling is possible.
+ */
+export async function mobileScrollGesture(
+  this: AndroidUiautomator2Driver,
+  direction: string,
+  percent: number,
+  elementId?: AppiumElement | string,
+  left?: number,
+  top?: number,
+  width?: number,
+  height?: number,
+  speed?: number,
+): Promise<boolean> {
+  return (await this.uiautomator2.jwproxy.command('/appium/gestures/scroll', 'POST', {
+    origin: toOrigin(elementId),
+    area: toRect(left, top, width, height),
+    direction,
+    percent,
+    speed,
+  })) as boolean;
+}
+
+/**
+ * Scrolls a scrollable element until a target element becomes visible.
+ */
+export async function mobileScrollBackTo(
+  this: AndroidUiautomator2Driver,
+  elementId?: string,
+  elementToId?: string,
+): Promise<void> {
+  if (!elementId || !elementToId) {
+    throw new errors.InvalidArgumentError(`Both elementId and elementToId arguments must be provided`);
+  }
+  await this.uiautomator2.jwproxy.command(
+    `/appium/element/${util.unwrapElement(elementId)}/scroll_to/${util.unwrapElement(elementToId)}`,
+    'POST',
+    {},
+  );
+}
+
+/**
+ * Scrolls until an element located by the given strategy is visible.
+ */
+export async function mobileScroll(
+  this: AndroidUiautomator2Driver,
+  strategy: string,
+  selector: string,
+  elementId?: AppiumElement | string,
+  maxSwipes?: number,
+): Promise<void> {
+  if (!strategy || !selector) {
+    throw new errors.InvalidArgumentError(`Both strategy and selector arguments must be provided`);
+  }
+  await this.uiautomator2.jwproxy.command('/gestures/scroll_to', 'POST', {
+    origin: toOrigin(elementId),
+    params: {strategy, selector, maxSwipes},
+  });
+}
+
+function toOrigin(element?: AppiumElement | string): AppiumElement | undefined {
+  return element ? (util.wrapElement(util.unwrapElement(element)) as AppiumElement) : undefined;
+}
+
+function toPoint(x?: number, y?: number): Partial<Position> | undefined {
+  return _.isFinite(x) && _.isFinite(y) ? {x, y} : undefined;
+}
+
+function toRect(left?: number, top?: number, width?: number, height?: number): RelativeRect | undefined {
+  return [left, top, width, height].some((v) => !_.isFinite(v))
+    ? undefined
+    : ({left, top, width, height} as RelativeRect);
+}
+

package/lib/commands/misc.ts

@@ -0,0 +1,63 @@
+import type {Orientation, StringRecord} from '@appium/types';
+import type {AndroidUiautomator2Driver} from '../driver';
+
+/**
+ * Retrieves the current page source.
+ */
+export async function getPageSource(this: AndroidUiautomator2Driver): Promise<string> {
+  return String(await this.uiautomator2.jwproxy.command('/source', 'GET', {}));
+}
+
+/**
+ * Gets the current device orientation.
+ */
+export async function getOrientation(this: AndroidUiautomator2Driver): Promise<Orientation> {
+  return (await this.uiautomator2.jwproxy.command(`/orientation`, 'GET', {})) as Orientation;
+}
+
+/**
+ * Sets the device orientation.
+ */
+export async function setOrientation(
+  this: AndroidUiautomator2Driver,
+  orientation: Orientation,
+): Promise<void> {
+  const normalizedOrientation = orientation.toUpperCase() as Orientation;
+  await this.uiautomator2.jwproxy.command(`/orientation`, 'POST', {orientation: normalizedOrientation});
+}
+
+/**
+ * Opens the device notification shade.
+ */
+export async function openNotifications(this: AndroidUiautomator2Driver): Promise<void> {
+  await this.uiautomator2.jwproxy.command('/appium/device/open_notifications', 'POST', {});
+}
+
+/**
+ * Stops proxying to Chromedriver and restores UIA2 proxy.
+ */
+export function suspendChromedriverProxy(this: AndroidUiautomator2Driver): void {
+  if (!this.uiautomator2?.proxyReqRes || !this.uiautomator2?.proxyCommand) {
+    return;
+  }
+
+  this.chromedriver = undefined;
+  this.proxyReqRes = this.uiautomator2.proxyReqRes.bind(this.uiautomator2);
+  this.proxyCommand = this.uiautomator2.proxyCommand.bind(this.uiautomator2);
+  this.jwpProxyActive = true;
+}
+
+/**
+ * Retrieves device info via the UIA2 server.
+ */
+export async function mobileGetDeviceInfo(this: AndroidUiautomator2Driver): Promise<StringRecord> {
+  return (await this.uiautomator2.jwproxy.command('/appium/device/info', 'GET')) as StringRecord;
+}
+
+/**
+ * Resets the accessibility cache on the device.
+ */
+export async function mobileResetAccessibilityCache(this: AndroidUiautomator2Driver): Promise<void> {
+  await this.uiautomator2.jwproxy.command('/appium/reset_ax_cache', 'POST', {});
+}
+

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "appium-uiautomator2-driver",
-  "version": "6.7.5",
+  "version": "6.7.6",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "appium-uiautomator2-driver",
-      "version": "6.7.5",
+      "version": "6.7.6",
       "license": "Apache-2.0",
       "dependencies": {
         "appium-adb": "^14.0.0",
@@ -626,9 +626,9 @@
       }
     },
     "node_modules/appium-adb": {
-      "version": "14.1.7",
-      "resolved": "https://registry.npmjs.org/appium-adb/-/appium-adb-14.1.7.tgz",
-      "integrity": "sha512-/06TJ7maIJ4RzKmXdnqVNBhBZqoxAwoDeYBEaRm8Dbsa803Io16CJ94R3ncpQwlD5r5bsj4YMmwdZtVZKMjsLw==",
+      "version": "14.1.8",
+      "resolved": "https://registry.npmjs.org/appium-adb/-/appium-adb-14.1.8.tgz",
+      "integrity": "sha512-GjJg3/1ZmwFk2YEWsPc/4CuejnpC4G3UN7ZP0dlBpYNHmbaLuUswnZnAhGpp/7yU2cAZXWZf43/5aJdFeoRxJg==",
       "license": "Apache-2.0",
       "dependencies": {
         "@appium/support": "^7.0.0-rc.1",
@@ -639,22 +639,7 @@
         "lodash": "^4.0.0",
         "lru-cache": "^11.1.0",
         "semver": "^7.0.0",
-        "teen_process": "^3.0.0"
-      },
-      "engines": {
-        "node": "^20.19.0 || ^22.12.0 || >=24.0.0",
-        "npm": ">=10"
-      }
-    },
-    "node_modules/appium-adb/node_modules/teen_process": {
-      "version": "3.0.6",
-      "resolved": "https://registry.npmjs.org/teen_process/-/teen_process-3.0.6.tgz",
-      "integrity": "sha512-nUw1B4MogSZzzy67n37IM1vg4doj+bWOZ7VwIFZGfD7MDmO+FRlhQlA2+22xJnTELVDDlOaTAMpKuuMI2vkDtg==",
-      "license": "Apache-2.0",
-      "dependencies": {
-        "bluebird": "^3.7.2",
-        "lodash": "^4.17.21",
-        "shell-quote": "^1.8.1"
+        "teen_process": "^4.0.4"
       },
       "engines": {
         "node": "^20.19.0 || ^22.12.0 || >=24.0.0",
@@ -662,9 +647,9 @@
       }
     },
     "node_modules/appium-android-driver": {
-      "version": "12.6.1",
-      "resolved": "https://registry.npmjs.org/appium-android-driver/-/appium-android-driver-12.6.1.tgz",
-      "integrity": "sha512-JFO6ouwGHYgC/knkPBVvKwtAqtaiCIPgUlVGmCngCtnLt2Zk4B0Sv+M1J8Elm1olFpCv/Jmb6kRxcEqHh1yRjg==",
+      "version": "12.6.2",
+      "resolved": "https://registry.npmjs.org/appium-android-driver/-/appium-android-driver-12.6.2.tgz",
+      "integrity": "sha512-jQbYHQXtBGgcpXskEvv2s+xtvC1MvcSOU5HD8eKdHpVZvQEnTdcOx3mZyG31UgxryVwj/rboIKRseDy4fTaXew==",
       "license": "Apache-2.0",
       "dependencies": {
         "@appium/support": "^7.0.0-rc.1",
@@ -681,7 +666,7 @@
         "moment-timezone": "^0.x",
         "portscanner": "^2.2.0",
         "semver": "^7.0.0",
-        "teen_process": "^3.0.0",
+        "teen_process": "^4.0.7",
         "ws": "^8.0.0"
       },
       "engines": {
@@ -692,25 +677,10 @@
         "appium": "^3.0.0-rc.2"
       }
     },
-    "node_modules/appium-android-driver/node_modules/teen_process": {
-      "version": "3.0.6",
-      "resolved": "https://registry.npmjs.org/teen_process/-/teen_process-3.0.6.tgz",
-      "integrity": "sha512-nUw1B4MogSZzzy67n37IM1vg4doj+bWOZ7VwIFZGfD7MDmO+FRlhQlA2+22xJnTELVDDlOaTAMpKuuMI2vkDtg==",
-      "license": "Apache-2.0",
-      "dependencies": {
-        "bluebird": "^3.7.2",
-        "lodash": "^4.17.21",
-        "shell-quote": "^1.8.1"
-      },
-      "engines": {
-        "node": "^20.19.0 || ^22.12.0 || >=24.0.0",
-        "npm": ">=10"
-      }
-    },
     "node_modules/appium-chromedriver": {
-      "version": "8.0.31",
-      "resolved": "https://registry.npmjs.org/appium-chromedriver/-/appium-chromedriver-8.0.31.tgz",
-      "integrity": "sha512-hmamyXXsRwzhYoMbNzfdL1t/lCb0o0vLf63WpK/SgLwlcO2ut6MunT729KQSlFzOlLpndtE1H+LCX5KFyPDuMw==",
+      "version": "8.1.0",
+      "resolved": "https://registry.npmjs.org/appium-chromedriver/-/appium-chromedriver-8.1.0.tgz",
+      "integrity": "sha512-zrruUWsDYSk5fdApN7yv9CY35VUp45oTOct+Hc+IidPXPQDyuHcgyeMgpTY8y4FhiiQ89fD4NZNsjwAcqbIxuA==",
       "license": "Apache-2.0",
       "dependencies": {
         "@appium/base-driver": "^10.0.0-rc.2",
@@ -4089,9 +4059,9 @@
       }
     },
     "node_modules/teen_process": {
-      "version": "4.0.5",
-      "resolved": "https://registry.npmjs.org/teen_process/-/teen_process-4.0.5.tgz",
-      "integrity": "sha512-ZQQ2Vjs1/maFzpzfsZRAlQVSZrUBsKzAItaxSLImsHRTdI8hVt9Jm0JHyWFbrvvAf78V55BM3ZgNeQpXcXsWpw==",
+      "version": "4.0.7",
+      "resolved": "https://registry.npmjs.org/teen_process/-/teen_process-4.0.7.tgz",
+      "integrity": "sha512-t7+1xY+WfihWM8M2JxL9ueH/SfDE7bhMuuVMR8bqrttQ0nn95hvOpGqThtZ2S/4+RvrJx2+UWO9no7wDFrOdsw==",
       "license": "Apache-2.0",
       "dependencies": {
         "bluebird": "^3.7.2",

package/package.json

@@ -7,7 +7,7 @@
     "automated testing",
     "android"
   ],
-  "version": "6.7.5",
+  "version": "6.7.6",
   "bugs": {
     "url": "https://github.com/appium/appium-uiautomator2-driver/issues"
   },