appium-android-driver 7.8.3 → 8.0.0

package/lib/commands/system-bars.js

@@ -3,7 +3,6 @@
 import {errors} from 'appium/driver';
 import _ from 'lodash';
 import {requireArgs} from '../utils';
-import {mixin} from './mixins';
 
 const WINDOW_TITLE_PATTERN = /^\s+Window\s#\d+\sWindow\{[0-9a-f]+\s\w+\s([\w-]+)\}:$/;
 const FRAME_PATTERN = /\bm?[Ff]rame=\[([0-9.-]+),([0-9.-]+)\]\[([0-9.-]+),([0-9.-]+)\]/;
@@ -20,22 +19,86 @@ const DEFAULT_WINDOW_PROPERTIES = {
   height: 0,
 };
 
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @returns {Promise<StringRecord>}
+ */
+export async function getSystemBars() {
+  /** @type {string} */
+  let stdout;
+  try {
+    stdout = await this.adb.shell(['dumpsys', 'window', 'windows']);
+  } catch (e) {
+    throw new Error(
+      `Cannot retrieve system bars details. Original error: ${/** @type {Error} */ (e).message}`,
+    );
+  }
+  return parseWindows.bind(this)(stdout);
+}
+
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @param {import('./types').StatusBarCommandOpts} opts
+ * @returns {Promise<string>}
+ */
+export async function mobilePerformStatusBarCommand(opts) {
+  const {command} = requireArgs('command', opts);
+
+  /**
+   *
+   * @param {string} cmd
+   * @param {(() => string[]|string)} [argsCallable]
+   * @returns
+   */
+  const toStatusBarCommandCallable = (cmd, argsCallable) => async () =>
+    await this.adb.shell([
+      'cmd',
+      'statusbar',
+      cmd,
+      ...(argsCallable ? _.castArray(argsCallable()) : []),
+    ]);
+  const tileCommandArgsCallable = () =>
+    /** @type {string} */ (requireArgs('component', opts).component);
+  const statusBarCommands = _.fromPairs(
+    /** @type {const} */ ([
+      ['expandNotifications', ['expand-notifications']],
+      ['expandSettings', ['expand-settings']],
+      ['collapse', ['collapse']],
+      ['addTile', ['add-tile', tileCommandArgsCallable]],
+      ['removeTile', ['remove-tile', tileCommandArgsCallable]],
+      ['clickTile', ['click-tile', tileCommandArgsCallable]],
+      ['getStatusIcons', ['get-status-icons']],
+    ]).map(([name, args]) => [name, toStatusBarCommandCallable(args[0], args[1])]),
+  );
+
+  const action = statusBarCommands[command];
+  if (!action) {
+    throw new errors.InvalidArgumentError(
+      `The '${command}' status bar command is unknown. Only the following commands ` +
+        `are supported: ${_.keys(statusBarCommands)}`,
+    );
+  }
+  return await action();
+}
+
+// #region Internal helpers
+
 /**
  * Parses window properties from adb dumpsys output
  *
+ * @this {import('../driver').AndroidDriver}
  * @param {string} name The name of the window whose properties are being parsed
  * @param {Array<string>} props The list of particular window property lines.
  * Check the corresponding unit tests for more details on the input format.
- * @param {import('@appium/types').AppiumLogger} [log] Logger instance
  * @returns {WindowProperties} Parsed properties object
  * @throws {Error} If there was an issue while parsing the properties string
  */
-function parseWindowProperties(name, props, log) {
+export function parseWindowProperties(name, props) {
   const result = _.cloneDeep(DEFAULT_WINDOW_PROPERTIES);
   const propLines = props.join('\n');
   const frameMatch = FRAME_PATTERN.exec(propLines);
   if (!frameMatch) {
-    log?.debug(propLines);
+    this.log.debug(propLines);
     throw new Error(`Cannot parse the frame size from '${name}' window properties`);
   }
   result.x = parseFloat(frameMatch[1]);
@@ -44,7 +107,7 @@ function parseWindowProperties(name, props, log) {
   result.height = parseFloat(frameMatch[4]) - result.y;
   const visibilityMatch = VIEW_VISIBILITY_PATTERN.exec(propLines);
   if (!visibilityMatch) {
-    log?.debug(propLines);
+    this.log.debug(propLines);
     throw new Error(`Cannot parse the visibility value from '${name}' window properties`);
   }
   result.visible = parseInt(visibilityMatch[1], 16) === VIEW_VISIBLE;
@@ -54,14 +117,14 @@ function parseWindowProperties(name, props, log) {
 /**
  * Extracts status and navigation bar information from the window manager output.
  *
+ * @this {import('../driver').AndroidDriver}
  * @param {string} lines Output from dumpsys command.
  * Check the corresponding unit tests for more details on the input format.
- * @param {import('@appium/types').AppiumLogger} [log] Logger instance
  * @return {StringRecord} An object containing two items where keys are statusBar and navigationBar,
  * and values are corresponding WindowProperties objects
  * @throws {Error} If no window properties could be parsed
  */
-function parseWindows(lines, log) {
+export function parseWindows(lines) {
   /**
    * @type {StringRecord}
    */
@@ -84,7 +147,7 @@ function parseWindows(lines, log) {
     }
   }
   if (_.isEmpty(windows)) {
-    log?.debug(lines);
+    this.log.debug(lines);
     throw new Error('Cannot parse any window information from the dumpsys output');
   }
 
@@ -92,9 +155,9 @@ function parseWindows(lines, log) {
   const result = {};
   for (const [name, props] of _.toPairs(windows)) {
     if (name.startsWith(STATUS_BAR_WINDOW_NAME_PREFIX)) {
-      result.statusBar = parseWindowProperties(name, props, log);
+      result.statusBar = parseWindowProperties.bind(this)(name, props);
     } else if (name.startsWith(NAVIGATION_BAR_WINDOW_NAME_PREFIX)) {
-      result.navigationBar = parseWindowProperties(name, props, log);
+      result.navigationBar = parseWindowProperties.bind(this)(name, props);
     }
   }
   const unmatchedWindows = /** @type {const} */ ([
@@ -102,81 +165,17 @@ function parseWindows(lines, log) {
     ['navigationBar', NAVIGATION_BAR_WINDOW_NAME_PREFIX],
   ]).filter(([name]) => _.isNil(result[name]));
   for (const [window, namePrefix] of unmatchedWindows) {
-    log?.info(
+    this.log.info(
       `No windows have been found whose title matches to ` +
         `'${namePrefix}'. Assuming it is invisible. ` +
-        `Only the following windows are available: ${_.keys(windows)}`
+        `Only the following windows are available: ${_.keys(windows)}`,
     );
     result[window] = _.cloneDeep(DEFAULT_WINDOW_PROPERTIES);
   }
   return result;
 }
 
-/**
- * @type {import('./mixins').SystemBarsMixin & ThisType<import('../driver').AndroidDriver>}
- * @satisfies {import('@appium/types').ExternalDriver}
- */
-const SystemBarsMixin = {
-  async getSystemBars() {
-    /** @type {string} */
-    let stdout;
-    try {
-      stdout = await this.adb.shell(['dumpsys', 'window', 'windows']);
-    } catch (e) {
-      throw new Error(
-        `Cannot retrieve system bars details. Original error: ${/** @type {Error} */ (e).message}`
-      );
-    }
-    return parseWindows(stdout, this.log);
-  },
-
-  async mobilePerformStatusBarCommand(opts) {
-    const {command} = requireArgs('command', opts);
-
-    /**
-     *
-     * @param {string} cmd
-     * @param {(() => string[]|string)} [argsCallable]
-     * @returns
-     */
-    const toStatusBarCommandCallable = (cmd, argsCallable) => async () =>
-      await this.adb.shell([
-        'cmd',
-        'statusbar',
-        cmd,
-        ...(argsCallable ? _.castArray(argsCallable()) : []),
-      ]);
-    const tileCommandArgsCallable = () =>
-      /** @type {string} */ (requireArgs('component', opts).component);
-    const statusBarCommands = _.fromPairs(
-      /** @type {const} */ ([
-        ['expandNotifications', ['expand-notifications']],
-        ['expandSettings', ['expand-settings']],
-        ['collapse', ['collapse']],
-        ['addTile', ['add-tile', tileCommandArgsCallable]],
-        ['removeTile', ['remove-tile', tileCommandArgsCallable]],
-        ['clickTile', ['click-tile', tileCommandArgsCallable]],
-        ['getStatusIcons', ['get-status-icons']],
-      ]).map(([name, args]) => [name, toStatusBarCommandCallable(args[0], args[1])])
-    );
-
-    const action = statusBarCommands[command];
-    if (!action) {
-      throw new errors.InvalidArgumentError(
-        `The '${command}' status bar command is unknown. Only the following commands ` +
-          `are supported: ${_.keys(statusBarCommands)}`
-      );
-    }
-    return await action();
-  },
-};
-
-mixin(SystemBarsMixin);
-
-// for unit tests
-export {parseWindowProperties, parseWindows};
-
-export default SystemBarsMixin;
+// #endregion
 
 /**
  * @typedef {import('appium-adb').ADB} ADB

package/lib/commands/time.js

@@ -0,0 +1,36 @@
+import moment from 'moment';
+
+const MOMENT_FORMAT_ISO8601 = 'YYYY-MM-DDTHH:mm:ssZ';
+
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @param {string} [format=MOMENT_FORMAT_ISO8601]
+ * @returns {Promise<string>}
+ */
+export async function getDeviceTime(format = MOMENT_FORMAT_ISO8601) {
+  this.log.debug(
+    'Attempting to capture android device date and time. ' + `The format specifier is '${format}'`,
+  );
+  const deviceTimestamp = (await this.adb.shell(['date', '+%Y-%m-%dT%T%z'])).trim();
+  this.log.debug(`Got device timestamp: ${deviceTimestamp}`);
+  const parsedTimestamp = moment.utc(deviceTimestamp, 'YYYY-MM-DDTHH:mm:ssZZ');
+  if (!parsedTimestamp.isValid()) {
+    this.log.warn('Cannot parse the returned timestamp. Returning as is');
+    return deviceTimestamp;
+  }
+  // @ts-expect-error private API
+  return parsedTimestamp.utcOffset(parsedTimestamp._tzm || 0).format(format);
+}
+
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @param {import('./types').DeviceTimeOpts} [opts={}]
+ * @returns {Promise<string>}
+ */
+export async function mobileGetDeviceTime(opts = {}) {
+  return await this.getDeviceTime(opts.format);
+}
+
+/**
+ * @typedef {import('appium-adb').ADB} ADB
+ */