appium-android-driver 12.4.7 → 12.4.9

package/lib/commands/intent.ts

@@ -0,0 +1,422 @@
+import _ from 'lodash';
+import {errors} from 'appium/driver';
+import {util} from '@appium/support';
+import type {AndroidDriver} from '../driver';
+import type {IntentOpts} from './types';
+
+const NO_VALUE_ARG_TYPE = 'sn';
+const SUPPORTED_EXTRA_TYPES = [
+  's',
+  NO_VALUE_ARG_TYPE,
+  'z',
+  'i',
+  'l',
+  'f',
+  'u',
+  'cn',
+  'ia',
+  'ial',
+  'la',
+  'lal',
+  'fa',
+  'fal',
+  'sa',
+  'sal',
+] as const;
+
+/**
+ * Starts an Android activity.
+ *
+ * @deprecated Use {@link mobileStartActivity} instead.
+ * @param appPackage The package name of the application to start.
+ * @param appActivity The activity name to start.
+ * @param appWaitPackage The package name to wait for. Defaults to `appPackage` if not provided.
+ * @param appWaitActivity The activity name to wait for. Defaults to `appActivity` if not provided.
+ * @param intentAction The intent action to use.
+ * @param intentCategory The intent category to use.
+ * @param intentFlags The intent flags to use.
+ * @param optionalIntentArguments Optional intent arguments.
+ * @param dontStopAppOnReset If `true`, does not stop the app on reset. If not provided, uses the capability value.
+ * @returns Promise that resolves when the activity is started.
+ */
+export async function startActivity(
+  this: AndroidDriver,
+  appPackage: string,
+  appActivity: string,
+  appWaitPackage?: string,
+  appWaitActivity?: string,
+  intentAction?: string,
+  intentCategory?: string,
+  intentFlags?: string,
+  optionalIntentArguments?: string,
+  dontStopAppOnReset?: boolean,
+): Promise<void> {
+  this.log.debug(`Starting package '${appPackage}' and activity '${appActivity}'`);
+
+  // dontStopAppOnReset is both an argument here, and a desired capability
+  // if the argument is set, use it, otherwise use the cap
+  if (!util.hasValue(dontStopAppOnReset)) {
+    dontStopAppOnReset = !!this.opts.dontStopAppOnReset;
+  }
+
+  const args = {
+    pkg: appPackage,
+    activity: appActivity,
+    waitPkg: appWaitPackage || appPackage,
+    waitActivity: appWaitActivity || appActivity,
+    action: intentAction,
+    category: intentCategory,
+    flags: intentFlags,
+    optionalIntentArguments,
+    stopApp: !dontStopAppOnReset,
+  };
+  this._cachedActivityArgs = this._cachedActivityArgs || {};
+  this._cachedActivityArgs[`${args.waitPkg}/${args.waitActivity}`] = args;
+  await this.adb.startApp(args);
+}
+
+/**
+ * Starts an Android activity using the activity manager.
+ *
+ * @param wait Set it to `true` if you want to block the method call
+ * until the activity manager's process returns the control to the system.
+ * `false` by default.
+ * @param stop Set it to `true` to force stop the target
+ * app before starting the activity. `false` by default.
+ * @param windowingMode The windowing mode to launch the activity into.
+ * Check https://android.googlesource.com/platform/frameworks/base/+/master/core/java/android/app/WindowConfiguration.java
+ * for more details on possible windowing modes (constants starting with `WINDOWING_MODE_`).
+ * @param activityType The activity type to launch the activity as.
+ * Check https://android.googlesource.com/platform/frameworks/base/+/master/core/java/android/app/WindowConfiguration.java
+ * for more details on possible activity types (constants starting with `ACTIVITY_TYPE_`).
+ * @param display The display identifier to launch the activity into.
+ * @param user The user ID for which the activity is started.
+ * @param intent The name of the activity intent to start, for example
+ * `com.some.package.name/.YourActivitySubClassName`.
+ * @param action Action name.
+ * @param pkg Package name.
+ * @param uri Unified resource identifier.
+ * @param mimeType Mime type.
+ * @param identifier Optional identifier.
+ * @param component Component name.
+ * @param categories One or more category names.
+ * @param extras Optional intent arguments. Must be represented as array of arrays,
+ * where each subarray item contains two or three string items: value type, key name and the value itself.
+ * See {@link IntentOpts} for supported value types.
+ * @param flags Intent startup-specific flags as a hexadecimal string.
+ * @returns Promise that resolves to the command output string.
+ */
+export async function mobileStartActivity(
+  this: AndroidDriver,
+  wait?: boolean,
+  stop?: boolean,
+  windowingMode?: string | number,
+  activityType?: string | number,
+  display?: number | string,
+  user?: string,
+  intent?: string,
+  action?: string,
+  pkg?: string,
+  uri?: string,
+  mimeType?: string,
+  identifier?: string,
+  component?: string,
+  categories?: string | string[],
+  extras?: string[][],
+  flags?: string,
+): Promise<string> {
+  const cmd = [
+    'am',
+    'start-activity',
+  ];
+  if (!_.isNil(user)) {
+    cmd.push('--user', String(user));
+  }
+  if (wait) {
+    cmd.push('-W');
+  }
+  if (stop) {
+    cmd.push('-S');
+  }
+  if (!_.isNil(windowingMode)) {
+    cmd.push('--windowingMode', String(windowingMode));
+  }
+  if (!_.isNil(activityType)) {
+    cmd.push('--activityType', String(activityType));
+  }
+  if (!_.isNil(display)) {
+    cmd.push('--display', String(display));
+  }
+  cmd.push(...parseIntentSpec({
+    intent,
+    action,
+    package: pkg,
+    uri,
+    mimeType,
+    identifier,
+    component,
+    categories,
+    extras,
+    flags,
+  }));
+  return await this.adb.shell(cmd);
+}
+
+/**
+ * Sends a broadcast intent to the Android system.
+ *
+ * @param receiverPermission Require receiver to hold the given permission.
+ * @param allowBackgroundActivityStarts Whether the receiver may start activities even if in the background.
+ * @param user The user ID for which the broadcast is sent.
+ * The `current` alias assumes the current user ID. `all` by default.
+ * @param intent The name of the activity intent to broadcast, for example
+ * `com.some.package.name/.YourServiceSubClassName`.
+ * @param action Action name.
+ * @param pkg Package name.
+ * @param uri Unified resource identifier.
+ * @param mimeType Mime type.
+ * @param identifier Optional identifier.
+ * @param component Component name.
+ * @param categories One or more category names.
+ * @param extras Optional intent arguments. Must be represented as array of arrays,
+ * where each subarray item contains two or three string items: value type, key name and the value itself.
+ * See {@link IntentOpts} for supported value types.
+ * @param flags Intent startup-specific flags as a hexadecimal string.
+ * @returns Promise that resolves to the command output string.
+ */
+export async function mobileBroadcast(
+  this: AndroidDriver,
+  receiverPermission?: string,
+  allowBackgroundActivityStarts?: boolean,
+  user?: string | number,
+  intent?: string,
+  action?: string,
+  pkg?: string,
+  uri?: string,
+  mimeType?: string,
+  identifier?: string,
+  component?: string,
+  categories?: string | string[],
+  extras?: string[][],
+  flags?: string,
+): Promise<string> {
+  const cmd = ['am', 'broadcast'];
+  if (!_.isNil(user)) {
+    cmd.push('--user', String(user));
+  }
+  if (receiverPermission) {
+    cmd.push('--receiver-permission', receiverPermission);
+  }
+  if (allowBackgroundActivityStarts) {
+    cmd.push('--allow-background-activity-starts');
+  }
+  cmd.push(...parseIntentSpec({
+    intent,
+    action,
+    package: pkg,
+    uri,
+    mimeType,
+    identifier,
+    component,
+    categories,
+    extras,
+    flags,
+  }));
+  return await this.adb.shell(cmd);
+}
+
+/**
+ * Starts an Android service.
+ *
+ * @param foreground Set it to `true` if your service must be started as foreground service.
+ * This option is ignored if the API level of the device under test is below 26 (Android 8).
+ * @param user The user ID for which the service is started.
+ * The `current` user id is used by default.
+ * @param intent The name of the activity intent to start, for example
+ * `com.some.package.name/.YourServiceSubClassName`.
+ * @param action Action name.
+ * @param pkg Package name.
+ * @param uri Unified resource identifier.
+ * @param mimeType Mime type.
+ * @param identifier Optional identifier.
+ * @param component Component name.
+ * @param categories One or more category names.
+ * @param extras Optional intent arguments. Must be represented as array of arrays,
+ * where each subarray item contains two or three string items: value type, key name and the value itself.
+ * See {@link IntentOpts} for supported value types.
+ * @param flags Intent startup-specific flags as a hexadecimal string.
+ * @returns Promise that resolves to the command output string.
+ */
+export async function mobileStartService(
+  this: AndroidDriver,
+  foreground?: boolean,
+  user?: string,
+  intent?: string,
+  action?: string,
+  pkg?: string,
+  uri?: string,
+  mimeType?: string,
+  identifier?: string,
+  component?: string,
+  categories?: string | string[],
+  extras?: string[][],
+  flags?: string,
+): Promise<string> {
+  const cmd = ['am'];
+  cmd.push(foreground ? 'start-foreground-service' : 'start-service');
+  if (!_.isNil(user)) {
+    cmd.push('--user', String(user));
+  }
+  cmd.push(...parseIntentSpec({
+    intent,
+    action,
+    package: pkg,
+    uri,
+    mimeType,
+    identifier,
+    component,
+    categories,
+    extras,
+    flags,
+  }));
+  return await this.adb.shell(cmd);
+}
+
+/**
+ * Stops an Android service.
+ *
+ * @param user The user ID for which the service is stopped.
+ * @param intent The name of the activity intent to stop, for example
+ * `com.some.package.name/.YourServiceSubClassName`.
+ * @param action Action name.
+ * @param pkg Package name.
+ * @param uri Unified resource identifier.
+ * @param mimeType Mime type.
+ * @param identifier Optional identifier.
+ * @param component Component name.
+ * @param categories One or more category names.
+ * @param extras Optional intent arguments. Must be represented as array of arrays,
+ * where each subarray item contains two or three string items: value type, key name and the value itself.
+ * See {@link IntentOpts} for supported value types.
+ * @param flags Intent startup-specific flags as a hexadecimal string.
+ * @returns Promise that resolves to the command output string.
+ * If the service was already stopped, returns the error message.
+ */
+export async function mobileStopService(
+  this: AndroidDriver,
+  user?: string,
+  intent?: string,
+  action?: string,
+  pkg?: string,
+  uri?: string,
+  mimeType?: string,
+  identifier?: string,
+  component?: string,
+  categories?: string | string[],
+  extras?: string[][],
+  flags?: string,
+): Promise<string> {
+  const cmd = [
+    'am',
+    'stop-service',
+  ];
+  if (!_.isNil(user)) {
+    cmd.push('--user', String(user));
+  }
+  cmd.push(...parseIntentSpec({
+    intent,
+    action,
+    package: pkg,
+    uri,
+    mimeType,
+    identifier,
+    component,
+    categories,
+    extras,
+    flags,
+  }));
+  try {
+    return await this.adb.shell(cmd);
+  } catch (e) {
+    // https://github.com/appium/appium-uiautomator2-driver/issues/792
+    const err = e as {code?: number; stderr?: string};
+    if (err.code === 255 && err.stderr?.includes('Service stopped')) {
+      return err.stderr;
+    }
+    throw e;
+  }
+}
+
+// #region Internal helpers
+
+function parseIntentSpec(opts: IntentOpts = {}): string[] {
+  const {intent, action, uri, mimeType, identifier, categories, component, extras, flags} = opts;
+  const resultArgs: string[] = [];
+  if (intent) {
+    resultArgs.push(intent);
+  }
+  if (action) {
+    resultArgs.push('-a', action);
+  }
+  if (uri) {
+    resultArgs.push('-d', uri);
+  }
+  if (mimeType) {
+    resultArgs.push('-t', mimeType);
+  }
+  if (!_.isNil(identifier)) {
+    resultArgs.push('-i', identifier);
+  }
+  if (categories) {
+    if (_.isArray(categories)) {
+      resultArgs.push(..._.flatMap(categories.map((cName) => ['-c', cName])));
+    } else {
+      resultArgs.push('-c', categories);
+    }
+  }
+  if (component) {
+    resultArgs.push('-n', component);
+  }
+  if (opts.package) {
+    resultArgs.push('-p', opts.package);
+  }
+  if (extras) {
+    if (!_.isArray(extras)) {
+      throw new errors.InvalidArgumentError(`'extras' must be an array`);
+    }
+    for (const item of extras) {
+      if (!_.isArray(item)) {
+        throw new errors.InvalidArgumentError(`Extra argument '${item}' must be an array`);
+      }
+      const [type, key, value] = item;
+      if (!SUPPORTED_EXTRA_TYPES.includes(type as any)) {
+        throw new errors.InvalidArgumentError(
+          `Extra argument type '${type}' is not known. ` +
+            `Supported intent argument types are: ${SUPPORTED_EXTRA_TYPES.join(', ')}`,
+        );
+      }
+      if (_.isEmpty(key) || (_.isString(key) && _.trim(key) === '')) {
+        throw new errors.InvalidArgumentError(
+          `Extra argument's key in '${JSON.stringify(item)}' must be a valid string identifier`,
+        );
+      }
+      if (type === NO_VALUE_ARG_TYPE) {
+        resultArgs.push(`--e${type}`, key);
+      } else if (_.isUndefined(value)) {
+        throw new errors.InvalidArgumentError(
+          `Intent argument type '${type}' in '${JSON.stringify(item)}' requires a ` +
+            `valid value to be provided`,
+        );
+      } else {
+        resultArgs.push(`--e${type}`, key, value);
+      }
+    }
+  }
+  if (flags) {
+    resultArgs.push('-f', flags);
+  }
+  return resultArgs;
+}
+
+// #endregion
+

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

@@ -2,51 +2,42 @@ import {DEFAULT_WS_PATHNAME_PREFIX, BaseDriver} from 'appium/driver';
 import _ from 'lodash';
 import os from 'node:os';
 import WebSocket from 'ws';
+import type {AppiumServer, WSServer} from '@appium/types';
+import type {EventEmitter} from 'node:events';
+import type {ADB} from 'appium-adb';
+import type {Chromedriver} from 'appium-chromedriver';
 import {
   GET_SERVER_LOGS_FEATURE,
   toLogRecord,
   nativeLogEntryToSeleniumEntry,
+  type LogEntry,
 } from '../utils';
 import { NATIVE_WIN } from './context/helpers';
 import { BIDI_EVENT_NAME } from './bidi/constants';
 import { makeLogEntryAddedEvent } from './bidi/models';
+import type {AndroidDriver} from '../driver';
 
 export const supportedLogTypes = {
   logcat: {
     description: 'Logs for Android applications on real device and emulators via ADB',
-    /**
-     *
-     * @param {import('../driver').AndroidDriver} self
-     * @returns
-     */
-    getter: (self) => /** @type {ADB} */ (self.adb).getLogcatLogs(),
+    getter: (self: AndroidDriver) => (self.adb as ADB).getLogcatLogs(),
   },
   bugreport: {
     description: `'adb bugreport' output for advanced issues diagnostic`,
-    /**
-     *
-     * @param {import('../driver').AndroidDriver} self
-     * @returns
-     */
-    getter: async (self) => {
-      const output = await /** @type {ADB} */ (self.adb).bugreport();
+    getter: async (self: AndroidDriver) => {
+      const output = await (self.adb as ADB).bugreport();
       const timestamp = Date.now();
       return output.split(os.EOL).map((x) => toLogRecord(timestamp, x));
     },
   },
   server: {
     description: 'Appium server logs',
-    /**
-     *
-     * @param {import('../driver').AndroidDriver} self
-     * @returns
-     */
-    getter: (self) => {
+    getter: (self: AndroidDriver) => {
       self.assertFeatureEnabled(GET_SERVER_LOGS_FEATURE);
       return self.log.unwrap().record.map(nativeLogEntryToSeleniumEntry);
     },
   },
-};
+} as const;
 
 /**
  * Starts Android logcat broadcast websocket on the same host and port
@@ -56,12 +47,13 @@ export const supportedLogTypes = {
  * Each connected websocket listener will receive logcat log lines
  * as soon as they are visible to Appium.
  *
- * @this {import('../driver').AndroidDriver}
- * @returns {Promise<void>}
+ * @returns Promise that resolves when the logcat broadcasting websocket is started.
  */
-export async function mobileStartLogsBroadcast() {
-  const server = /** @type {import('@appium/types').AppiumServer} */ (this.server);
-  const pathname = WEBSOCKET_ENDPOINT(/** @type {string} */ (this.sessionId));
+export async function mobileStartLogsBroadcast(
+  this: AndroidDriver,
+): Promise<void> {
+  const server = this.server as AppiumServer;
+  const pathname = WEBSOCKET_ENDPOINT(this.sessionId as string);
   if (!_.isEmpty(await server.getWebSocketHandlers(pathname))) {
     this.log.debug(`The logcat broadcasting web socket server is already listening at ${pathname}`);
     return;
@@ -78,7 +70,7 @@ export async function mobileStartLogsBroadcast() {
   wss.on('connection', (ws, req) => {
     if (req) {
       const remoteIp = _.isEmpty(req.headers['x-forwarded-for'])
-        ? req.connection?.remoteAddress
+        ? req.socket.remoteAddress
         : req.headers['x-forwarded-for'];
       this.log.debug(`Established a new logcat listener web socket connection from ${remoteIp}`);
     } else {
@@ -86,7 +78,7 @@ export async function mobileStartLogsBroadcast() {
     }
 
     if (_.isEmpty(this._logcatWebsocketListener)) {
-      this._logcatWebsocketListener = (logRecord) => {
+      this._logcatWebsocketListener = (logRecord: LogEntry) => {
         if (ws?.readyState === WebSocket.OPEN) {
           ws.send(logRecord.message);
         }
@@ -112,19 +104,20 @@ export async function mobileStartLogsBroadcast() {
       this.log.debug(closeMsg);
     });
   });
-  await server.addWebSocketHandler(pathname, /** @type {import('@appium/types').WSServer} */ (wss));
+  await server.addWebSocketHandler(pathname, wss as WSServer);
 }
 
 /**
  * Stops the previously started logcat broadcasting wesocket server.
  * This method will return immediately if no server is running.
  *
- * @this {import('../driver').AndroidDriver}
- * @returns {Promise<void>}
+ * @returns Promise that resolves when the logcat broadcasting websocket is stopped.
  */
-export async function mobileStopLogsBroadcast() {
-  const pathname = WEBSOCKET_ENDPOINT(/** @type {string} */ (this.sessionId));
-  const server = /** @type {import('@appium/types').AppiumServer} */ (this.server);
+export async function mobileStopLogsBroadcast(
+  this: AndroidDriver,
+): Promise<void> {
+  const pathname = WEBSOCKET_ENDPOINT(this.sessionId as string);
+  const server = this.server as AppiumServer;
   if (_.isEmpty(await server.getWebSocketHandlers(pathname))) {
     return;
   }
@@ -137,40 +130,53 @@ export async function mobileStopLogsBroadcast() {
 }
 
 /**
- * @this {import('../driver').AndroidDriver}
- * @returns {Promise<string[]>}
+ * Gets the list of available log types.
+ *
+ * @returns Promise that resolves to an array of log type names.
  */
-export async function getLogTypes() {
+export async function getLogTypes(
+  this: AndroidDriver,
+): Promise<string[]> {
   // XXX why doesn't `super` work here?
   const nativeLogTypes = await BaseDriver.prototype.getLogTypes.call(this);
   if (this.isWebContext()) {
-    const webLogTypes = /** @type {string[]} */ (
-      await /** @type {import('appium-chromedriver').Chromedriver} */ (
-        this.chromedriver
-      ).jwproxy.command('/log/types', 'GET')
-    );
+    const webLogTypes = await (this.chromedriver as Chromedriver).jwproxy.command('/log/types', 'GET') as string[];
     return [...nativeLogTypes, ...webLogTypes];
   }
   return nativeLogTypes;
 }
 
+export interface BiDiListenerProperties {
+  type: string;
+  srcEventName?: string;
+  context?: string;
+  entryTransformer?: (x: LogEntry) => LogEntry;
+}
+
+export type LogListener = (logEntry: LogEntry) => any;
+
 /**
+ * Assigns a BiDi log listener to an event emitter.
+ *
  * https://w3c.github.io/webdriver-bidi/#event-log-entryAdded
  *
- * @template {import('node:events').EventEmitter} EE
- * @this {import('../driver').AndroidDriver}
- * @param {EE} logEmitter
- * @param {BiDiListenerProperties} properties
- * @returns {[EE, LogListener]}
+ * @template EE The event emitter type.
+ * @param logEmitter The event emitter to attach the listener to.
+ * @param properties The BiDi listener properties.
+ * @returns A tuple containing the event emitter and the listener function.
  */
-export function assignBiDiLogListener (logEmitter, properties) {
+export function assignBiDiLogListener<EE extends EventEmitter>(
+  this: AndroidDriver,
+  logEmitter: EE,
+  properties: BiDiListenerProperties,
+): [EE, LogListener] {
   const {
     type,
     context = NATIVE_WIN,
     srcEventName = 'output',
     entryTransformer,
   } = properties;
-  const listener = (/** @type {import('../utils').LogEntry} */ logEntry) => {
+  const listener: LogListener = (logEntry: LogEntry) => {
     const finalEntry = entryTransformer ? entryTransformer(logEntry) : logEntry;
     this.eventEmitter.emit(BIDI_EVENT_NAME, makeLogEntryAddedEvent(finalEntry, context, type));
   };
@@ -179,42 +185,31 @@ export function assignBiDiLogListener (logEmitter, properties) {
 }
 
 /**
- * @this {import('../driver').AndroidDriver}
- * @param {string} logType
- * @returns {Promise<any>}
+ * Gets logs of a specific type.
+ *
+ * @param logType The type of logs to retrieve.
+ * @returns Promise that resolves to the logs for the specified type.
  */
-export async function getLog(logType) {
+export async function getLog(
+  this: AndroidDriver,
+  logType: string,
+): Promise<any> {
   if (this.isWebContext() && !_.keys(this.supportedLogTypes).includes(logType)) {
-    return await /** @type {import('appium-chromedriver').Chromedriver} */ (
-      this.chromedriver
-    ).jwproxy.command('/log', 'POST', {type: logType});
+    return await (this.chromedriver as Chromedriver).jwproxy.command('/log', 'POST', {type: logType});
   }
-  // XXX why doesn't `super` work here?
   return await BaseDriver.prototype.getLog.call(this, logType);
 }
 
 // #region Internal helpers
 
 /**
- * @param {string} sessionId
- * @returns {string}
+ * Generates the websocket endpoint path for logcat broadcasting.
+ *
+ * @param sessionId The session ID.
+ * @returns The websocket endpoint path.
  */
-const WEBSOCKET_ENDPOINT = (sessionId) =>
+const WEBSOCKET_ENDPOINT = (sessionId: string): string =>
   `${DEFAULT_WS_PATHNAME_PREFIX}/session/${sessionId}/appium/device/logcat`;
 
-
 // #endregion
 
-/**
- * @typedef {import('appium-adb').ADB} ADB
- */
-
-/**
- * @typedef {Object} BiDiListenerProperties
- * @property {string} type
- * @property {string} [srcEventName='output']
- * @property {string} [context=NATIVE_WIN]
- * @property {(x: Object) => import('../utils').LogEntry} [entryTransformer]
- */
-
-/** @typedef {(logEntry: import('../utils').LogEntry) => any} LogListener */