appium-android-driver 7.8.2 → 8.0.0

package/lib/commands/log.js

@@ -1,14 +1,179 @@
-// @ts-check
-
 import {DEFAULT_WS_PATHNAME_PREFIX, BaseDriver} from 'appium/driver';
 import _ from 'lodash';
 import os from 'node:os';
 import WebSocket from 'ws';
-import log from '../logger';
-import {mixin} from './mixins';
 
 const GET_SERVER_LOGS_FEATURE = 'get_server_logs';
 
+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(),
+  },
+  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();
+      const timestamp = Date.now();
+      return output.split(os.EOL).map((x) => toLogRecord(timestamp, 'ALL', x));
+    },
+  },
+  server: {
+    description: 'Appium server logs',
+    /**
+     *
+     * @param {import('../driver').AndroidDriver} self
+     * @returns
+     */
+    getter: (self) => {
+      self.ensureFeatureEnabled(GET_SERVER_LOGS_FEATURE);
+      const timestamp = Date.now();
+      return self.log
+        .unwrap()
+        .record.map((x) =>
+          toLogRecord(
+            timestamp,
+            'ALL',
+            _.isEmpty(x.prefix) ? x.message : `[${x.prefix}] ${x.message}`,
+          ),
+        );
+    },
+  },
+};
+
+/**
+ * Starts Android logcat broadcast websocket on the same host and port
+ * where Appium server is running at `/ws/session/:sessionId:/appium/logcat` endpoint. The method
+ * will return immediately if the web socket is already listening.
+ *
+ * Each connected websocket listener will receive logcat log lines
+ * as soon as they are visible to Appium.
+ *
+ * @this {import('../driver').AndroidDriver}
+ * @returns {Promise<void>}
+ */
+export async function mobileStartLogsBroadcast() {
+  const server = /** @type {import('@appium/types').AppiumServer} */ (this.server);
+  const pathname = WEBSOCKET_ENDPOINT(/** @type {string} */ (this.sessionId));
+  if (!_.isEmpty(await server.getWebSocketHandlers(pathname))) {
+    this.log.debug(`The logcat broadcasting web socket server is already listening at ${pathname}`);
+    return;
+  }
+
+  this.log.info(
+    `Starting logcat broadcasting on web socket server ` +
+      `${JSON.stringify(server.address())} to ${pathname}`,
+  );
+  // https://github.com/websockets/ws/blob/master/doc/ws.md
+  const wss = new WebSocket.Server({
+    noServer: true,
+  });
+  wss.on('connection', (ws, req) => {
+    if (req) {
+      const remoteIp = _.isEmpty(req.headers['x-forwarded-for'])
+        ? req.connection?.remoteAddress
+        : req.headers['x-forwarded-for'];
+      this.log.debug(`Established a new logcat listener web socket connection from ${remoteIp}`);
+    } else {
+      this.log.debug('Established a new logcat listener web socket connection');
+    }
+
+    if (_.isEmpty(this._logcatWebsocketListener)) {
+      this._logcatWebsocketListener = (logRecord) => {
+        if (ws?.readyState === WebSocket.OPEN) {
+          ws.send(logRecord.message);
+        }
+      };
+    }
+    this.adb.setLogcatListener(this._logcatWebsocketListener);
+
+    ws.on('close', (code, reason) => {
+      if (!_.isEmpty(this._logcatWebsocketListener)) {
+        try {
+          this.adb.removeLogcatListener(this._logcatWebsocketListener);
+        } catch (ign) {}
+        this._logcatWebsocketListener = undefined;
+      }
+
+      let closeMsg = 'Logcat listener web socket is closed.';
+      if (!_.isEmpty(code)) {
+        closeMsg += ` Code: ${code}.`;
+      }
+      if (!_.isEmpty(reason)) {
+        closeMsg += ` Reason: ${reason.toString()}.`;
+      }
+      this.log.debug(closeMsg);
+    });
+  });
+  await server.addWebSocketHandler(pathname, /** @type {import('@appium/types').WSServer} */ (wss));
+}
+
+/**
+ * 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>}
+ */
+export async function mobileStopLogsBroadcast() {
+  const pathname = WEBSOCKET_ENDPOINT(/** @type {string} */ (this.sessionId));
+  const server = /** @type {import('@appium/types').AppiumServer} */ (this.server);
+  if (_.isEmpty(await server.getWebSocketHandlers(pathname))) {
+    return;
+  }
+
+  this.log.debug(
+    `Stopping logcat broadcasting on web socket server ` +
+      `${JSON.stringify(server.address())} to ${pathname}`,
+  );
+  await server.removeWebSocketHandler(pathname);
+}
+
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @returns {Promise<string[]>}
+ */
+export async function getLogTypes() {
+  // 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')
+    );
+    return [...nativeLogTypes, ...webLogTypes];
+  }
+  return nativeLogTypes;
+}
+
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @param {string} logType
+ * @returns {Promise<any>}
+ */
+export async function getLog(logType) {
+  if (this.isWebContext() && !_.keys(this.supportedLogTypes).includes(logType)) {
+    return await /** @type {import('appium-chromedriver').Chromedriver} */ (
+      this.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}
@@ -30,169 +195,8 @@ function toLogRecord(timestamp, level, message) {
     message,
   };
 }
-/**
- * @type {import('./mixins').LogMixin & ThisType<import('../driver').AndroidDriver>}
- * @satisfies {import('@appium/types').ExternalDriver}
- */
-const LogMixin = {
-  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(),
-    },
-    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();
-        const timestamp = Date.now();
-        return output.split(os.EOL).map((x) => toLogRecord(timestamp, 'ALL', x));
-      },
-    },
-    server: {
-      description: 'Appium server logs',
-      /**
-       *
-       * @param {import('../driver').AndroidDriver} self
-       * @returns
-       */
-      getter: (self) => {
-        self.ensureFeatureEnabled(GET_SERVER_LOGS_FEATURE);
-        const timestamp = Date.now();
-        return log
-          .unwrap()
-          .record.map((x) =>
-            toLogRecord(
-              timestamp,
-              'ALL',
-              _.isEmpty(x.prefix) ? x.message : `[${x.prefix}] ${x.message}`
-            )
-          );
-      },
-    },
-  },
-
-  /**
-   * Starts Android logcat broadcast websocket on the same host and port
-   * where Appium server is running at `/ws/session/:sessionId:/appium/logcat` endpoint. The method
-   * will return immediately if the web socket is already listening.
-   *
-   * Each connected websocket listener will receive logcat log lines
-   * as soon as they are visible to Appium.
-   */
-  async mobileStartLogsBroadcast() {
-    const server = /** @type {import('@appium/types').AppiumServer} */ (this.server);
-    const pathname = WEBSOCKET_ENDPOINT(/** @type {string} */ (this.sessionId));
-    if (!_.isEmpty(await server.getWebSocketHandlers(pathname))) {
-      log.debug(`The logcat broadcasting web socket server is already listening at ${pathname}`);
-      return;
-    }
-
-    log.info(
-      `Starting logcat broadcasting on web socket server ` +
-        `${JSON.stringify(server.address())} to ${pathname}`
-    );
-    // https://github.com/websockets/ws/blob/master/doc/ws.md
-    const wss = new WebSocket.Server({
-      noServer: true,
-    });
-    wss.on('connection', (ws, req) => {
-      if (req) {
-        const remoteIp = _.isEmpty(req.headers['x-forwarded-for'])
-          ? req.connection?.remoteAddress
-          : req.headers['x-forwarded-for'];
-        log.debug(`Established a new logcat listener web socket connection from ${remoteIp}`);
-      } else {
-        log.debug('Established a new logcat listener web socket connection');
-      }
-
-      if (_.isEmpty(this._logcatWebsocketListener)) {
-        this._logcatWebsocketListener = (logRecord) => {
-          if (ws?.readyState === WebSocket.OPEN) {
-            ws.send(logRecord.message);
-          }
-        };
-      }
-      this.adb.setLogcatListener(this._logcatWebsocketListener);
-
-      ws.on('close', (code, reason) => {
-        if (!_.isEmpty(this._logcatWebsocketListener)) {
-          try {
-            this.adb.removeLogcatListener(this._logcatWebsocketListener);
-          } catch (ign) {}
-          this._logcatWebsocketListener = undefined;
-        }
-
-        let closeMsg = 'Logcat listener web socket is closed.';
-        if (!_.isEmpty(code)) {
-          closeMsg += ` Code: ${code}.`;
-        }
-        if (!_.isEmpty(reason)) {
-          closeMsg += ` Reason: ${reason.toString()}.`;
-        }
-        log.debug(closeMsg);
-      });
-    });
-    await server.addWebSocketHandler(
-      pathname,
-      /** @type {import('@appium/types').WSServer} */ (wss)
-    );
-  },
-  /**
-   * Stops the previously started logcat broadcasting wesocket server.
-   * This method will return immediately if no server is running.
-   */
-  async mobileStopLogsBroadcast() {
-    const pathname = WEBSOCKET_ENDPOINT(/** @type {string} */ (this.sessionId));
-    const server = /** @type {import('@appium/types').AppiumServer} */ (this.server);
-    if (_.isEmpty(await server.getWebSocketHandlers(pathname))) {
-      return;
-    }
-
-    log.debug(
-      `Stopping logcat broadcasting on web socket server ` +
-        `${JSON.stringify(server.address())} to ${pathname}`
-    );
-    await server.removeWebSocketHandler(pathname);
-  },
-
-  async getLogTypes() {
-    // 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')
-      );
-      return [...nativeLogTypes, ...webLogTypes];
-    }
-    return nativeLogTypes;
-  },
-
-  async getLog(logType) {
-    if (this.isWebContext() && !_.keys(this.supportedLogTypes).includes(logType)) {
-      return await /** @type {import('appium-chromedriver').Chromedriver} */ (
-        this.chromedriver
-      ).jwproxy.command('/log', 'POST', {type: logType});
-    }
-    // XXX why doesn't `super` work here?
-    return await BaseDriver.prototype.getLog.call(this, logType);
-  },
-};
-
-mixin(LogMixin);
 
-export default LogMixin;
+// #endregion
 
 /**
  * @typedef {import('appium-adb').ADB} ADB

package/lib/commands/media-projection.js

@@ -2,13 +2,85 @@ import {fs, net, util} from '@appium/support';
 import _ from 'lodash';
 import moment from 'moment';
 import path from 'node:path';
-import {mixin} from './mixins';
 
 // https://github.com/appium/io.appium.settings#internal-audio--video-recording
 const DEFAULT_EXT = '.mp4';
 const MIN_API_LEVEL = 29;
 const DEFAULT_FILENAME_FORMAT = 'YYYY-MM-DDTHH-mm-ss';
 
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @param {import('./types').StartMediaProjectionRecordingOpts} [options={}]
+ * @returns {Promise<boolean>}
+ */
+export async function mobileStartMediaProjectionRecording(options = {}) {
+  await verifyMediaProjectionRecordingIsSupported(this.adb);
+
+  const {resolution, priority, maxDurationSec, filename} = options;
+  const recorder = this.settingsApp.makeMediaProjectionRecorder();
+  const fname = adjustMediaExtension(filename || moment().format(DEFAULT_FILENAME_FORMAT));
+  const didStart = await recorder.start({
+    resolution,
+    priority,
+    maxDurationSec,
+    filename: fname,
+  });
+  if (didStart) {
+    this.log.info(`A new media projection recording '${fname}' has been successfully started`);
+  } else {
+    this.log.info(
+      'Another media projection recording is already in progress. There is nothing to start',
+    );
+  }
+  return didStart;
+}
+
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @returns {Promise<boolean>}
+ */
+export async function mobileIsMediaProjectionRecordingRunning() {
+  await verifyMediaProjectionRecordingIsSupported(this.adb);
+
+  const recorder = this.settingsApp.makeMediaProjectionRecorder();
+  return await recorder.isRunning();
+}
+
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @param {import('./types').StopMediaProjectionRecordingOpts} [options={}]
+ * @returns {Promise<string>}
+ */
+export async function mobileStopMediaProjectionRecording(options = {}) {
+  await verifyMediaProjectionRecordingIsSupported(this.adb);
+
+  const recorder = this.settingsApp.makeMediaProjectionRecorder();
+  if (await recorder.stop()) {
+    this.log.info('Successfully stopped a media projection recording. Pulling the recorded media');
+  } else {
+    this.log.info('Media projection recording is not running. There is nothing to stop');
+  }
+  const recentRecordingPath = await recorder.pullRecent();
+  if (!recentRecordingPath) {
+    throw new Error(`No recent media projection recording have been found. Did you start any?`);
+  }
+
+  const {remotePath} = options;
+  if (_.isEmpty(remotePath)) {
+    const {size} = await fs.stat(recentRecordingPath);
+    this.log.debug(
+      `The size of the resulting media projection recording is ${util.toReadableSizeString(size)}`,
+    );
+  }
+  try {
+    return await uploadRecordedMedia(recentRecordingPath, remotePath, options);
+  } finally {
+    await fs.rimraf(path.dirname(recentRecordingPath));
+  }
+}
+
+// #region Internal helpers
+
 /**
  *
  * @param {string} localFile
@@ -65,79 +137,12 @@ async function verifyMediaProjectionRecordingIsSupported(adb) {
   if (apiLevel < MIN_API_LEVEL) {
     throw new Error(
       `Media projection-based recording is not available on API Level ${apiLevel}. ` +
-        `Minimum required API Level is ${MIN_API_LEVEL}.`
+        `Minimum required API Level is ${MIN_API_LEVEL}.`,
     );
   }
 }
 
-/**
- * @type {import('./mixins').MediaProjectionMixin & ThisType<import('../driver').AndroidDriver>}
- * @satisfies {import('@appium/types').ExternalDriver}
- */
-const MediaProjectionMixin = {
-  async mobileStartMediaProjectionRecording(options = {}) {
-    await verifyMediaProjectionRecordingIsSupported(this.adb);
-
-    const {resolution, priority, maxDurationSec, filename} = options;
-    const recorder = this.settingsApp.makeMediaProjectionRecorder();
-    const fname = adjustMediaExtension(filename || moment().format(DEFAULT_FILENAME_FORMAT));
-    const didStart = await recorder.start({
-      resolution,
-      priority,
-      maxDurationSec,
-      filename: fname,
-    });
-    if (didStart) {
-      this.log.info(`A new media projection recording '${fname}' has been successfully started`);
-    } else {
-      this.log.info(
-        'Another media projection recording is already in progress. There is nothing to start'
-      );
-    }
-    return didStart;
-  },
-
-  async mobileIsMediaProjectionRecordingRunning() {
-    await verifyMediaProjectionRecordingIsSupported(this.adb);
-
-    const recorder = this.settingsApp.makeMediaProjectionRecorder();
-    return await recorder.isRunning();
-  },
-
-  async mobileStopMediaProjectionRecording(options = {}) {
-    await verifyMediaProjectionRecordingIsSupported(this.adb);
-
-    const recorder = this.settingsApp.makeMediaProjectionRecorder();
-    if (await recorder.stop()) {
-      this.log.info(
-        'Successfully stopped a media projection recording. Pulling the recorded media'
-      );
-    } else {
-      this.log.info('Media projection recording is not running. There is nothing to stop');
-    }
-    const recentRecordingPath = await recorder.pullRecent();
-    if (!recentRecordingPath) {
-      throw new Error(`No recent media projection recording have been found. Did you start any?`);
-    }
-
-    const {remotePath} = options;
-    if (_.isEmpty(remotePath)) {
-      const {size} = await fs.stat(recentRecordingPath);
-      this.log.debug(
-        `The size of the resulting media projection recording is ${util.toReadableSizeString(size)}`
-      );
-    }
-    try {
-      return await uploadRecordedMedia(recentRecordingPath, remotePath, options);
-    } finally {
-      await fs.rimraf(path.dirname(recentRecordingPath));
-    }
-  },
-};
-
-mixin(MediaProjectionMixin);
-
-export default MediaProjectionMixin;
+// #endregion
 
 /**
  * @typedef {import('appium-adb').ADB} ADB

package/lib/commands/memory.js

@@ -1,38 +1,26 @@
 import {errors} from 'appium/driver';
-import {mixin} from './mixins';
 
 /**
- * @type {import('./mixins').MemoryMixin & ThisType<import('../driver').AndroidDriver>}
- * @satisfies {import('@appium/types').ExternalDriver}
+ * Simulates the onTrimMemory() event for the given package.
+ * Read https://developer.android.com/topic/performance/memory
+ * for more details.
+ *
+ * @this {import('../driver').AndroidDriver}
+ * @param {import('./types').SendTrimMemoryOpts} opts
+ * @returns {Promise<void>}
  */
-const MemoryMixin = {
-  /**
-   * Simulates the onTrimMemory() event for the given package.
-   * Read https://developer.android.com/topic/performance/memory
-   * for more details.
-   *
-   * @param {import('./types').SendTrimMemoryOpts} opts
-   */
-  async mobileSendTrimMemory(opts) {
-    const {
-      pkg,
-      level,
-    } = opts;
+export async function mobileSendTrimMemory(opts) {
+  const {pkg, level} = opts;
 
-    if (!pkg) {
-      throw new errors.InvalidArgumentError(`The 'pkg' argument must be provided`);
-    }
-    if (!level) {
-      throw new errors.InvalidArgumentError(`The 'level' argument must be provided`);
-    }
+  if (!pkg) {
+    throw new errors.InvalidArgumentError(`The 'pkg' argument must be provided`);
+  }
+  if (!level) {
+    throw new errors.InvalidArgumentError(`The 'level' argument must be provided`);
+  }
 
-    await this.adb.shell(['am', 'send-trim-memory', pkg, level]);
-  },
-};
-
-mixin(MemoryMixin);
-
-export default MemoryMixin;
+  await this.adb.shell(['am', 'send-trim-memory', pkg, level]);
+}
 
 /**
  * @typedef {import('appium-adb').ADB} ADB

package/lib/commands/misc.js

@@ -0,0 +1,94 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+import _ from 'lodash';
+import {errors} from 'appium/driver';
+
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @returns {Promise<import('@appium/types').Size>}
+ */
+export async function getWindowSize() {
+  throw new errors.NotImplementedError('Not implemented');
+}
+
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @returns {Promise<import('@appium/types').Rect>}
+ */
+export async function getWindowRect() {
+  const {width, height} = await this.getWindowSize();
+  return {
+    width,
+    height,
+    x: 0,
+    y: 0,
+  };
+}
+
+/**
+ * we override setUrl to take an android URI which can be used for deep-linking
+ * inside an app, similar to starting an intent
+ *
+ * @this {import('../driver').AndroidDriver}
+ * @param {string} uri
+ * @returns {Promise<void>}
+ */
+export async function setUrl(uri) {
+  await this.adb.startUri(uri, /** @type {string} */ (this.opts.appPackage));
+}
+
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @returns {Promise<number>}
+ */
+export async function getDisplayDensity() {
+  // first try the property for devices
+  let out = await this.adb.shell(['getprop', 'ro.sf.lcd_density']);
+  if (out) {
+    let val = parseInt(out, 10);
+    // if the value is NaN, try getting the emulator property
+    if (!isNaN(val)) {
+      return val;
+    }
+    this.log.debug(`Parsed density value was NaN: "${out}"`);
+  }
+  // fallback to trying property for emulators
+  out = await this.adb.shell(['getprop', 'qemu.sf.lcd_density']);
+  if (out) {
+    let val = parseInt(out, 10);
+    if (!isNaN(val)) {
+      return val;
+    }
+    this.log.debug(`Parsed density value was NaN: "${out}"`);
+  }
+  // couldn't get anything, so error out
+  throw this.log.errorAndThrow('Failed to get display density property.');
+}
+
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @returns {Promise<StringRecord>}
+ */
+export async function mobileGetNotifications() {
+  return await this.settingsApp.getNotifications();
+}
+
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @returns {Promise<import('./types').SmsListResult>}
+ */
+export async function mobileListSms(opts) {
+  return await this.settingsApp.getSmsList(opts);
+}
+
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @returns {Promise<void>}
+ */
+export async function openNotifications() {
+  throw new errors.NotImplementedError('Not implemented');
+}
+
+/**
+ * @typedef {import('appium-adb').ADB} ADB
+ * @typedef {import('@appium/types').StringRecord} StringRecord
+ */