appium-android-driver 5.14.7 → 6.0.0

package/lib/commands/performance.js

@@ -1,27 +1,50 @@
+// @ts-check
+import {retryInterval} from 'asyncbox';
 import _ from 'lodash';
-import { retryInterval } from 'asyncbox';
-import { requireArgs } from '../utils';
-
-const commands = {};
+import {requireArgs} from '../utils';
+import {mixin} from './mixins';
 
 const NETWORK_KEYS = [
-  ['bucketStart', 'activeTime', 'rxBytes', 'rxPackets', 'txBytes', 'txPackets', 'operations', 'bucketDuration'],
-  ['st', 'activeTime', 'rb', 'rp', 'tb', 'tp', 'op', 'bucketDuration']
+  [
+    'bucketStart',
+    'activeTime',
+    'rxBytes',
+    'rxPackets',
+    'txBytes',
+    'txPackets',
+    'operations',
+    'bucketDuration',
+  ],
+  ['st', 'activeTime', 'rb', 'rp', 'tb', 'tp', 'op', 'bucketDuration'],
 ];
-const CPU_KEYS = ['user', 'kernel'];
+const CPU_KEYS = /** @type {const} */ (['user', 'kernel']);
 const BATTERY_KEYS = ['power'];
 const MEMORY_KEYS = [
-  'totalPrivateDirty', 'nativePrivateDirty', 'dalvikPrivateDirty',
-  'eglPrivateDirty', 'glPrivateDirty',
-  'totalPss', 'nativePss', 'dalvikPss', 'eglPss', 'glPss',
-  'nativeHeapAllocatedSize', 'nativeHeapSize',
-  'nativeRss', 'dalvikRss', 'totalRss'
+  'totalPrivateDirty',
+  'nativePrivateDirty',
+  'dalvikPrivateDirty',
+  'eglPrivateDirty',
+  'glPrivateDirty',
+  'totalPss',
+  'nativePss',
+  'dalvikPss',
+  'eglPss',
+  'glPss',
+  'nativeHeapAllocatedSize',
+  'nativeHeapSize',
+  'nativeRss',
+  'dalvikRss',
+  'totalRss',
 ];
 const SUPPORTED_PERFORMANCE_DATA_TYPES = Object.freeze({
-  cpuinfo: 'the amount of cpu by user and kernel process - cpu information for applications on real devices and simulators',
-  memoryinfo: 'the amount of memory used by the process - memory information for applications on real devices and simulators',
-  batteryinfo: 'the remaining battery power - battery power information for applications on real devices and simulators',
-  networkinfo: 'the network statistics - network rx/tx information for applications on real devices and simulators'
+  cpuinfo:
+    'the amount of cpu by user and kernel process - cpu information for applications on real devices and simulators',
+  memoryinfo:
+    'the amount of memory used by the process - memory information for applications on real devices and simulators',
+  batteryinfo:
+    'the remaining battery power - battery power information for applications on real devices and simulators',
+  networkinfo:
+    'the network statistics - network rx/tx information for applications on real devices and simulators',
 });
 const MEMINFO_TITLES = Object.freeze({
   NATIVE: 'Native',
@@ -30,7 +53,7 @@ const MEMINFO_TITLES = Object.freeze({
   GL: 'GL',
   MTRACK: 'mtrack',
   TOTAL: 'TOTAL',
-  HEAP: 'Heap'
+  HEAP: 'Heap',
 });
 const RETRY_PAUSE_MS = 1000;
 
@@ -40,16 +63,26 @@ const RETRY_PAUSE_MS = 1000;
  * except 'TOTAL', which skips the second type name
  * !!! valDict gets mutated
  */
-function parseMeminfoForApi19To29 (entries, valDict) {
+// @ts-expect-error FIXME: type this properly
+function parseMeminfoForApi19To29(entries, valDict) {
   const [type, subType] = entries;
   if (type === MEMINFO_TITLES.NATIVE && subType === MEMINFO_TITLES.HEAP) {
-    [,, valDict.nativePss, valDict.nativePrivateDirty,,, valDict.nativeHeapSize, valDict.nativeHeapAllocatedSize] = entries;
+    [
+      ,
+      ,
+      valDict.nativePss,
+      valDict.nativePrivateDirty,
+      ,
+      ,
+      valDict.nativeHeapSize,
+      valDict.nativeHeapAllocatedSize,
+    ] = entries;
   } else if (type === MEMINFO_TITLES.DALVIK && subType === MEMINFO_TITLES.HEAP) {
-    [,, valDict.dalvikPss, valDict.dalvikPrivateDirty] = entries;
+    [, , valDict.dalvikPss, valDict.dalvikPrivateDirty] = entries;
   } else if (type === MEMINFO_TITLES.EGL && subType === MEMINFO_TITLES.MTRACK) {
-    [,, valDict.eglPss, valDict.eglPrivateDirty] = entries;
+    [, , valDict.eglPss, valDict.eglPrivateDirty] = entries;
   } else if (type === MEMINFO_TITLES.GL && subType === MEMINFO_TITLES.MTRACK) {
-    [,, valDict.glPss, valDict.glPrivateDirty] = entries;
+    [, , valDict.glPss, valDict.glPrivateDirty] = entries;
   } else if (type === MEMINFO_TITLES.TOTAL && entries.length === 8) {
     // there are two totals, and we only want the full listing, which has 8 entries
     [, valDict.totalPss, valDict.totalPrivateDirty] = entries;
@@ -60,18 +93,26 @@ function parseMeminfoForApi19To29 (entries, valDict) {
  * ['<System Type', '<pps>', '<shared dirty>', '<private dirty>', '<heap size>', '<heap alloc>', '<heap free>']
  * !!! valDict gets mutated
  */
-function parseMeminfoForApiBelow19 (entries, valDict) {
+// @ts-expect-error FIXME: type this properly
+function parseMeminfoForApiBelow19(entries, valDict) {
   const type = entries[0];
   if (type === MEMINFO_TITLES.NATIVE) {
-    [, valDict.nativePss,, valDict.nativePrivateDirty, valDict.nativeHeapSize, valDict.nativeHeapAllocatedSize] = entries;
+    [
+      ,
+      valDict.nativePss,
+      ,
+      valDict.nativePrivateDirty,
+      valDict.nativeHeapSize,
+      valDict.nativeHeapAllocatedSize,
+    ] = entries;
   } else if (type === MEMINFO_TITLES.DALVIK) {
-    [, valDict.dalvikPss,, valDict.dalvikPrivateDirty] = entries;
+    [, valDict.dalvikPss, , valDict.dalvikPrivateDirty] = entries;
   } else if (type === MEMINFO_TITLES.EGL) {
-    [, valDict.eglPss,, valDict.eglPrivateDirty] = entries;
+    [, valDict.eglPss, , valDict.eglPrivateDirty] = entries;
   } else if (type === MEMINFO_TITLES.GL) {
-    [, valDict.glPss,, valDict.glPrivateDirty] = entries;
+    [, valDict.glPss, , valDict.glPrivateDirty] = entries;
   } else if (type === MEMINFO_TITLES.TOTAL) {
-    [, valDict.totalPss,, valDict.totalPrivateDirty] = entries;
+    [, valDict.totalPss, , valDict.totalPrivateDirty] = entries;
   }
 }
 
@@ -80,36 +121,57 @@ function parseMeminfoForApiBelow19 (entries, valDict) {
  * ['<System Type>', '<Memory Type>', <pss total>, <private dirty>, <private clean>, <swapPss dirty>, <rss total>, <heap size>, <heap alloc>, <heap free>]
  * !!! valDict gets mutated
  */
-function parseMeminfoForApiAbove29 (entries, valDict) {
+// @ts-expect-error FIXME: type this properly
+function parseMeminfoForApiAbove29(entries, valDict) {
   const [type, subType] = entries;
   if (type === MEMINFO_TITLES.NATIVE && subType === MEMINFO_TITLES.HEAP) {
-    [,, valDict.nativePss, valDict.nativePrivateDirty,,, valDict.nativeRss, valDict.nativeHeapSize, valDict.nativeHeapAllocatedSize] = entries;
+    [
+      ,
+      ,
+      valDict.nativePss,
+      valDict.nativePrivateDirty,
+      ,
+      ,
+      valDict.nativeRss,
+      valDict.nativeHeapSize,
+      valDict.nativeHeapAllocatedSize,
+    ] = entries;
   } else if (type === MEMINFO_TITLES.DALVIK && subType === MEMINFO_TITLES.HEAP) {
-    [,, valDict.dalvikPss, valDict.dalvikPrivateDirty,,, valDict.dalvikRss] = entries;
+    [, , valDict.dalvikPss, valDict.dalvikPrivateDirty, , , valDict.dalvikRss] = entries;
   } else if (type === MEMINFO_TITLES.EGL && subType === MEMINFO_TITLES.MTRACK) {
-    [,, valDict.eglPss, valDict.eglPrivateDirty] = entries;
+    [, , valDict.eglPss, valDict.eglPrivateDirty] = entries;
   } else if (type === MEMINFO_TITLES.GL && subType === MEMINFO_TITLES.MTRACK) {
-    [,, valDict.glPss, valDict.glPrivateDirty] = entries;
+    [, , valDict.glPss, valDict.glPrivateDirty] = entries;
   } else if (type === MEMINFO_TITLES.TOTAL && entries.length === 9) {
     // has 9 entries
-    [, valDict.totalPss, valDict.totalPrivateDirty,,, valDict.totalRss] = entries;
+    [, valDict.totalPss, valDict.totalPrivateDirty, , , valDict.totalRss] = entries;
   }
 }
 
-async function getMemoryInfo (packageName, retries = 2) {
+/**
+ *
+ * @this {AndroidDriver}
+ * @param {string} packageName
+ * @param {number} retries
+ */
+async function getMemoryInfo(packageName, retries = 2) {
   return await retryInterval(retries, RETRY_PAUSE_MS, async () => {
     const cmd = [
-      'dumpsys', 'meminfo', `'${packageName}'`,
-      '|', 'grep', '-E',
+      'dumpsys',
+      'meminfo',
+      `'${packageName}'`,
+      '|',
+      'grep',
+      '-E',
       `'${MEMINFO_TITLES.NATIVE}|${MEMINFO_TITLES.DALVIK}|${MEMINFO_TITLES.EGL}` +
-      `|${MEMINFO_TITLES.GL}|${MEMINFO_TITLES.TOTAL}'`
+        `|${MEMINFO_TITLES.GL}|${MEMINFO_TITLES.TOTAL}'`,
     ];
-    const data = await this.adb.shell(cmd);
+    const data = await /** @type {ADB} */ (this.adb).shell(cmd);
     if (!data) {
       throw new Error('No data from dumpsys');
     }
     const valDict = {totalPrivateDirty: ''};
-    const apiLevel = await this.adb.getApiLevel();
+    const apiLevel = await /** @type {ADB} */ (this.adb).getApiLevel();
     for (const line of data.split('\n')) {
       const entries = line.trim().split(/\s+/).filter(Boolean);
       if (apiLevel >= 30) {
@@ -122,25 +184,26 @@ async function getMemoryInfo (packageName, retries = 2) {
     }
     if (valDict.totalPrivateDirty && valDict.totalPrivateDirty !== 'nodex') {
       const headers = _.clone(MEMORY_KEYS);
+      // @ts-expect-error FIXME: don't want to deal w/ it
       const values = headers.map((header) => valDict[header]);
       return [headers, values];
     }
 
     throw new Error(`Unable to parse memory data: '${data}'`);
   });
-};
+}
 
 /**
  * @this {AndroidDriver}
  * @param {number} retries
  */
-async function getNetworkTrafficInfo (retries = 2) {
+async function getNetworkTrafficInfo(retries = 2) {
   return await retryInterval(retries, RETRY_PAUSE_MS, async () => {
     let returnValue = [];
     let bucketDuration, bucketStart, activeTime, rxBytes, rxPackets, txBytes, txPackets, operations;
 
     let cmd = ['dumpsys', 'netstats'];
-    let data = await this.adb.shell(cmd);
+    let data = await /** @type {ADB} */ (this.adb).shell(cmd);
     if (!data) throw new Error('No data from dumpsys'); //eslint-disable-line curly
 
     // In case of network traffic information, it is different for the return data between emulator and real device.
@@ -200,7 +263,7 @@ async function getNetworkTrafficInfo (retries = 2) {
 
           if (start >= 0) {
             index = j;
-            returnValue[0] = [];
+            returnValue[0] = /** @type {string[]} */ ([]);
 
             for (let k = 0; k < NETWORK_KEYS[j].length; ++k) {
               returnValue[0][k] = NETWORK_KEYS[j][k];
@@ -270,16 +333,28 @@ async function getNetworkTrafficInfo (retries = 2) {
                 delimiter = data.indexOf('=', start + 1);
                 end = data.length;
                 operations = data.substring(delimiter + 1, end).trim();
-
               }
             }
-            returnValue[returnIndex++] = [bucketStart, activeTime, rxBytes, rxPackets, txBytes, txPackets, operations, bucketDuration];
+            returnValue[returnIndex++] = [
+              bucketStart,
+              activeTime,
+              rxBytes,
+              rxPackets,
+              txBytes,
+              txPackets,
+              operations,
+              bucketDuration,
+            ];
           }
         }
       }
     }
 
-    if (!_.isEqual(pendingBytes, '') && !_.isUndefined(pendingBytes) && !_.isEqual(pendingBytes, 'nodex')) {
+    if (
+      !_.isEqual(pendingBytes, '') &&
+      !_.isUndefined(pendingBytes) &&
+      !_.isEqual(pendingBytes, 'nodex')
+    ) {
       return returnValue;
     } else {
       throw new Error(`Unable to parse network traffic data: '${data}'`);
@@ -300,37 +375,48 @@ async function getNetworkTrafficInfo (retries = 2) {
  * @this {AndroidDriver}
  * @param {string} packageName The package name to get the CPU information.
  * @param {number} retries The number of retry count.
- * @returns {Array} The array of the parsed CPU upsage percentages.
+ * @returns {Promise<[typeof CPU_KEYS, [user: string, kernel: string]]>} The array of the parsed CPU upsage percentages.
  *                  e.g. ['cpuinfo', ['14.3', '28.2']]
  *                  '14.3' is usage by the user (%), '28.2' is usage by the kernel (%)
- * @throw {Error} If it failed to parse the result of dumpsys, or no package name exists.
+ * @throws {Error} If it failed to parse the result of dumpsys, or no package name exists.
  */
-async function getCPUInfo (packageName, retries = 2) {
+async function getCPUInfo(packageName, retries = 2) {
   // TODO: figure out why this is
   // sometimes, the function of 'adb.shell' fails. when I tested this function on the target of 'Galaxy Note5',
   // adb.shell(dumpsys cpuinfo) returns cpu datas for other application packages, but I can't find the data for packageName.
   // It usually fails 30 times and success for the next time,
   // Since then, he has continued to succeed.
+
+  // @ts-expect-error retryInterval says it can return `null`, but it doesn't look like it actually can.
+  // FIXME: fix this in asyncbox
   return await retryInterval(retries, RETRY_PAUSE_MS, async () => {
+    /** @type {string} */
     let output;
     try {
-      output = await this.adb.shell(['dumpsys', 'cpuinfo']);
+      output = await /** @type {ADB} */ (this.adb).shell(['dumpsys', 'cpuinfo']);
     } catch (e) {
-      if (e.stderr) {
-        this.log.info(e.stderr);
+      const err = /** @type {import('teen_process').ExecError} */ (e);
+      if (err.stderr) {
+        this.log.info(err.stderr);
       }
       throw e;
     }
     // `output` will be something like
     //    +0% 2209/io.appium.android.apis: 0.1% user + 0.2% kernel / faults: 70 minor
-    const usagesPattern =
-      new RegExp(`^.+\\/${_.escapeRegExp(packageName)}:\\D+([\\d.]+)%\\s+user\\s+\\+\\s+([\\d.]+)%\\s+kernel`, 'm');
+    const usagesPattern = new RegExp(
+      `^.+\\/${_.escapeRegExp(packageName)}:\\D+([\\d.]+)%\\s+user\\s+\\+\\s+([\\d.]+)%\\s+kernel`,
+      'm'
+    );
     const match = usagesPattern.exec(output);
     if (!match) {
       this.log.debug(output);
-      throw new Error(`Unable to parse cpu usage data for '${packageName}'. Check the server log for more details`);
+      throw new Error(
+        `Unable to parse cpu usage data for '${packageName}'. Check the server log for more details`
+      );
     }
-    return [CPU_KEYS, [match[1], match[2]]];
+    const user = /** @type {string} */ (match[1]);
+    const kernel = /** @type {string} */ (match[2]);
+    return [CPU_KEYS, [user, kernel]];
   });
 }
 
@@ -338,10 +424,10 @@ async function getCPUInfo (packageName, retries = 2) {
  * @this {AndroidDriver}
  * @param {number} retries
  */
-async function getBatteryInfo (retries = 2) {
+async function getBatteryInfo(retries = 2) {
   return await retryInterval(retries, RETRY_PAUSE_MS, async () => {
     let cmd = ['dumpsys', 'battery', '|', 'grep', 'level'];
-    let data = await this.adb.shell(cmd);
+    let data = await /** @type {ADB} */ (this.adb).shell(cmd);
     if (!data) throw new Error('No data from dumpsys'); //eslint-disable-line curly
 
     let power = parseInt((data.split(':')[1] || '').trim(), 10);
@@ -354,83 +440,68 @@ async function getBatteryInfo (retries = 2) {
   });
 }
 
-//
-// returns the information type of the system state which is supported to read as like cpu, memory, network traffic, and battery.
-// output - array like below
-// [cpuinfo, batteryinfo, networkinfo, memoryinfo]
-//
-commands.getPerformanceDataTypes = function getPerformanceDataTypes () {
-  return _.keys(SUPPORTED_PERFORMANCE_DATA_TYPES);
-};
-
-/**
- * @returns The information type of the system state which is supported to read as like cpu, memory, network traffic, and battery.
- * input - (packageName) the package name of the application
- *        (dataType) the type of system state which wants to read. It should be one of the keys of the SUPPORTED_PERFORMANCE_DATA_TYPES
- *        (dataReadTimeout) the number of attempts to read
- * output - table of the performance data, The first line of the table represents the type of data. The remaining lines represent the values of the data.
- *
- * in case of battery info : [[power], [23]]
- * in case of memory info :  [[totalPrivateDirty, nativePrivateDirty, dalvikPrivateDirty, eglPrivateDirty, glPrivateDirty, totalPss,
- *   nativePss, dalvikPss, eglPss, glPss, nativeHeapAllocatedSize, nativeHeapSize], [18360, 8296, 6132, null, null, 42588, 8406, 7024, null, null, 26519, 10344]]
- * in case of network info : [[bucketStart, activeTime, rxBytes, rxPackets, txBytes, txPackets, operations, bucketDuration,],
- *   [1478091600000, null, 1099075, 610947, 928, 114362, 769, 0, 3600000], [1478095200000, null, 1306300, 405997, 509, 46359, 370, 0, 3600000]]
- * in case of network info : [[st, activeTime, rb, rp, tb, tp, op, bucketDuration], [1478088000, null, null, 32115296, 34291, 2956805, 25705, 0, 3600],
- *   [1478091600, null, null, 2714683, 11821, 1420564, 12650, 0, 3600], [1478095200, null, null, 10079213, 19962, 2487705, 20015, 0, 3600],
- *   [1478098800, null, null, 4444433, 10227, 1430356, 10493, 0, 3600]]
- * in case of cpu info : [[user, kernel], [0.9, 1.3]]
- */
-commands.getPerformanceData = async function getPerformanceData (packageName, dataType, retries = 2) {
-  switch (_.toLower(dataType)) {
-    case 'batteryinfo':
-      return await getBatteryInfo.bind(this)(retries);
-    case 'cpuinfo':
-      return await getCPUInfo.bind(this)(packageName, retries);
-    case 'memoryinfo':
-      return await getMemoryInfo.bind(this)(packageName, retries);
-    case 'networkinfo':
-      return await getNetworkTrafficInfo.bind(this)(retries);
-    default:
-      throw new Error(`No performance data of type '${dataType}' found. ` +
-        `Only the following values are supported: ${JSON.stringify(SUPPORTED_PERFORMANCE_DATA_TYPES, ' ', 2)}`);
-  }
-};
-
 /**
- * @typedef {Object} PerformanceDataOptions
- * @property {string} packageName The name of the package identifier to fetch the data for
- * @property {'batteryinfo' | 'cpuinfo' | 'memoryinfo' | 'networkinfo'} dataType One of supported subsystem
- * to fetch the data for.
+ * @type {import('./mixins').PerformanceMixin & ThisType<import('../driver').AndroidDriver>}
+ * @satisfies {import('@appium/types').ExternalDriver}
  */
+const PerformanceMixin = {
+  async getPerformanceDataTypes() {
+    return /** @type {import('./types').PerformanceDataType[]} */ (
+      _.keys(SUPPORTED_PERFORMANCE_DATA_TYPES)
+    );
+  },
+
+  async getPerformanceData(packageName, dataType, retries = 2) {
+    let result;
+    switch (_.toLower(dataType)) {
+      case 'batteryinfo':
+        result = await getBatteryInfo.call(this, retries);
+        break;
+      case 'cpuinfo':
+        result = await getCPUInfo.call(this, packageName, retries);
+        break;
+      case 'memoryinfo':
+        result = await getMemoryInfo.call(this, packageName, retries);
+        break;
+      case 'networkinfo':
+        result = await getNetworkTrafficInfo.call(this, retries);
+        break;
+      default:
+        throw new Error(
+          `No performance data of type '${dataType}' found. ` +
+            `Only the following values are supported: ${JSON.stringify(
+              SUPPORTED_PERFORMANCE_DATA_TYPES,
+              [' '],
+              2
+            )}`
+        );
+    }
+    return /** @type {any[][]} */ (result);
+  },
 
-/**
- * Retrieves performance data about the given Android subsystem.
- * The data is parsed from the output of the dumpsys utility.
- *
- * @param {PerformanceDataOptions} opts
- * @returns {Promise<any[][]>} The output depends on the selected subsystem.
- * It is orginized into a table, where the first row represent column names
- * and the following rows represent the sampled data for each column.
- * Example output for different data types:
- * - batteryinfo: [[power], [23]]
- * - memory info: [[totalPrivateDirty, nativePrivateDirty, dalvikPrivateDirty, eglPrivateDirty, glPrivateDirty, totalPss,
- *   nativePss, dalvikPss, eglPss, glPss, nativeHeapAllocatedSize, nativeHeapSize], [18360, 8296, 6132, null, null, 42588, 8406, 7024, null, null, 26519, 10344]]
- * - networkinfo: [[bucketStart, activeTime, rxBytes, rxPackets, txBytes, txPackets, operations, bucketDuration,],
- *   [1478091600000, null, 1099075, 610947, 928, 114362, 769, 0, 3600000], [1478095200000, null, 1306300, 405997, 509, 46359, 370, 0, 3600000]]
- *
- *   [[st, activeTime, rb, rp, tb, tp, op, bucketDuration], [1478088000, null, null, 32115296, 34291, 2956805, 25705, 0, 3600],
- *   [1478091600, null, null, 2714683, 11821, 1420564, 12650, 0, 3600], [1478095200, null, null, 10079213, 19962, 2487705, 20015, 0, 3600],
- *   [1478098800, null, null, 4444433, 10227, 1430356, 10493, 0, 3600]]
- * - cpuinfo: [[user, kernel], [0.9, 1.3]]
- */
-commands.mobileGetPerformanceData = async function mobileGetPerformanceData (opts = {}) {
-  const { packageName, dataType } = requireArgs(['packageName', 'dataType'], opts);
-  return await this.getPerformanceData(packageName, dataType);
+  async mobileGetPerformanceData(opts) {
+    const {packageName, dataType} = requireArgs(['packageName', 'dataType'], opts);
+    return await this.getPerformanceData(packageName, dataType);
+  },
 };
 
+mixin(PerformanceMixin);
+
 export {
-  commands, SUPPORTED_PERFORMANCE_DATA_TYPES, CPU_KEYS, MEMORY_KEYS,
-  BATTERY_KEYS, NETWORK_KEYS, getMemoryInfo, getNetworkTrafficInfo,
-  getCPUInfo, getBatteryInfo,
+  BATTERY_KEYS,
+  CPU_KEYS,
+  MEMORY_KEYS,
+  NETWORK_KEYS,
+  SUPPORTED_PERFORMANCE_DATA_TYPES,
+  getBatteryInfo,
+  getCPUInfo,
+  getMemoryInfo,
+  getNetworkTrafficInfo,
 };
-export default commands;
+
+export default PerformanceMixin;
+
+/**
+ * @typedef {import('../driver').AndroidDriver} AndroidDriver
+ * @typedef {import('appium-adb').ADB} ADB
+ */