feat: Split process and app commands (#822)

BREAKING CHANGE: Renamed getPIDsByName to listAppProcessIds
BREAKING CHANGE: Renamed getNameByPid to getProcessNameById
BREAKING CHANGE: Removed the obsolete broadcastProcessEnd method
BREAKING CHANGE: Removed the deprecated appDeviceReadyTimeout property

Author: mykola-mokhnach

.github/workflows/functional-test.yml

@@ -27,12 +27,8 @@ jobs:
           apiLevel: 28
           emuTag: default
           arch: x86
-        - platformVersion: "7.1"
-          apiLevel: 25
-          emuTag: default
-          arch: x86
-        - platformVersion: "5.1"
-          apiLevel: 22
+        - platformVersion: "8.0"
+          apiLevel: 26
           emuTag: default
           arch: x86
       fail-fast: false

lib/adb.ts

@@ -28,6 +28,7 @@ import * as fsCommands from './tools/fs-commands';
 import * as appCommands from './tools/app-commands';
 import * as networkCommands from './tools/network-commands';
 import * as logcatCommands from './tools/logcat-commands';
+import * as processCommands from './tools/process-commands';
 
 
 export const DEFAULT_ADB_PORT = 5037;
@@ -59,8 +60,6 @@ export class ADB implements ADBOptions {
 
   sdkRoot?: string;
   udid?: string;
-  /** @deprecated Not used anywhere, marked for deletion */
-  appDeviceReadyTimeout?: number;
   useKeystore?: boolean;
   keystorePath?: string;
   keystorePassword?: string;
@@ -198,14 +197,6 @@ export class ADB implements ADBOptions {
   forceStop = appCommands.forceStop;
   killPackage = appCommands.killPackage;
   clear = appCommands.clear;
-  listProcessStatus = appCommands.listProcessStatus;
-  getNameByPid = appCommands.getNameByPid;
-  getPIDsByName = appCommands.getPIDsByName;
-  killProcessesByName = appCommands.killProcessesByName;
-  killProcessByPID = appCommands.killProcessByPID;
-  broadcastProcessEnd = appCommands.broadcastProcessEnd;
-  broadcast = appCommands.broadcast;
-  processExists = appCommands.processExists;
   readonly APP_INSTALL_STATE = appCommands.APP_INSTALL_STATE;
   isAppInstalled = appCommands.isAppInstalled;
   startUri = appCommands.startUri;
@@ -218,6 +209,16 @@ export class ADB implements ADBOptions {
   getPackageInfo = appCommands.getPackageInfo;
   pullApk = appCommands.pullApk;
   activateApp = appCommands.activateApp;
+  listAppProcessIds = appCommands.listAppProcessIds;
+  isAppRunning = appCommands.isAppRunning;
+  broadcast = appCommands.broadcast;
+
+  listProcessStatus = processCommands.listProcessStatus;
+  getProcessNameById = processCommands.getProcessNameById;
+  getProcessIdsByName = processCommands.getProcessIdsByName;
+  killProcessesByName = processCommands.killProcessesByName;
+  killProcessByPID = processCommands.killProcessByPID;
+  processExists = processCommands.processExists;
 
   uninstallApk = apkUtilCommands.uninstallApk;
   installFromDevicePath = apkUtilCommands.installFromDevicePath;

lib/tools/app-commands.js

@@ -1,8 +1,7 @@
 import _ from 'lodash';
 import { fs, tempDir, util, system } from '@appium/support';
 import { log } from '../logger.js';
-import { sleep, waitForCondition } from 'asyncbox';
-import B from 'bluebird';
+import { waitForCondition } from 'asyncbox';
 import path from 'path';
 
 /** @type {import('./types').StringRecord<import('./types').InstallState>} */
@@ -19,9 +18,6 @@ const IGNORED_PERM_ERRORS = [
   /Unknown permission/i,
 ];
 const MIN_API_LEVEL_WITH_PERMS_SUPPORT = 23;
-const PID_COLUMN_TITLE = 'PID';
-const PROCESS_NAME_COLUMN_TITLE = 'NAME';
-const PS_TITLE_PATTERN = new RegExp(`^(.*\\b${PID_COLUMN_TITLE}\\b.*\\b${PROCESS_NAME_COLUMN_TITLE}\\b.*)$`, 'm');
 const RESOLVER_ACTIVITY_NAME = 'android/com.android.internal.app.ResolverActivity';
 const MAIN_ACTION = 'android.intent.action.MAIN';
 const LAUNCHER_CATEGORY = 'android.intent.category.LAUNCHER';
@@ -308,211 +304,6 @@ export async function stopAndClear (pkg) {
   }
 }
 
-
-/**
- * At some point of time Google has changed the default `ps` behaviour, so it only
- * lists processes that belong to the current shell user rather to all
- * users. It is necessary to execute ps with -A command line argument
- * to mimic the previous behaviour.
- *
- * @this {import('../adb.js').ADB}
- * @returns {Promise<string>} the output of `ps` command where all processes are included
- */
-export async function listProcessStatus () {
-  if (!_.isBoolean(this._doesPsSupportAOption)) {
-    try {
-      this._doesPsSupportAOption = /^-A\b/m.test(await this.shell(['ps', '--help']));
-    } catch (e) {
-      log.debug((/** @type {Error} */ (e)).stack);
-      this._doesPsSupportAOption = false;
-    }
-  }
-  return await this.shell(this._doesPsSupportAOption ? ['ps', '-A'] : ['ps']);
-}
-
-/**
- * Returns process name for the given process identifier
- *
- * @this {import('../adb.js').ADB}
- * @param {string|number} pid - The valid process identifier
- * @throws {Error} If the given PID is either invalid or is not present
- * in the active processes list
- * @returns {Promise<string>} The process name
- */
-export async function getNameByPid (pid) {
-  // @ts-ignore This validation works as expected
-  if (isNaN(pid)) {
-    throw new Error(`The PID value must be a valid number. '${pid}' is given instead`);
-  }
-  pid = parseInt(`${pid}`, 10);
-
-  const stdout = await this.listProcessStatus();
-  const titleMatch = PS_TITLE_PATTERN.exec(stdout);
-  if (!titleMatch) {
-    log.debug(stdout);
-    throw new Error(`Could not get the process name for PID '${pid}'`);
-  }
-  const allTitles = titleMatch[1].trim().split(/\s+/);
-  const pidIndex = allTitles.indexOf(PID_COLUMN_TITLE);
-  // it might not be stable to take NAME by index, because depending on the
-  // actual SDK the ps output might not contain an abbreviation for the S flag:
-  // USER     PID   PPID  VSIZE  RSS     WCHAN    PC        NAME
-  // USER     PID   PPID  VSIZE  RSS     WCHAN    PC   S    NAME
-  const nameOffset = allTitles.indexOf(PROCESS_NAME_COLUMN_TITLE) - allTitles.length;
-  const pidRegex = new RegExp(`^(.*\\b${pid}\\b.*)$`, 'gm');
-  let matchedLine;
-  while ((matchedLine = pidRegex.exec(stdout))) {
-    const items = matchedLine[1].trim().split(/\s+/);
-    if (parseInt(items[pidIndex], 10) === pid && items[items.length + nameOffset]) {
-      return items[items.length + nameOffset];
-    }
-  }
-  log.debug(stdout);
-  throw new Error(`Could not get the process name for PID '${pid}'`);
-}
-
-/**
- * Get the list of process ids for the particular process on the device under test.
- *
- * @this {import('../adb.js').ADB}
- * @param {string} name - The part of process name.
- * @return {Promise<number[]>} The list of matched process IDs or an empty list.
- * @throws {Error} If the passed process name is not a valid one
- */
-export async function getPIDsByName (name) {
-  log.debug(`Getting IDs of all '${name}' processes`);
-  if (!this.isValidClass(name)) {
-    throw new Error(`Invalid process name: '${name}'`);
-  }
-
-  const pidRegex = new RegExp(`ProcessRecord\\{[\\w]+\\s+(\\d+):${_.escapeRegExp(name)}\\/`);
-  const processesInfo = await this.shell(['dumpsys', 'activity', 'processes']);
-  const pids = processesInfo.split('\n')
-    .map((line) => line.match(pidRegex))
-    .filter((match) => !!match)
-    .map(([, pidStr]) => parseInt(pidStr, 10));
-  return _.uniq(pids);
-}
-
-/**
- * Get the list of process ids for the particular process on the device under test.
- *
- * @this {import('../adb.js').ADB}
- * @param {string} name - The part of process name.
- */
-export async function killProcessesByName (name) {
-  try {
-    log.debug(`Attempting to kill all ${name} processes`);
-    const pids = await this.getPIDsByName(name);
-    if (_.isEmpty(pids)) {
-      log.info(`No '${name}' process has been found`);
-    } else {
-      await B.all(pids.map((p) => this.killProcessByPID(p)));
-    }
-  } catch (e) {
-    const err = /** @type {Error} */ (e);
-    throw new Error(`Unable to kill ${name} processes. Original error: ${err.message}`);
-  }
-}
-
-/**
- * Kill the particular process on the device under test.
- * The current user is automatically switched to root if necessary in order
- * to properly kill the process.
- *
- * @this {import('../adb.js').ADB}
- * @param {string|number} pid - The ID of the process to be killed.
- * @throws {Error} If the process cannot be killed.
- */
-export async function killProcessByPID (pid) {
-  log.debug(`Attempting to kill process ${pid}`);
-  const noProcessFlag = 'No such process';
-  try {
-    // Check if the process exists and throw an exception otherwise
-    await this.shell(['kill', `${pid}`]);
-  } catch (e) {
-    const err = /** @type {import('teen_process').ExecError} */ (e);
-    if (_.includes(err.stderr, noProcessFlag)) {
-      return;
-    }
-    if (!_.includes(err.stderr, 'Operation not permitted')) {
-      throw err;
-    }
-    log.info(`Cannot kill PID ${pid} due to insufficient permissions. Retrying as root`);
-    try {
-      await this.shell(['kill', `${pid}`], {
-        privileged: true
-      });
-    } catch (e1) {
-      const err1 = /** @type {import('teen_process').ExecError} */ (e1);
-      if (_.includes(err1.stderr, noProcessFlag)) {
-        return;
-      }
-      throw err1;
-    }
-  }
-}
-
-/**
- * Broadcast process killing on the device under test.
- *
- * @deprecated This method is deprecated and marked for removal in future releases.
- * @this {import('../adb.js').ADB}
- * @param {string} intent - The name of the intent to broadcast to.
- * @param {string} processName - The name of the killed process.
- * @throws {error} If the process was not killed.
- */
-export async function broadcastProcessEnd (intent, processName) {
-  // start the broadcast without waiting for it to finish.
-  this.broadcast(intent);
-  // wait for the process to end
-  let start = Date.now();
-  let timeoutMs = 40000;
-  try {
-    while ((Date.now() - start) < timeoutMs) {
-      if (await this.processExists(processName)) {
-        // cool down
-        await sleep(400);
-        continue;
-      }
-      return;
-    }
-    throw new Error(`Process never died within ${timeoutMs} ms`);
-  } catch (e) {
-    const err = /** @type {Error} */ (e);
-    throw new Error(`Unable to broadcast process end. Original error: ${err.message}`);
-  }
-}
-
-/**
- * Broadcast a message to the given intent.
- *
- * @this {import('../adb.js').ADB}
- * @param {string} intent - The name of the intent to broadcast to.
- * @throws {error} If intent name is not a valid class name.
- */
-export async function broadcast (intent) {
-  if (!this.isValidClass(intent)) {
-    throw new Error(`Invalid intent ${intent}`);
-  }
-  log.debug(`Broadcasting: ${intent}`);
-  await this.shell(['am', 'broadcast', '-a', intent]);
-}
-
-/**
- * Check whether the process with the particular name is running on the device
- * under test.
- *
- * @this {import('../adb.js').ADB}
- * @param {string} processName - The name of the process to be checked.
- * @return {Promise<boolean>} True if the given process is running.
- * @throws {Error} If the given process name is not a valid class name.
- */
-export async function processExists (processName) {
-  return !_.isEmpty(await this.getPIDsByName(processName));
-}
-
-
 /**
  * Get the package info from the installed application.
  *
@@ -631,7 +422,6 @@ export async function activateApp (appId) {
   }
 }
 
-
 /**
  * Check whether the particular package is present on the device under test.
  *
@@ -1285,7 +1075,52 @@ export function extractMatchingPermissions (dumpsysOutput, groupNames, grantedSt
   log.debug(`Retrieved ${util.pluralize('permission', filteredResult.length, true)} ` +
     `from ${groupNames} ${util.pluralize('group', groupNames.length, false)}`);
   return filteredResult;
-};
+}
+
+/**
+ * Broadcast a message to the given intent.
+ *
+ * @this {import('../adb.js').ADB}
+ * @param {string} intent - The name of the intent to broadcast to.
+ * @throws {error} If intent name is not a valid class name.
+ */
+export async function broadcast (intent) {
+  if (!this.isValidClass(intent)) {
+    throw new Error(`Invalid intent ${intent}`);
+  }
+  log.debug(`Broadcasting: ${intent}`);
+  await this.shell(['am', 'broadcast', '-a', intent]);
+}
+
+/**
+ * Get the list of process ids for the particular package on the device under test.
+ *
+ * @this {import('../adb.js').ADB}
+ * @param {string} pkg
+ * @returns {Promise<number[]>} The list of matched process IDs or an empty list.
+ */
+export async function listAppProcessIds (pkg) {
+  log.debug(`Getting IDs of all '${pkg}' package`);
+  const pidRegex = new RegExp(`ProcessRecord\\{[\\w]+\\s+(\\d+):${_.escapeRegExp(pkg)}\\/`);
+  const processesInfo = await this.shell(['dumpsys', 'activity', 'processes']);
+  const pids = processesInfo.split('\n')
+    .map((line) => line.match(pidRegex))
+    .filter((match) => !!match)
+    .map(([, pidStr]) => parseInt(pidStr, 10));
+  return _.uniq(pids);
+}
+
+/**
+ * Check whether the process with the particular name is running on the device
+ * under test.
+ *
+ * @this {import('../adb.js').ADB}
+ * @param {string} pkg - The id of the package to be checked.
+ * @returns True if the given package is running.
+ */
+export async function isAppRunning (pkg) {
+  return !_.isEmpty(await this.listAppProcessIds(pkg));
+}
 
 /**
  * @typedef {Object} StartCmdOptions