appium-uiautomator2-driver 6.7.5 → 6.7.7

package/lib/commands/actions.ts

@@ -0,0 +1,95 @@
+import type {StringRecord} from '@appium/types';
+import type {AndroidUiautomator2Driver} from '../driver';
+import type {ActionResult} from './types';
+
+/**
+ * Schedules a recurring action to be performed at specified intervals.
+ * @param name - Unique name for the scheduled action.
+ * @param steps - Array of action steps to be executed.
+ * @param maxPass - Maximum number of successful executions before stopping.
+ * @param maxFail - Maximum number of failed executions before stopping.
+ * @param times - Total number of times to execute the action.
+ * @param intervalMs - Interval in milliseconds between action executions.
+ * @param maxHistoryItems - Maximum number of history items to keep.
+ * @returns The result of scheduling the action.
+ */
+export async function mobileScheduleAction(
+  this: AndroidUiautomator2Driver,
+  name: string,
+  steps: StringRecord[],
+  maxPass?: number,
+  maxFail?: number,
+  times?: number,
+  intervalMs?: number,
+  maxHistoryItems?: number,
+): Promise<any> {
+  return await this.uiautomator2.jwproxy.command('/appium/schedule_action', 'POST', {
+    name,
+    steps,
+    maxFail,
+    maxPass,
+    times,
+    intervalMs,
+    maxHistoryItems,
+  });
+}
+
+/**
+ * Gets the execution history for a scheduled action.
+ * @param name - Name of the scheduled action.
+ * @returns The action execution history containing repeats and step results.
+ */
+export async function mobileGetActionHistory(
+  this: AndroidUiautomator2Driver,
+  name: string,
+): Promise<ActionResult> {
+  return (await this.uiautomator2.jwproxy.command('/appium/action_history', 'POST', {name})) as ActionResult;
+}
+
+/**
+ * Unschedules a previously scheduled action.
+ * @param name - Name of the scheduled action to unschedule.
+ * @returns The result of unscheduling the action.
+ */
+export async function mobileUnscheduleAction(
+  this: AndroidUiautomator2Driver,
+  name: string,
+): Promise<any> {
+  return await this.uiautomator2.jwproxy.command('/appium/unschedule_action', 'POST', {name});
+}
+
+/**
+ * Performs a sequence of actions.
+ * @param actions - Array of action objects to perform. Pointer actions are automatically converted to touch type.
+ */
+export async function performActions(
+  this: AndroidUiautomator2Driver,
+  actions: StringRecord[],
+): Promise<void> {
+  // This is mandatory, since 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.uiautomator2.jwproxy.command('/actions', 'POST', {
+    actions: preprocessedActions,
+  });
+}
+
+/**
+ * Releases all currently pressed keys and buttons.
+ */
+export async function releaseActions(this: AndroidUiautomator2Driver): Promise<void> {
+  this.log.info('On this platform, releaseActions is a no-op');
+}
+

package/lib/commands/alert.ts

@@ -0,0 +1,46 @@
+import type {AndroidUiautomator2Driver} from '../driver';
+
+/**
+ * Gets the text of the currently displayed alert.
+ * @returns The alert text as a string.
+ */
+export async function getAlertText(this: AndroidUiautomator2Driver): Promise<string> {
+  return String(await this.uiautomator2.jwproxy.command('/alert/text', 'GET', {}));
+}
+
+/**
+ * Accepts the currently displayed alert.
+ * @param buttonLabel - Optional label of the button to click. If not provided, the button will be detected automatically.
+ */
+export async function mobileAcceptAlert(
+  this: AndroidUiautomator2Driver,
+  buttonLabel?: string,
+): Promise<void> {
+  await this.uiautomator2.jwproxy.command('/alert/accept', 'POST', {buttonLabel});
+}
+
+/**
+ * Accepts the currently displayed alert (W3C endpoint).
+ */
+export async function postAcceptAlert(this: AndroidUiautomator2Driver): Promise<void> {
+  await this.mobileAcceptAlert();
+}
+
+/**
+ * Dismisses the currently displayed alert.
+ * @param buttonLabel - Optional label of the button to click. If not provided, the button will be detected automatically.
+ */
+export async function mobileDismissAlert(
+  this: AndroidUiautomator2Driver,
+  buttonLabel?: string,
+): Promise<void> {
+  await this.uiautomator2.jwproxy.command('/alert/dismiss', 'POST', {buttonLabel});
+}
+
+/**
+ * Dismisses the currently displayed alert (W3C endpoint).
+ */
+export async function postDismissAlert(this: AndroidUiautomator2Driver): Promise<void> {
+  await this.mobileDismissAlert();
+}
+

package/lib/commands/app-management.ts

@@ -0,0 +1,25 @@
+import _ from 'lodash';
+import B from 'bluebird';
+import {errors} from 'appium/driver';
+import {APK_EXTENSION} from '../extensions';
+import type {AndroidUiautomator2Driver} from '../driver';
+import type {InstallOptions} from './types';
+
+/**
+ * Installs multiple APKs with `install-multiple` option.
+ * @param apks - Array of APK file paths or URLs to install.
+ * @param options - Optional installation options (allowTestPackages, useSdcard, grantPermissions, etc.).
+ * @throws {errors.InvalidArgumentError} If the apks array is empty or invalid.
+ */
+export async function mobileInstallMultipleApks(
+  this: AndroidUiautomator2Driver,
+  apks: string[],
+  options?: InstallOptions,
+): Promise<void> {
+  if (!_.isArray(apks) || _.isEmpty(apks)) {
+    throw new errors.InvalidArgumentError('No apks are given to install');
+  }
+  const configuredApks = await B.all(apks.map((app) => this.helpers.configureApp(app, [APK_EXTENSION])));
+  await this.adb.installMultipleApks(configuredApks, options);
+}
+

package/lib/commands/battery.ts

@@ -0,0 +1,19 @@
+import type {AndroidUiautomator2Driver} from '../driver';
+import type {BatteryInfo} from './types';
+
+/**
+ * Reads the battery information from the device under test.
+ * @returns Battery information including level (0.0-1.0) and state (charging, discharging, etc.).
+ */
+export async function mobileGetBatteryInfo(this: AndroidUiautomator2Driver): Promise<BatteryInfo> {
+  const result = (await this.uiautomator2.jwproxy.command('/appium/device/battery_info', 'GET', {})) as {
+    status: BatteryInfo['state'];
+    level: number;
+  };
+  const batteryInfo = result as any;
+  // Give it the same name as in iOS
+  batteryInfo.state = result.status;
+  delete batteryInfo.status;
+  return batteryInfo as BatteryInfo;
+}
+

package/lib/commands/clipboard.ts

@@ -0,0 +1,29 @@
+import type {AndroidUiautomator2Driver} from '../driver';
+
+/**
+ * Gets the clipboard content as a base64-encoded string.
+ * @returns Base64-encoded clipboard content, or an empty string if the clipboard is empty.
+ */
+export async function getClipboard(this: AndroidUiautomator2Driver): Promise<string> {
+  return String(
+    (await this.adb.getApiLevel()) < 29
+      ? await this.uiautomator2.jwproxy.command('/appium/device/get_clipboard', 'POST', {})
+      : await this.settingsApp.getClipboard()
+  );
+}
+
+/**
+ * Sets the clipboard content.
+ * @param content - Base64-encoded clipboard payload.
+ * @param contentType - Content type. Only 'plaintext' is supported. Defaults to 'plaintext'.
+ * @param label - Optional label to identify the current clipboard payload.
+ */
+export async function setClipboard(
+  this: AndroidUiautomator2Driver,
+  content: string,
+  contentType: 'plaintext' = 'plaintext',
+  label?: string,
+): Promise<void> {
+  await this.uiautomator2.jwproxy.command('/appium/device/set_clipboard', 'POST', {content, contentType, label});
+}
+

package/lib/commands/element.ts

@@ -0,0 +1,180 @@
+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.
+ * @returns 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.
+ * @param attribute - Name of the attribute to retrieve.
+ * @param elementId - ID of the element.
+ * @returns The attribute value as a string.
+ */
+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.
+ * @param elementId - ID of the element.
+ * @returns True if the element is displayed, false otherwise.
+ */
+export async function elementDisplayed(this: AndroidUiautomator2Driver, elementId: string): Promise<boolean> {
+  return toBool(await this.getAttribute('displayed', elementId));
+}
+
+/**
+ * Returns whether the element is enabled.
+ * @param elementId - ID of the element.
+ * @returns True if the element is enabled, false otherwise.
+ */
+export async function elementEnabled(this: AndroidUiautomator2Driver, elementId: string): Promise<boolean> {
+  return toBool(await this.getAttribute('enabled', elementId));
+}
+
+/**
+ * Returns whether the element is selected.
+ * @param elementId - ID of the element.
+ * @returns True if the element is selected, false otherwise.
+ */
+export async function elementSelected(this: AndroidUiautomator2Driver, elementId: string): Promise<boolean> {
+  return toBool(await this.getAttribute('selected', elementId));
+}
+
+/**
+ * Gets the element tag name.
+ * @param elementId - ID of the element.
+ * @returns 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.
+ * @param elementId - ID of the element.
+ * @returns The element position coordinates (x, y).
+ */
+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.
+ * @param elementId - ID of the element.
+ * @returns The element size (width, height).
+ */
+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.
+ * @param params - Options containing the element ID and value to set.
+ */
+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.
+ * @param keys - Text to send, either as a string or array of strings (which will be joined).
+ * @param elementId - ID of the element.
+ */
+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.
+ * @param elementId - ID of the element.
+ * @returns The element text content.
+ */
+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.
+ * @param element - ID of the element to click.
+ */
+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.
+ * @param element - ID of the element.
+ * @returns Base64-encoded PNG 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.
+ * @param elementId - ID of the element to clear.
+ */
+export async function clear(this: AndroidUiautomator2Driver, elementId: string): Promise<void> {
+  await this.uiautomator2.jwproxy.command(`/element/${elementId}/clear`, 'POST', {elementId});
+}
+
+/**
+ * Gets the element rectangle.
+ * @param elementId - ID of the element.
+ * @returns The element rectangle (x, y, width, height).
+ */
+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.
+ * @param elementId - ID of the element.
+ * @param text - Text to replace the current element value with.
+ */
+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/find.ts

@@ -0,0 +1,48 @@
+import {CssConverter} from '../css-converter';
+import type {Element as AppiumElement} from '@appium/types';
+import type {FindElementOpts} from 'appium-android-driver';
+import type {AndroidUiautomator2Driver} from '../driver';
+
+// we override the xpath search for this first-visible-child selector, which
+// looks like /*[@firstVisible="true"]
+const MAGIC_FIRST_VIS_CHILD_SEL = /\/\*\[@firstVisible ?= ?('|")true\1\]/;
+
+const MAGIC_SCROLLABLE_SEL = /\/\/\*\[@scrollable ?= ?('|")true\1\]/;
+const MAGIC_SCROLLABLE_BY = 'new UiSelector().scrollable(true)';
+
+/**
+ * Overrides helpers.doFindElementOrEls functionality of appium-android-driver.
+ * Handles special xpath selectors and CSS selector conversion.
+ * @param params - Element finding options including strategy, selector, context, and multiple flag.
+ * @returns A single element if `params.multiple` is false, or an array of elements if true.
+ */
+export async function doFindElementOrEls(
+  this: AndroidUiautomator2Driver,
+  params: FindElementOpts & {multiple: true},
+): Promise<AppiumElement[]>;
+export async function doFindElementOrEls(
+  this: AndroidUiautomator2Driver,
+  params: FindElementOpts & {multiple: false},
+): Promise<AppiumElement>;
+export async function doFindElementOrEls(
+  this: AndroidUiautomator2Driver,
+  params: FindElementOpts,
+): Promise<AppiumElement | AppiumElement[]> {
+  const uiautomator2 = this.uiautomator2;
+  if (params.strategy === 'xpath' && MAGIC_FIRST_VIS_CHILD_SEL.test(params.selector)) {
+    const elementId = params.context;
+    return (await uiautomator2.jwproxy.command(`/appium/element/${elementId}/first_visible`, 'GET', {})) as AppiumElement;
+  }
+  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 uiautomator2.jwproxy.command(`/element${params.multiple ? 's' : ''}`, 'POST', params)) as
+    | AppiumElement
+    | AppiumElement[];
+}
+