appium-android-driver 5.14.6 → 6.0.0

package/lib/commands/system-bars.js

@@ -1,6 +1,9 @@
+// @ts-check
+
+import {errors} from 'appium/driver';
 import _ from 'lodash';
-import { requireArgs } from '../utils';
-import { errors } from 'appium/driver';
+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.-]+)\]/;
@@ -11,31 +14,23 @@ const STATUS_BAR_WINDOW_NAME_PREFIX = 'StatusBar';
 const NAVIGATION_BAR_WINDOW_NAME_PREFIX = 'NavigationBar';
 const DEFAULT_WINDOW_PROPERTIES = {
   visible: false,
-  x: 0, y: 0, width: 0, height: 0,
+  x: 0,
+  y: 0,
+  width: 0,
+  height: 0,
 };
 
-const commands = {};
-
-/**
- * @typedef {Object} WindowProperties
- * @property {boolean} visible Whether the window is visible
- * @property {number} x Window x coordinate
- * @property {number} y Window y coordinate
- * @property {number} width Window width
- * @property {number} height Window height
- */
-
 /**
  * Parses window properties from adb dumpsys output
  *
  * @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 {Object?} log Logger instance
+ * @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 = null) {
+function parseWindowProperties(name, props, log) {
   const result = _.cloneDeep(DEFAULT_WINDOW_PROPERTIES);
   const propLines = props.join('\n');
   const frameMatch = FRAME_PATTERN.exec(propLines);
@@ -59,14 +54,17 @@ function parseWindowProperties (name, props, log = null) {
 /**
  * Extracts status and navigation bar information from the window manager output.
  *
- * @param {Array<string>} lines Output from dumpsys command.
+ * @param {string} lines Output from dumpsys command.
  * Check the corresponding unit tests for more details on the input format.
- * @param {Object?} log Logger instance
- * @return {Object} An object containing two items where keys are statusBar and navigationBar,
+ * @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 = null) {
+function parseWindows(lines, log) {
+  /**
+   * @type {StringRecord}
+   */
   const windows = {};
   let currentWindowName = null;
   for (const line of lines.split('\n').map(_.trimEnd)) {
@@ -86,11 +84,12 @@ function parseWindows (lines, log = null) {
     }
   }
   if (_.isEmpty(windows)) {
-    log?.debug(lines.join('\n'));
+    log?.debug(lines);
     throw new Error('Cannot parse any window information from the dumpsys output');
   }
 
-  const result = {statusBar: null, navigationBar: null};
+  /** @type {{statusBar?: WindowProperties, navigationBar?: WindowProperties}} */
+  const result = {};
   for (const [name, props] of _.toPairs(windows)) {
     if (name.startsWith(STATUS_BAR_WINDOW_NAME_PREFIX)) {
       result.statusBar = parseWindowProperties(name, props, log);
@@ -98,79 +97,89 @@ function parseWindows (lines, log = null) {
       result.navigationBar = parseWindowProperties(name, props, log);
     }
   }
-  const unmatchedWindows = [
+  const unmatchedWindows = /** @type {const} */ ([
     ['statusBar', STATUS_BAR_WINDOW_NAME_PREFIX],
-    ['navigationBar', NAVIGATION_BAR_WINDOW_NAME_PREFIX]
-  ].filter(([name]) => _.isNil(result[name]));
+    ['navigationBar', NAVIGATION_BAR_WINDOW_NAME_PREFIX],
+  ]).filter(([name]) => _.isNil(result[name]));
   for (const [window, namePrefix] of unmatchedWindows) {
-    log?.info(`No windows have been found whose title matches to ` +
-      `'${namePrefix}'. Assuming it is invisible. ` +
-      `Only the following windows are available: ${_.keys(windows)}`);
+    log?.info(
+      `No windows have been found whose title matches to ` +
+        `'${namePrefix}'. Assuming it is invisible. ` +
+        `Only the following windows are available: ${_.keys(windows)}`
+    );
     result[window] = _.cloneDeep(DEFAULT_WINDOW_PROPERTIES);
   }
   return result;
 }
 
-commands.getSystemBars = async function getSystemBars () {
-  let stdout;
-  try {
-    stdout = await this.adb.shell(['dumpsys', 'window', 'windows']);
-  } catch (e) {
-    throw new Error(`Cannot retrieve system bars details. Original error: ${e.message}`);
-  }
-  return parseWindows(stdout, this.log);
-};
-
-/**
- * @typedef {Object} StatusBarCommandOptions
- * @property {string} command One of supported status bar commands:
- * - expandNotifications: Open the notifications panel.
- * - expandSettings: Open the notifications panel and expand quick settings if present.
- * - collapse: Collapse the notifications and settings panel.
- * - addTile: Add a TileService of the specified component.
- * - removeTile: Remove a TileService of the specified component.
- * - clickTile: Click on a TileService of the specified component.
- * - getStatusIcons: Print the list of status bar icons and the order they appear in.
- * Each list item is separated with a new line character.
- * @property {string?} component The name of the tile component.
- * It is only required for (add|remove|click)Tile commands.
- * Example value: com.package.name/.service.QuickSettingsTileComponent
- */
-
 /**
- * Performs commands on the system status bar. A thin wrapper over
- * 'adb shell cmd statusbar' CLI. Works on Android Oreo and newer.
- *
- * @param {StatusBarCommandOptions} opts
- * @returns {Promise<string>} The actual output of the downstream console command.
+ * @type {import('./mixins').SystemBarsMixin & ThisType<import('../driver').AndroidDriver>}
+ * @satisfies {import('@appium/types').ExternalDriver}
  */
-commands.mobilePerformStatusBarCommand = async function mobilePerformStatusBarCommand (opts = {}) {
-  const {command} = requireArgs('command', opts);
+const SystemBarsMixin = {
+  async getSystemBars() {
+    /** @type {string} */
+    let stdout;
+    try {
+      stdout = await /** @type {ADB} */ (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);
+  },
 
-  const toStatusBarCommandCallable = (cmd, argsCallable = null) => async () => await this.adb.shell([
-    'cmd', 'statusbar', cmd, ...(argsCallable ? argsCallable() : [])
-  ]);
-  const tileCommandArgsCallable = () => requireArgs('component', opts).component;
-  const statusBarCommands = _.fromPairs([
-    ['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)]));
+  async mobilePerformStatusBarCommand(opts) {
+    const {command} = requireArgs('command', opts);
 
-  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)}`
+    /**
+     *
+     * @param {string} cmd
+     * @param {(() => string[]|string)} [argsCallable]
+     * @returns
+     */
+    const toStatusBarCommandCallable = (cmd, argsCallable) => async () =>
+      await /** @type {ADB} */ (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])])
     );
-  }
-  return await action();
+
+    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 { parseWindows, parseWindowProperties };
-export default commands;
+export {parseWindowProperties, parseWindows};
+
+export default SystemBarsMixin;
+
+/**
+ * @typedef {import('appium-adb').ADB} ADB
+ * @typedef {import('@appium/types').StringRecord} StringRecord
+ * @typedef {import('./types').WindowProperties} WindowProperties
+ */