appium-uiautomator2-driver 6.7.6 → 6.7.8

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

@@ -8,6 +8,7 @@ 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;
@@ -15,6 +16,9 @@ export async function active(this: AndroidUiautomator2Driver): Promise<AppiumEle
 
 /**
  * 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', {}));
@@ -22,6 +26,8 @@ export async function getAttribute(this: AndroidUiautomator2Driver, attribute: s
 
 /**
  * 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));
@@ -29,6 +35,8 @@ export async function elementDisplayed(this: AndroidUiautomator2Driver, elementI
 
 /**
  * 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));
@@ -36,6 +44,8 @@ export async function elementEnabled(this: AndroidUiautomator2Driver, 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));
@@ -43,6 +53,8 @@ export async function elementSelected(this: AndroidUiautomator2Driver, 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;
@@ -50,6 +62,8 @@ export async function getName(this: AndroidUiautomator2Driver, elementId: 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;
@@ -57,6 +71,8 @@ export async function getLocation(this: AndroidUiautomator2Driver, elementId: st
 
 /**
  * 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;
@@ -64,6 +80,7 @@ export async function getSize(this: AndroidUiautomator2Driver, elementId: string
 
 /**
  * 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);
@@ -71,6 +88,8 @@ export async function doSetElementValue(this: AndroidUiautomator2Driver, 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,
@@ -86,6 +105,8 @@ export async function setValueImmediate(
 
 /**
  * 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', {}));
@@ -93,6 +114,7 @@ export async function getText(this: AndroidUiautomator2Driver, elementId: string
 
 /**
  * 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});
@@ -100,6 +122,8 @@ export async function click(this: AndroidUiautomator2Driver, element: string): P
 
 /**
  * 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', {}));
@@ -107,6 +131,7 @@ export async function getElementScreenshot(this: AndroidUiautomator2Driver, elem
 
 /**
  * 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});
@@ -114,6 +139,8 @@ export async function clear(this: AndroidUiautomator2Driver, elementId: string):
 
 /**
  * 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()) {
@@ -133,6 +160,8 @@ export async function getElementRect(this: AndroidUiautomator2Driver, elementId:
 
 /**
  * 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,

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[];
+}
+

package/lib/commands/gestures.ts

@@ -7,6 +7,9 @@ import type {AndroidUiautomator2Driver} from '../driver';
 
 /**
  * Performs a simple click/tap gesture.
+ * @param elementId - Optional element to use as the origin for the click. If not provided, uses screen coordinates.
+ * @param x - Optional X offset from the element origin or screen.
+ * @param y - Optional Y offset from the element origin or screen.
  */
 export async function mobileClickGesture(
   this: AndroidUiautomator2Driver,
@@ -22,6 +25,10 @@ export async function mobileClickGesture(
 
 /**
  * Performs a long click with an optional duration.
+ * @param elementId - Optional element to use as the origin for the long click.
+ * @param x - Optional X offset from the element origin or screen.
+ * @param y - Optional Y offset from the element origin or screen.
+ * @param duration - Optional duration of the long press in milliseconds.
  */
 export async function mobileLongClickGesture(
   this: AndroidUiautomator2Driver,
@@ -39,6 +46,9 @@ export async function mobileLongClickGesture(
 
 /**
  * Performs a double-click gesture.
+ * @param elementId - Optional element to use as the origin for the double click.
+ * @param x - Optional X offset from the element origin or screen.
+ * @param y - Optional Y offset from the element origin or screen.
  */
 export async function mobileDoubleClickGesture(
   this: AndroidUiautomator2Driver,
@@ -54,6 +64,12 @@ export async function mobileDoubleClickGesture(
 
 /**
  * Drags from a start point to an end point.
+ * @param elementId - Optional element to use as the origin for the drag.
+ * @param startX - X coordinate of the drag start point.
+ * @param startY - Y coordinate of the drag start point.
+ * @param endX - X coordinate of the drag end point.
+ * @param endY - Y coordinate of the drag end point.
+ * @param speed - Optional speed of the drag gesture.
  */
 export async function mobileDragGesture(
   this: AndroidUiautomator2Driver,
@@ -74,6 +90,14 @@ export async function mobileDragGesture(
 
 /**
  * Performs a fling gesture and reports if further scrolling is possible.
+ * @param direction - Direction of the fling ('up', 'down', 'left', 'right').
+ * @param elementId - Optional element to use as the origin for the fling.
+ * @param left - Optional left coordinate of the fling area.
+ * @param top - Optional top coordinate of the fling area.
+ * @param width - Optional width of the fling area.
+ * @param height - Optional height of the fling area.
+ * @param speed - Optional speed of the fling gesture.
+ * @returns True if further scrolling is possible, false otherwise.
  */
 export async function mobileFlingGesture(
   this: AndroidUiautomator2Driver,
@@ -95,6 +119,13 @@ export async function mobileFlingGesture(
 
 /**
  * Performs a pinch-close gesture.
+ * @param percent - Percentage of the pinch (0-100).
+ * @param elementId - Optional element to use as the origin for the pinch.
+ * @param left - Optional left coordinate of the pinch area.
+ * @param top - Optional top coordinate of the pinch area.
+ * @param width - Optional width of the pinch area.
+ * @param height - Optional height of the pinch area.
+ * @param speed - Optional speed of the pinch gesture.
  */
 export async function mobilePinchCloseGesture(
   this: AndroidUiautomator2Driver,
@@ -116,6 +147,13 @@ export async function mobilePinchCloseGesture(
 
 /**
  * Performs a pinch-open gesture.
+ * @param percent - Percentage of the pinch (0-100).
+ * @param elementId - Optional element to use as the origin for the pinch.
+ * @param left - Optional left coordinate of the pinch area.
+ * @param top - Optional top coordinate of the pinch area.
+ * @param width - Optional width of the pinch area.
+ * @param height - Optional height of the pinch area.
+ * @param speed - Optional speed of the pinch gesture.
  */
 export async function mobilePinchOpenGesture(
   this: AndroidUiautomator2Driver,
@@ -137,6 +175,14 @@ export async function mobilePinchOpenGesture(
 
 /**
  * Performs a swipe gesture for the given direction and percent.
+ * @param direction - Direction of the swipe ('up', 'down', 'left', 'right').
+ * @param percent - Percentage of the swipe distance (0-100).
+ * @param elementId - Optional element to use as the origin for the swipe.
+ * @param left - Optional left coordinate of the swipe area.
+ * @param top - Optional top coordinate of the swipe area.
+ * @param width - Optional width of the swipe area.
+ * @param height - Optional height of the swipe area.
+ * @param speed - Optional speed of the swipe gesture.
  */
 export async function mobileSwipeGesture(
   this: AndroidUiautomator2Driver,
@@ -160,6 +206,15 @@ export async function mobileSwipeGesture(
 
 /**
  * Performs a scroll gesture and reports if further scrolling is possible.
+ * @param direction - Direction of the scroll ('up', 'down', 'left', 'right').
+ * @param percent - Percentage of the scroll distance (0-100).
+ * @param elementId - Optional element to use as the origin for the scroll.
+ * @param left - Optional left coordinate of the scroll area.
+ * @param top - Optional top coordinate of the scroll area.
+ * @param width - Optional width of the scroll area.
+ * @param height - Optional height of the scroll area.
+ * @param speed - Optional speed of the scroll gesture.
+ * @returns True if further scrolling is possible, false otherwise.
  */
 export async function mobileScrollGesture(
   this: AndroidUiautomator2Driver,
@@ -183,6 +238,9 @@ export async function mobileScrollGesture(
 
 /**
  * Scrolls a scrollable element until a target element becomes visible.
+ * @param elementId - ID of the scrollable element.
+ * @param elementToId - ID of the target element to scroll to.
+ * @throws {errors.InvalidArgumentError} If either elementId or elementToId is not provided.
  */
 export async function mobileScrollBackTo(
   this: AndroidUiautomator2Driver,
@@ -201,6 +259,11 @@ export async function mobileScrollBackTo(
 
 /**
  * Scrolls until an element located by the given strategy is visible.
+ * @param strategy - Locator strategy to use (e.g., 'id', 'xpath', 'class name').
+ * @param selector - Selector string for the element to find.
+ * @param elementId - Optional element to use as the origin for scrolling.
+ * @param maxSwipes - Optional maximum number of swipes to perform.
+ * @throws {errors.InvalidArgumentError} If either strategy or selector is not provided.
  */
 export async function mobileScroll(
   this: AndroidUiautomator2Driver,

package/lib/commands/keyboard.ts

@@ -0,0 +1,102 @@
+import {errors} from 'appium/driver';
+import _ from 'lodash';
+import type {AndroidUiautomator2Driver} from '../driver';
+import type {SendKeysOpts} from 'appium-android-driver';
+
+/**
+ * Presses a key code with optional metastate and flags.
+ * @param keycode - Android key code to press.
+ * @param metastate - Optional meta state modifier keys.
+ * @param flags - Optional flags for the key event.
+ */
+export async function pressKeyCode(
+  this: AndroidUiautomator2Driver,
+  keycode: string | number,
+  metastate?: number,
+  flags?: number,
+): Promise<void> {
+  await this.uiautomator2.jwproxy.command('/appium/device/press_keycode', 'POST', {
+    keycode,
+    metastate,
+    flags,
+  });
+}
+
+/**
+ * Long presses a key code with optional metastate and flags.
+ * @param keycode - Android key code to long press.
+ * @param metastate - Meta state modifier keys.
+ * @param flags - Optional flags for the key event.
+ */
+export async function longPressKeyCode(
+  this: AndroidUiautomator2Driver,
+  keycode: string | number,
+  metastate: number,
+  flags?: number,
+): Promise<void> {
+  await this.uiautomator2.jwproxy.command('/appium/device/long_press_keycode', 'POST', {
+    keycode,
+    metastate,
+    flags,
+  });
+}
+
+/**
+ * Presses a key code with optional metastate, flags, and long press support.
+ * @param keycode - Android key code to press.
+ * @param metastate - Optional meta state modifier keys.
+ * @param flags - Optional flags for the key event.
+ * @param isLongPress - Whether to perform a long press. Defaults to false.
+ */
+export async function mobilePressKey(
+  this: AndroidUiautomator2Driver,
+  keycode: number,
+  metastate?: number,
+  flags?: string,
+  isLongPress: boolean = false,
+): Promise<void> {
+  await this.uiautomator2.jwproxy.command(`/appium/device/${isLongPress ? 'long_' : ''}press_keycode`, 'POST', {
+    keycode,
+    metastate,
+    flags,
+  });
+}
+
+/**
+ * Types the given Unicode string. The focus should already be on the destination input field.
+ * @param text - Text to type. Can be a string, number, or boolean.
+ * @returns True if the input text has been successfully sent to adb.
+ * @throws {errors.InvalidArgumentError} If the text argument is not provided.
+ */
+export async function mobileType(
+  this: AndroidUiautomator2Driver,
+  text: string | number | boolean,
+): Promise<boolean> {
+  if (_.isUndefined(text)) {
+    throw new errors.InvalidArgumentError(`The 'text' argument is mandatory`);
+  }
+  return await this.settingsApp.typeUnicode(String(text));
+}
+
+/**
+ * Sends keys to the current element.
+ * @param params - Options containing the text to send and optional replace flag.
+ */
+export async function doSendKeys(this: AndroidUiautomator2Driver, params: SendKeysOpts): Promise<void> {
+  await this.uiautomator2.jwproxy.command('/keys', 'POST', params);
+}
+
+/**
+ * Sends a key event to the device.
+ * @param keycode - Android key code to send.
+ * @param metastate - Optional meta state (ignored in this implementation).
+ */
+export async function keyevent(
+  this: AndroidUiautomator2Driver,
+  keycode: string | number,
+  metastate?: number,
+): Promise<void> {
+  this.log.debug(`Ignoring metastate ${metastate}`);
+  await this.adb.keyevent(keycode);
+}
+

package/lib/commands/misc.ts

@@ -3,6 +3,7 @@ import type {AndroidUiautomator2Driver} from '../driver';
 
 /**
  * Retrieves the current page source.
+ * @returns The XML page source of the current screen.
  */
 export async function getPageSource(this: AndroidUiautomator2Driver): Promise<string> {
   return String(await this.uiautomator2.jwproxy.command('/source', 'GET', {}));
@@ -10,6 +11,7 @@ export async function getPageSource(this: AndroidUiautomator2Driver): Promise<st
 
 /**
  * Gets the current device orientation.
+ * @returns The current device orientation ('LANDSCAPE' or 'PORTRAIT').
  */
 export async function getOrientation(this: AndroidUiautomator2Driver): Promise<Orientation> {
   return (await this.uiautomator2.jwproxy.command(`/orientation`, 'GET', {})) as Orientation;
@@ -17,6 +19,7 @@ export async function getOrientation(this: AndroidUiautomator2Driver): Promise<O
 
 /**
  * Sets the device orientation.
+ * @param orientation - The desired orientation ('LANDSCAPE' or 'PORTRAIT').
  */
 export async function setOrientation(
   this: AndroidUiautomator2Driver,
@@ -49,6 +52,7 @@ export function suspendChromedriverProxy(this: AndroidUiautomator2Driver): void
 
 /**
  * Retrieves device info via the UIA2 server.
+ * @returns Device information as a string record.
  */
 export async function mobileGetDeviceInfo(this: AndroidUiautomator2Driver): Promise<StringRecord> {
   return (await this.uiautomator2.jwproxy.command('/appium/device/info', 'GET')) as StringRecord;