appium-android-driver 12.4.9 → 12.4.11

package/lib/commands/element.ts

@@ -0,0 +1,234 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+
+import {errors} from 'appium/driver';
+import type {Position, Size} from '@appium/types';
+import type {AndroidDriver} from '../driver';
+import type {DoSetElementValueOpts} from './types';
+
+/**
+ * Gets an attribute value from an element.
+ *
+ * @param attribute The name of the attribute to retrieve.
+ * @param elementId The element identifier.
+ * @returns Promise that resolves to the attribute value, or `null` if not found.
+ * @throws {errors.NotImplementedError} This method is not implemented.
+ */
+export async function getAttribute(
+  this: AndroidDriver,
+  attribute: string,
+  elementId: string,
+): Promise<string | null> {
+  throw new errors.NotImplementedError('Not implemented');
+}
+
+/**
+ * Clicks on an element.
+ *
+ * @param elementId The element identifier.
+ * @returns Promise that resolves when the click is performed.
+ * @throws {errors.NotImplementedError} This method is not implemented.
+ */
+export async function click(
+  this: AndroidDriver,
+  elementId: string,
+): Promise<void> {
+  throw new errors.NotImplementedError('Not implemented');
+}
+
+/**
+ * Gets the text content of an element.
+ *
+ * @param elementId The element identifier.
+ * @returns Promise that resolves to the element's text content.
+ * @throws {errors.NotImplementedError} This method is not implemented.
+ */
+export async function getText(
+  this: AndroidDriver,
+  elementId: string,
+): Promise<string> {
+  throw new errors.NotImplementedError('Not implemented');
+}
+
+/**
+ * Gets the location of an element on the screen.
+ *
+ * @param elementId The element identifier.
+ * @returns Promise that resolves to the element's position (x, y coordinates).
+ * @throws {errors.NotImplementedError} This method is not implemented.
+ */
+export async function getLocation(
+  this: AndroidDriver,
+  elementId: string,
+): Promise<Position> {
+  throw new errors.NotImplementedError('Not implemented');
+}
+
+/**
+ * Gets the size of an element.
+ *
+ * @param elementId The element identifier.
+ * @returns Promise that resolves to the element's size (width, height).
+ * @throws {errors.NotImplementedError} This method is not implemented.
+ */
+export async function getSize(
+  this: AndroidDriver,
+  elementId: string,
+): Promise<Size> {
+  throw new errors.NotImplementedError('Not implemented');
+}
+
+/**
+ * Gets the class name of an element.
+ *
+ * @param elementId The element identifier.
+ * @returns Promise that resolves to the element's class name.
+ */
+export async function getName(
+  this: AndroidDriver,
+  elementId: string,
+): Promise<string> {
+  return await this.getAttribute('className', elementId) as string;
+}
+
+/**
+ * Checks if an element is displayed.
+ *
+ * @param elementId The element identifier.
+ * @returns Promise that resolves to `true` if the element is displayed, `false` otherwise.
+ */
+export async function elementDisplayed(
+  this: AndroidDriver,
+  elementId: string,
+): Promise<boolean> {
+  return (await this.getAttribute('displayed', elementId)) === 'true';
+}
+
+/**
+ * Checks if an element is enabled.
+ *
+ * @param elementId The element identifier.
+ * @returns Promise that resolves to `true` if the element is enabled, `false` otherwise.
+ */
+export async function elementEnabled(
+  this: AndroidDriver,
+  elementId: string,
+): Promise<boolean> {
+  return (await this.getAttribute('enabled', elementId)) === 'true';
+}
+
+/**
+ * Checks if an element is selected.
+ *
+ * @param elementId The element identifier.
+ * @returns Promise that resolves to `true` if the element is selected, `false` otherwise.
+ */
+export async function elementSelected(
+  this: AndroidDriver,
+  elementId: string,
+): Promise<boolean> {
+  return (await this.getAttribute('selected', elementId)) === 'true';
+}
+
+/**
+ * Sets the value of an element.
+ *
+ * @param keys The text to set, either as a string or an array of strings (which will be joined).
+ * @param elementId The element identifier.
+ * @param replace If `true`, replaces the existing value. If `false`, appends to it. Defaults to `false`.
+ * @returns Promise that resolves when the value is set.
+ */
+export async function setElementValue(
+  this: AndroidDriver,
+  keys: string | string[],
+  elementId: string,
+  replace = false,
+): Promise<void> {
+  const text = keys instanceof Array ? keys.join('') : keys;
+  return await this.doSetElementValue({
+    elementId,
+    text: String(text),
+    replace,
+  });
+}
+
+/**
+ * Sets the value of an element.
+ *
+ * Reason for isolating doSetElementValue from setElementValue is for reusing setElementValue
+ * across android-drivers (like appium-uiautomator2-driver) and to avoid code duplication.
+ * Other android-drivers (like appium-uiautomator2-driver) need to override doSetElementValue
+ * to facilitate setElementValue.
+ *
+ * @param params The parameters for setting the element value.
+ * @returns Promise that resolves when the value is set.
+ * @throws {errors.NotImplementedError} This method is not implemented.
+ */
+export async function doSetElementValue(
+  this: AndroidDriver,
+  params: DoSetElementValueOpts,
+): Promise<void> {
+  throw new errors.NotImplementedError('Not implemented');
+}
+
+/**
+ * Sets the value of an element (appends to existing value).
+ *
+ * @param keys The text to set, either as a string or an array of strings (which will be joined).
+ * @param elementId The element identifier.
+ * @returns Promise that resolves when the value is set.
+ */
+export async function setValue(
+  this: AndroidDriver,
+  keys: string | string[],
+  elementId: string,
+): Promise<void> {
+  return await this.setElementValue(keys, elementId, false);
+}
+
+/**
+ * Replaces the value of an element.
+ *
+ * @param keys The text to set, either as a string or an array of strings (which will be joined).
+ * @param elementId The element identifier.
+ * @returns Promise that resolves when the value is replaced.
+ */
+export async function replaceValue(
+  this: AndroidDriver,
+  keys: string | string[],
+  elementId: string,
+): Promise<void> {
+  return await this.setElementValue(keys, elementId, true);
+}
+
+/**
+ * Sets the value of an element immediately using ADB input.
+ *
+ * @param keys The text to set, either as a string or an array of strings (which will be joined).
+ * @param elementId The element identifier.
+ * @returns Promise that resolves when the value is set.
+ */
+export async function setValueImmediate(
+  this: AndroidDriver,
+  keys: string | string[],
+  elementId: string,
+): Promise<void> {
+  const text = Array.isArray(keys) ? keys.join('') : keys;
+  // first, make sure we are focused on the element
+  await this.click(elementId);
+  // then send through adb
+  await this.adb.inputText(text);
+}
+
+/**
+ * Gets the location of an element relative to the view.
+ *
+ * @param elementId The element identifier.
+ * @returns Promise that resolves to the element's position (x, y coordinates).
+ */
+export async function getLocationInView(
+  this: AndroidDriver,
+  elementId: string,
+): Promise<Position> {
+  return await this.getLocation(elementId);
+}
+

package/lib/commands/{execute.js → execute.ts}

@@ -1,16 +1,26 @@
 import _ from 'lodash';
 import {errors, PROTOCOLS} from 'appium/driver';
 import { util } from '@appium/support';
+import type {StringRecord, Element} from '@appium/types';
+import type {AndroidDriver} from '../driver';
+import type {Chromedriver} from 'appium-chromedriver';
 
 const EXECUTE_SCRIPT_PREFIX = 'mobile:';
 
 /**
- * @this {AndroidDriver}
- * @param {string} script
- * @param {ExecuteMethodArgs} [args]
- * @returns {Promise<any>}
+ * Executes a script on the device or in a web context.
+ *
+ * @param script The script to execute. If it starts with 'mobile:', it will be treated
+ * as a mobile command. Otherwise, it will be executed in the web context (if available).
+ * @param args Optional arguments to pass to the script.
+ * @returns Promise that resolves to the script execution result.
+ * @throws {errors.NotImplementedError} If not in a web context and script doesn't start with 'mobile:'.
  */
-export async function execute(script, args) {
+export async function execute(
+  this: AndroidDriver,
+  script: string,
+  args?: ExecuteMethodArgs,
+): Promise<any> {
   if (_.startsWith(script, EXECUTE_SCRIPT_PREFIX)) {
     const formattedScript = script.trim().replace(/^mobile:\s*/, `${EXECUTE_SCRIPT_PREFIX} `);
     const executeMethodArgs = preprocessExecuteMethodArgs(args);
@@ -20,13 +30,11 @@ export async function execute(script, args) {
     throw new errors.NotImplementedError();
   }
   const endpoint =
-    /** @type {import('appium-chromedriver').Chromedriver} */ (this.chromedriver).jwproxy
+    (this.chromedriver as Chromedriver).jwproxy
       .downstreamProtocol === PROTOCOLS.MJSONWP
       ? '/execute'
       : '/execute/sync';
-  return await /** @type {import('appium-chromedriver').Chromedriver} */ (
-    this.chromedriver
-  ).jwproxy.command(endpoint, 'POST', {
+  return await (this.chromedriver as Chromedriver).jwproxy.command(endpoint, 'POST', {
     script,
     args,
   });
@@ -37,11 +45,11 @@ export async function execute(script, args) {
 /**
  * Massages the arguments going into an execute method.
  *
- * @param {ExecuteMethodArgs} [args]
- * @returns {StringRecord}
+ * @param args Optional arguments to preprocess.
+ * @returns Preprocessed arguments as a StringRecord.
  */
-function preprocessExecuteMethodArgs(args) {
-  const executeMethodArgs = /** @type {StringRecord} */ ((_.isArray(args) ? _.first(args) : args) ?? {});
+function preprocessExecuteMethodArgs(args?: ExecuteMethodArgs): StringRecord {
+  const executeMethodArgs = (_.isArray(args) ? _.first(args) : args) ?? {} as StringRecord;
 
   /**
    * Renames the deprecated `element` key to `elementId`.  Historically,
@@ -57,7 +65,7 @@ function preprocessExecuteMethodArgs(args) {
    */
   if ('elementId' in executeMethodArgs) {
     executeMethodArgs.elementId = util.unwrapElement(
-      /** @type {import('@appium/types').Element|string} */ (executeMethodArgs.elementId),
+      executeMethodArgs.elementId as Element | string,
     );
   }
 
@@ -66,8 +74,5 @@ function preprocessExecuteMethodArgs(args) {
 
 // #endregion
 
-/**
- * @typedef {import('../driver').AndroidDriver} AndroidDriver
- * @typedef {import('@appium/types').StringRecord} StringRecord
- * @typedef {readonly any[] | readonly [StringRecord] | Readonly<StringRecord>} ExecuteMethodArgs
- */
+type ExecuteMethodArgs = readonly any[] | readonly [StringRecord] | Readonly<StringRecord>;
+

package/lib/commands/gestures.ts

@@ -0,0 +1,19 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+import {errors} from 'appium/driver';
+import type {StringRecord} from '@appium/types';
+import type {AndroidDriver} from '../driver';
+
+/**
+ * Performs a series of actions (gestures) on the device.
+ *
+ * @param actions An array of action objects to perform.
+ * @returns Promise that resolves when all actions are performed.
+ * @throws {errors.NotImplementedError} This method is not implemented.
+ */
+export async function performActions(
+  this: AndroidDriver,
+  actions: StringRecord[],
+): Promise<void> {
+  throw new errors.NotImplementedError('Not implemented');
+}
+

package/lib/commands/{image-injection.js → image-injection.ts}

@@ -3,6 +3,7 @@ import path from 'node:path';
 import {fs, tempDir} from '@appium/support';
 import crypto from 'node:crypto';
 import _ from 'lodash';
+import type {AndroidDriver} from '../driver';
 
 const EMULATOR_RESOURCES_ROOT = ['emulator', 'resources'];
 const CONFIG_NAME = 'Toren1BD.posters';
@@ -25,13 +26,15 @@ const PNG_MAGIC_LENGTH = 4;
  * Updates the emulator configuration to show the
  * image using the given properties when one opens the Camera app.
  *
- * @this {AndroidDriver}
- * @param {string} sdkRoot ADB SDK root folder path
- * @returns {Promise<boolean>} If emulator services restart is needed
- * to load the updated config or false if the current config is already up to date
+ * @param sdkRoot ADB SDK root folder path
+ * @returns Promise that resolves to `true` if emulator services restart is needed
+ * to load the updated config or `false` if the current config is already up to date
  * or does not need to be updated
  */
-export async function prepareEmulatorForImageInjection(sdkRoot) {
+export async function prepareEmulatorForImageInjection(
+  this: AndroidDriver,
+  sdkRoot: string,
+): Promise<boolean> {
   const { injectedImageProperties: props } = this.opts;
   if (!props) {
     return false;
@@ -74,11 +77,15 @@ export async function prepareEmulatorForImageInjection(sdkRoot) {
  * already prepared and loaded either manually or using the
  * `injectedImageProperties` capability.
  *
- * @this {AndroidDriver}
- * @param {string} payload Base64-encoded payload of a .png image to be injected
- * @returns {Promise<void>}
+ * @param payload Base64-encoded payload of a .png image to be injected
+ * @returns Promise that resolves when the image is injected.
+ * @throws {Error} If called on a non-emulator device.
+ * @throws {errors.InvalidArgumentError} If the payload is not a valid base64-encoded PNG.
  */
-export async function mobileInjectEmulatorCameraImage(payload) {
+export async function mobileInjectEmulatorCameraImage(
+  this: AndroidDriver,
+  payload: string,
+): Promise<void> {
   if (!this.isEmulator()) {
     throw new Error('The image injection feature is only available on emulators');
   }
@@ -110,12 +117,7 @@ export async function mobileInjectEmulatorCameraImage(payload) {
 
 // #region Internal helpers
 
-/**
- *
- * @param {Buffer} buffer
- * @returns {string}
- */
-function calculateImageHash(buffer) {
+function calculateImageHash(buffer: Buffer): string {
   const hasher = crypto.createHash('sha1');
   hasher.update(buffer);
   return hasher.digest('hex');
@@ -123,7 +125,3 @@ function calculateImageHash(buffer) {
 
 // #endregion
 
-/**
- * @typedef {import('appium-adb').ADB} ADB
- * @typedef {import('../driver').AndroidDriver} AndroidDriver
- */

package/lib/commands/ime.ts

@@ -0,0 +1,79 @@
+import {errors} from 'appium/driver';
+import type {AndroidDriver} from '../driver';
+
+/**
+ * Checks if an IME (Input Method Editor) is activated.
+ *
+ * @returns Promise that resolves to `true` (IME is always activated on Android devices).
+ */
+export async function isIMEActivated(
+  this: AndroidDriver,
+): Promise<boolean> {
+  // IME is always activated on Android devices
+  return true;
+}
+
+/**
+ * Gets the list of available IME engines.
+ *
+ * @returns Promise that resolves to an array of IME engine identifiers.
+ */
+export async function availableIMEEngines(
+  this: AndroidDriver,
+): Promise<string[]> {
+  this.log.debug('Retrieving available IMEs');
+  const engines = await this.adb.availableIMEs();
+  this.log.debug(`Engines: ${JSON.stringify(engines)}`);
+  return engines;
+}
+
+/**
+ * Gets the currently active IME engine.
+ *
+ * @returns Promise that resolves to the active IME engine identifier.
+ */
+export async function getActiveIMEEngine(
+  this: AndroidDriver,
+): Promise<string> {
+  this.log.debug('Retrieving current default IME');
+  return String(await this.adb.defaultIME());
+}
+
+/**
+ * Activates an IME engine.
+ *
+ * @param imeId The IME engine identifier to activate.
+ * @returns Promise that resolves when the IME is activated.
+ * @throws {errors.IMENotAvailableError} If the IME is not available.
+ */
+export async function activateIMEEngine(
+  this: AndroidDriver,
+  imeId: string,
+): Promise<void> {
+  this.log.debug(`Attempting to activate IME ${imeId}`);
+  const availableEngines = await this.adb.availableIMEs();
+  if (availableEngines.indexOf(imeId) === -1) {
+    this.log.debug('IME not found, failing');
+    throw new errors.IMENotAvailableError();
+  }
+  this.log.debug('Found installed IME, attempting to activate');
+  await this.adb.enableIME(imeId);
+  await this.adb.setIME(imeId);
+}
+
+/**
+ * Deactivates the currently active IME engine.
+ *
+ * @returns Promise that resolves when the IME is deactivated.
+ */
+export async function deactivateIMEEngine(
+  this: AndroidDriver,
+): Promise<void> {
+  const currentEngine = await this.getActiveIMEEngine();
+  // XXX: this allowed 'null' to be passed into `adb.shell`
+  if (currentEngine) {
+    this.log.debug(`Attempting to deactivate ${currentEngine}`);
+    await this.adb.disableIME(currentEngine);
+  }
+}
+

package/lib/commands/keyboard.ts

@@ -0,0 +1,163 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+import _ from 'lodash';
+import {errors} from 'appium/driver';
+import {UNICODE_IME, EMPTY_IME} from 'io.appium.settings';
+import type {AndroidDriver} from '../driver';
+import type {SendKeysOpts} from './types';
+
+/**
+ * Hides the on-screen keyboard.
+ *
+ * @returns Promise that resolves to `true` if the keyboard was hidden, `false` otherwise.
+ */
+export async function hideKeyboard(
+  this: AndroidDriver,
+): Promise<boolean> {
+  return await this.adb.hideKeyboard();
+}
+
+/**
+ * Checks if the on-screen keyboard is currently shown.
+ *
+ * @returns Promise that resolves to `true` if the keyboard is shown, `false` otherwise.
+ */
+export async function isKeyboardShown(
+  this: AndroidDriver,
+): Promise<boolean> {
+  const {isKeyboardShown} = await this.adb.isSoftKeyboardPresent();
+  return isKeyboardShown;
+}
+
+/**
+ * Sends keys to the active element.
+ *
+ * @param keys The keys to send, either as a string or an array of strings (which will be joined).
+ * @returns Promise that resolves when the keys are sent.
+ */
+export async function keys(
+  this: AndroidDriver,
+  keys: string | string[],
+): Promise<void> {
+  // Protocol sends an array; rethink approach
+  const keysStr = _.isArray(keys) ? keys.join('') : keys;
+  await this.doSendKeys({
+    text: keysStr,
+    replace: false,
+  });
+}
+
+/**
+ * Sends keys to the active element.
+ *
+ * @param params The parameters for sending keys.
+ * @returns Promise that resolves when the keys are sent.
+ * @throws {errors.NotImplementedError} This method is not implemented.
+ */
+export async function doSendKeys(
+  this: AndroidDriver,
+  params: SendKeysOpts,
+): Promise<void> {
+  throw new errors.NotImplementedError('Not implemented');
+}
+
+/**
+ * Sends a key event to the device.
+ *
+ * @deprecated Use {@link pressKeyCode} instead.
+ * @param keycode The key code to press.
+ * @param metastate Optional meta state flags.
+ * @returns Promise that resolves when the key event is sent.
+ */
+export async function keyevent(
+  this: AndroidDriver,
+  keycode: string | number,
+  metastate?: number,
+): Promise<void> {
+  // TODO deprecate keyevent; currently wd only implements keyevent
+  this.log.warn('keyevent will be deprecated use pressKeyCode');
+  return await this.pressKeyCode(keycode, metastate);
+}
+
+/**
+ * Presses a key code on the device.
+ *
+ * @param keycode The key code to press.
+ * @param metastate Optional meta state flags.
+ * @returns Promise that resolves when the key code is pressed.
+ * @throws {errors.NotImplementedError} This method is not implemented.
+ */
+export async function pressKeyCode(
+  this: AndroidDriver,
+  keycode: string | number,
+  metastate?: number,
+): Promise<void> {
+  throw new errors.NotImplementedError('Not implemented');
+}
+
+/**
+ * Long presses a key code on the device.
+ *
+ * @param keycode The key code to long press.
+ * @param metastate Optional meta state flags.
+ * @returns Promise that resolves when the key code is long pressed.
+ * @throws {errors.NotImplementedError} This method is not implemented.
+ */
+export async function longPressKeyCode(
+  this: AndroidDriver,
+  keycode: string | number,
+  metastate?: number,
+): Promise<void> {
+  throw new errors.NotImplementedError('Not implemented');
+}
+
+/**
+ * Performs an editor action on the active input field.
+ *
+ * @param action The editor action to perform (e.g., 'done', 'go', 'next').
+ * @returns Promise that resolves when the editor action is performed.
+ */
+export async function mobilePerformEditorAction(
+  this: AndroidDriver,
+  action: string | number,
+): Promise<void> {
+  await this.settingsApp.performEditorAction(action);
+}
+
+// #region Internal Helpers
+
+/**
+ * Initializes Unicode keyboard support.
+ *
+ * @deprecated
+ * @returns Promise that resolves to the default IME identifier that was active before.
+ */
+export async function initUnicodeKeyboard(
+  this: AndroidDriver,
+): Promise<string | null> {
+  this.log.debug('Enabling Unicode keyboard support');
+
+  // get the default IME so we can return back to it later if we want
+  const defaultIME = await this.adb.defaultIME();
+
+  this.log.debug(`Unsetting previous IME ${defaultIME}`);
+  this.log.debug(`Setting IME to '${UNICODE_IME}'`);
+  await this.adb.enableIME(UNICODE_IME);
+  await this.adb.setIME(UNICODE_IME);
+  return defaultIME;
+}
+
+/**
+ * Hides the on-screen keyboard completely by setting IME to empty.
+ *
+ * @returns Promise that resolves when the keyboard is hidden.
+ */
+export async function hideKeyboardCompletely(
+  this: AndroidDriver,
+): Promise<void> {
+  this.log.debug(`Hiding the on-screen keyboard by setting IME to '${EMPTY_IME}'`);
+  await this.adb.enableIME(EMPTY_IME);
+  await this.adb.setIME(EMPTY_IME);
+}
+
+// #endregion
+

package/lib/commands/legacy.ts

@@ -0,0 +1,41 @@
+import { errors } from 'appium/driver';
+import type {AndroidDriver} from '../driver';
+
+const ISSUE_URL = 'https://github.com/appium/appium/issues/15807';
+
+/**
+ * Launches the application.
+ *
+ * @returns Promise that resolves when the app is launched.
+ * @throws {errors.UnsupportedOperationError} This API is not supported anymore.
+ */
+export async function launchApp(
+  this: AndroidDriver,
+): Promise<void> {
+  throw new errors.UnsupportedOperationError(`This API is not supported anymore. See ${ISSUE_URL}`);
+}
+
+/**
+ * Closes the application.
+ *
+ * @returns Promise that resolves when the app is closed.
+ * @throws {errors.UnsupportedOperationError} This API is not supported anymore.
+ */
+export async function closeApp(
+  this: AndroidDriver,
+): Promise<void> {
+  throw new errors.UnsupportedOperationError(`This API is not supported anymore. See ${ISSUE_URL}`);
+}
+
+/**
+ * Resets the application state.
+ *
+ * @returns Promise that resolves when the app is reset.
+ * @throws {errors.UnsupportedOperationError} This API is not supported anymore.
+ */
+export async function reset(
+  this: AndroidDriver,
+): Promise<void> {
+  throw new errors.UnsupportedOperationError(`This API is not supported anymore. See ${ISSUE_URL}`);
+}
+