appium 2.2.3 → 2.4.0

package/lib/cli/extension-command.js

@@ -2,7 +2,7 @@
 import B from 'bluebird';
 import _ from 'lodash';
 import path from 'path';
-import {npm, util, env, console} from '@appium/support';
+import {npm, util, env, console, fs, system} from '@appium/support';
 import {spinWith, RingBuffer} from './utils';
 import {
   INSTALL_TYPE_NPM,
@@ -15,6 +15,10 @@ import {SubProcess} from 'teen_process';
 import {packageDidChange} from '../extension/package-changed';
 import {spawn} from 'child_process';
 import {inspect} from 'node:util';
+import {pathToFileURL} from 'url';
+import {Doctor} from '../doctor/doctor';
+import {npmPackage} from '../utils';
+import semver from 'semver';
 
 const UPDATE_ALL = 'installed';
 
@@ -31,6 +35,19 @@ function receiptToManifest(receipt) {
   return /** @type {ExtManifest<ExtType>} */ (_.omit(receipt, 'driverName', 'pluginName'));
 }
 
+/**
+ * Fetches the remote extension version requirement
+ *
+ * @param {string} installSpec Extension name (could also contain the version suffix)
+ * @returns {Promise<[string, string|null]>}
+ */
+async function getRemoteExtensionVersionReq(installSpec) {
+  const allDeps = await npm.getPackageInfo(installSpec, ['peerDependencies', 'dependencies']);
+  const requiredVersionPair = _.flatMap(_.values(allDeps).map(_.toPairs))
+    .find(([name]) => name === 'appium');
+  return [npmPackage.version, requiredVersionPair ? requiredVersionPair[1] : null];
+}
+
 /**
  * @template {ExtensionType} ExtType
  */
@@ -223,6 +240,29 @@ class ExtensionCliCommand {
     return listData;
   }
 
+  /**
+   * Checks whether the given extension is compatible with the currently installed server
+   *
+   * @param {InstallViaNpmArgs} installViaNpmOpts
+   * @returns {Promise<void>}
+   */
+  async _checkInstallCompatibility({installSpec, pkgName, installType}) {
+    if (INSTALL_TYPE_NPM !== installType) {
+      return;
+    }
+
+    await spinWith(this.isJsonOutput, `Checking if '${pkgName}' is compatible`, async () => {
+      const [serverVersion, extVersionRequirement] = await getRemoteExtensionVersionReq(installSpec);
+      if (serverVersion && extVersionRequirement && !semver.satisfies(serverVersion, extVersionRequirement)) {
+        throw this._createFatalError(
+          `'${installSpec}' cannot be installed because the server version it requires (${extVersionRequirement}) ` +
+          `does not meet the currently installed one (${serverVersion}). Please install ` +
+          `a compatible server version first.`
+        );
+      }
+    });
+  }
+
   /**
    * Install an extension
    *
@@ -332,6 +372,8 @@ class ExtensionCliCommand {
       );
     }
 
+    await this._checkInstallCompatibility(installViaNpmOpts);
+
     receipt = await this.installViaNpm(installViaNpmOpts);
 
     // this _should_ be the same as `probablyExtName` as the one derived above unless
@@ -695,6 +737,85 @@ class ExtensionCliCommand {
     });
   }
 
+  /**
+   * Runs doctor checks for the given extension
+   *
+   * @param {DoctorOptions} opts
+   * @returns {Promise<import('@appium/types').IDoctorCheck[]>}
+   */
+  async _doctor({installSpec}) {
+    if (!this.config.isInstalled(installSpec)) {
+      throw this._createFatalError(`The ${this.type} "${installSpec}" is not installed`);
+    }
+
+    const moduleRoot = this.config.getInstallPath(installSpec);
+    const packageJsonPath = path.join(moduleRoot, 'package.json');
+    if (!await fs.exists(packageJsonPath)) {
+      throw this._createFatalError(
+        `No package.json could be found for "${installSpec}" ${this.type}`
+      );
+    }
+    let doctorSpec;
+    try {
+      doctorSpec = JSON.parse(await fs.readFile(packageJsonPath, 'utf8')).appium?.doctor;
+    } catch (e) {
+      throw this._createFatalError(
+        `The manifest at '${packageJsonPath}' cannot be parsed: ${e.message}`
+      );
+    }
+    if (!doctorSpec) {
+      this.log.info(`The ${this.type} "${installSpec}" does not export any doctor checks`);
+      return [];
+    }
+    if (!_.isPlainObject(doctorSpec) || !_.isArray(doctorSpec.checks)) {
+      throw this._createFatalError(
+        `The 'doctor' entry in the package manifest '${packageJsonPath}' must be a proper object ` +
+        `containing the 'checks' key with the array of script paths`
+      );
+    }
+    const paths = doctorSpec.checks.map((/** @type {string} */ p) => {
+      const scriptPath = path.resolve(moduleRoot, p);
+      if (!path.normalize(scriptPath).startsWith(path.normalize(moduleRoot))) {
+        this.log.error(
+          `The doctor check script '${p}' from the package manifest '${packageJsonPath}' must be located ` +
+          `in the '${moduleRoot}' root folder. It will be skipped`
+        );
+        return null;
+      }
+      return scriptPath;
+    }).filter(Boolean);
+    /** @type {Promise[]} */
+    const loadChecksPromises = [];
+    for (const p of paths) {
+      const promise = (async () => {
+        // https://github.com/nodejs/node/issues/31710
+        const scriptPath = system.isWindows() ? pathToFileURL(p).href : p;
+        try {
+          return await import(scriptPath);
+        } catch (e) {
+          this.log.warn(`Unable to load doctor checks from '${p}': ${e.message}`);
+        }
+      })();
+      loadChecksPromises.push(promise);
+    }
+    const isDoctorCheck = (/** @type {any} */ x) =>
+      ['diagnose', 'fix', 'hasAutofix', 'isOptional'].every((method) => _.isFunction(x?.[method]));
+    /** @type {import('@appium/types').IDoctorCheck[]} */
+    const checks = _.flatMap((await B.all(loadChecksPromises)).filter(Boolean).map(_.toPairs))
+      .map(([, value]) => value)
+      .filter(isDoctorCheck);
+    if (_.isEmpty(checks)) {
+      this.log.info(`The ${this.type} "${installSpec}" exports no valid doctor checks`);
+      return [];
+    }
+    this.log.debug(
+      `Running ${util.pluralize('doctor check', checks.length, true)} ` +
+      `for the "${installSpec}" ${this.type}`
+    );
+    await new Doctor(checks).run();
+    return checks;
+  }
+
   /**
    * Runs a script cached inside the `scripts` field under `appium`
    * inside of the extension's `package.json` file. Will throw
@@ -729,15 +850,42 @@ class ExtensionCliCommand {
       );
     }
 
+    if (!scriptName) {
+      const allScripts = _.toPairs(extScripts);
+      const root = this.config.getInstallPath(installSpec);
+      const existingScripts = await B.filter(
+        allScripts,
+        async ([, p]) => await fs.exists(path.join(root, p))
+      );
+      if (_.isEmpty(existingScripts)) {
+        this.log.info(`The ${this.type} named '${installSpec}' does not contain any scripts`);
+      } else {
+        this.log.info(`The ${this.type} named '${installSpec}' contains ` +
+          `${util.pluralize('script', existingScripts.length, true)}:`);
+        existingScripts.forEach(([name]) => this.log.info(`  - ${name}`));
+      }
+      this.log.ok(`Successfully retrieved the list of scripts`.green);
+      return {};
+    }
+
     if (!(scriptName in /** @type {Record<string,string>} */ (extScripts))) {
       throw this._createFatalError(
         `The ${this.type} named '${installSpec}' does not support the script: '${scriptName}'`
       );
     }
 
+    const scriptPath = extScripts[scriptName];
+    const moduleRoot = this.config.getInstallPath(installSpec);
+    const normalizedScriptPath = path.normalize(path.resolve(moduleRoot, scriptPath));
+    if (!normalizedScriptPath.startsWith(path.normalize(moduleRoot))) {
+      throw this._createFatalError(
+        `The '${scriptPath}' script must be located in the '${moduleRoot}' folder`
+      );
+    }
+
     if (bufferOutput) {
-      const runner = new SubProcess(process.execPath, [extScripts[scriptName], ...extraArgs], {
-        cwd: this.config.getInstallPath(installSpec),
+      const runner = new SubProcess(process.execPath, [scriptPath, ...extraArgs], {
+        cwd: moduleRoot,
       });
 
       const output = new RingBuffer(50);
@@ -761,11 +909,7 @@ class ExtensionCliCommand {
 
     try {
       await new B((resolve, reject) => {
-        this._runUnbuffered(
-          this.config.getInstallPath(installSpec),
-          extScripts[scriptName],
-          extraArgs
-        )
+        this._runUnbuffered(moduleRoot, scriptPath, extraArgs)
           .on('error', (err) => {
             // generally this is of the "I can't find the script" variety.
             // this is a developer bug: the extension is pointing to a script that is not where the
@@ -869,11 +1013,18 @@ export {ExtensionCliCommand as ExtensionCommand};
  * Options for {@linkcode ExtensionCliCommand._run}.
  * @typedef RunOptions
  * @property {string} installSpec - name of the extension to run a script from
- * @property {string} scriptName - name of the script to run
+ * @property {string} [scriptName] - name of the script to run. If not provided
+ * then all available script names will be printed
  * @property {string[]} [extraArgs] - arguments to pass to the script
  * @property {boolean} [bufferOutput] - if true, will buffer the output of the script and return it
  */
 
+/**
+ * Options for {@linkcode ExtensionCliCommand.doctor}.
+ * @typedef DoctorOptions
+ * @property {string} installSpec - name of the extension to run doctor checks for
+ */
+
 /**
  * Return value of {@linkcode ExtensionCliCommand._run}
  *

package/lib/cli/parser.js

@@ -2,7 +2,17 @@ import {fs} from '@appium/support';
 import {ArgumentParser} from 'argparse';
 import _ from 'lodash';
 import path from 'path';
-import {DRIVER_TYPE, PLUGIN_TYPE, SERVER_SUBCOMMAND} from '../constants';
+import {
+  DRIVER_TYPE,
+  EXT_SUBCOMMAND_DOCTOR,
+  EXT_SUBCOMMAND_INSTALL,
+  EXT_SUBCOMMAND_LIST,
+  EXT_SUBCOMMAND_RUN,
+  EXT_SUBCOMMAND_UNINSTALL,
+  EXT_SUBCOMMAND_UPDATE,
+  PLUGIN_TYPE,
+  SERVER_SUBCOMMAND
+} from '../constants';
 import {finalizeSchema, getArgSpec, hasArgSpec} from '../schema';
 import {rootDir} from '../config';
 import {getExtensionArgs, getServerArgs} from './args';
@@ -191,8 +201,7 @@ class ArgParser {
 
     const serverArgs = getServerArgs();
     for (const [flagsOrNames, opts] of serverArgs) {
-      // TS doesn't like the spread operator here.
-      // @ts-ignore
+      // @ts-ignore TS doesn't like the spread operator here.
       serverParser.add_argument(...flagsOrNames, {...opts});
     }
 
@@ -221,33 +230,38 @@ class ArgParser {
        */
       const parserSpecs = [
         {
-          command: 'list',
+          command: EXT_SUBCOMMAND_LIST,
           args: extensionArgs[type].list,
           help: `List available and installed ${type}s`,
           aliases: ['ls'],
         },
         {
-          command: 'install',
+          command: EXT_SUBCOMMAND_INSTALL,
           args: extensionArgs[type].install,
           help: `Install a ${type}`,
         },
         {
-          command: 'uninstall',
+          command: EXT_SUBCOMMAND_UNINSTALL,
           args: extensionArgs[type].uninstall,
           help: `Uninstall a ${type}`,
         },
         {
-          command: 'update',
+          command: EXT_SUBCOMMAND_UPDATE,
           args: extensionArgs[type].update,
           help: `Update installed ${type}s to the latest version`,
         },
         {
-          command: 'run',
+          command: EXT_SUBCOMMAND_RUN,
           args: extensionArgs[type].run,
           help:
             `Run a script (defined inside the ${type}'s package.json under the ` +
             `“scripts” field inside the “appium” field) from an installed ${type}`,
         },
+        {
+          command: EXT_SUBCOMMAND_DOCTOR,
+          args: extensionArgs[type].doctor,
+          help: `Run doctor checks (if any defined) for the given ${type}`,
+        },
       ];
 
       for (const {command, args, help, aliases} of parserSpecs) {

package/lib/cli/plugin-command.js

@@ -65,6 +65,18 @@ export default class PluginCliCommand extends ExtensionCliCommand {
     });
   }
 
+  /**
+   * Runs doctor checks for the given plugin
+   *
+   * @param {PluginDoctorOptions} opts
+   * @returns {Promise<import('@appium/types').IDoctorCheck[]>}
+   */
+  async doctor({plugin}) {
+    return await super._doctor({
+      installSpec: plugin,
+    });
+  }
+
   /**
    *
    * @param {import('./extension-command').ExtensionArgs} opts
@@ -141,3 +153,9 @@ export default class PluginCliCommand extends ExtensionCliCommand {
  * @property {string} scriptName - name of the script to run
  * @property {string[]} [extraArgs] - arguments to pass to the script
  */
+
+/**
+ * Options for {@linkcode PluginCliCommand.doctor}.
+ * @typedef PluginDoctorOptions
+ * @property {string} plugin - name of the plugin to run doctor checks for
+ */

package/lib/cli/utils.js

@@ -2,14 +2,14 @@
 
 import ora from 'ora';
 
-const JSON_SPACES = 4;
+export const JSON_SPACES = 4;
 
 /***
  * Log an error to the console and exit the process.
  * @param {boolean} json - whether we should log json or text
  * @param {any} msg - error message, object, Error instance, etc.
  */
-function errAndQuit(json, msg) {
+export function errAndQuit(json, msg) {
   if (json) {
     console.log(JSON.stringify({error: `${msg}`}, null, JSON_SPACES));
   } else {
@@ -26,7 +26,7 @@ function errAndQuit(json, msg) {
  * @param {boolean} json - whether we are in json mode (and should therefore not log)
  * @param {string} msg - string to log
  */
-function log(json, msg) {
+export function log(json, msg) {
   !json && console.log(msg);
 }
 
@@ -36,7 +36,7 @@ function log(json, msg) {
  * @param {string} msg - string to log
  * @param {function} fn - function to wrap with spinning
  */
-async function spinWith(json, msg, fn) {
+export async function spinWith(json, msg, fn) {
   if (json) {
     return await fn();
   }
@@ -52,7 +52,7 @@ async function spinWith(json, msg, fn) {
   }
 }
 
-class RingBuffer {
+export class RingBuffer {
   constructor(size = 50) {
     this.size = size;
     this.buffer = [];
@@ -70,5 +70,3 @@ class RingBuffer {
     this.buffer.push(item);
   }
 }
-
-export {errAndQuit, log, spinWith, JSON_SPACES, RingBuffer};

package/lib/config.js

@@ -4,17 +4,14 @@ import {system, fs} from '@appium/support';
 import axios from 'axios';
 import {exec} from 'teen_process';
 import semver from 'semver';
-import findUp from 'find-up';
+import os from 'node:os';
+import {npmPackage} from './utils';
 import {getDefaultsForSchema, getAllArgSpecs} from './schema/schema';
 
-const npmPackage = fs.readPackageJsonFrom(__dirname);
-
-const APPIUM_VER = npmPackage.version;
+export const APPIUM_VER = npmPackage.version;
 const ENGINES = /** @type {Record<string,string>} */ (npmPackage.engines);
 const MIN_NODE_VERSION = ENGINES.node;
-const MIN_NPM_VERSION = ENGINES.npm;
 
-const GIT_META_ROOT = '.git';
 const GIT_BINARY = `git${system.isWindows() ? '.exe' : ''}`;
 const GITHUB_API = 'https://api.github.com/repos/appium/appium';
 
@@ -29,15 +26,6 @@ function getNodeVersion() {
   return /** @type {import('semver').SemVer} */ (semver.coerce(process.version));
 }
 
-/**
- * Returns version of `npm`
- * @returns {Promise<string>}
- */
-async function getNpmVersion() {
-  const {stdout} = await exec(system.isWindows() ? 'npm.cmd' : 'npm', ['--version']);
-  return stdout.trim();
-}
-
 /**
  * @param {boolean} [useGithubApiFallback]
  */
@@ -53,27 +41,25 @@ async function updateBuildInfo(useGithubApiFallback = false) {
   }
 }
 
-/**
- * Finds the Git metadata dir (see `GIT_META_ROOT`)
- *
- * This is needed because Appium cannot assume `package.json` and `.git` are in the same
- * directory.  Monorepos, see?
- * @returns {Promise<string|undefined>} Path to dir or `undefined` if not found
- */
-async function findGitRoot() {
-  return await findUp(GIT_META_ROOT, {cwd: rootDir, type: 'directory'});
-}
+/** @type {() => Promise<string?>} */
+const getFullGitPath = _.memoize(async function getFullGitPath() {
+  try {
+    return await fs.which(GIT_BINARY);
+  } catch {
+    return null;
+  }
+});
 
 /**
  * @param {boolean} [useGithubApiFallback]
  * @returns {Promise<string?>}
  */
 async function getGitRev(useGithubApiFallback = false) {
-  const gitRoot = await findGitRoot();
-  if (gitRoot) {
+  const fullGitPath = await getFullGitPath();
+  if (fullGitPath) {
     try {
-      const {stdout} = await exec(GIT_BINARY, ['rev-parse', 'HEAD'], {
-        cwd: gitRoot,
+      const {stdout} = await exec(fullGitPath, ['rev-parse', 'HEAD'], {
+        cwd: __dirname,
       });
       return stdout.trim();
     } catch (ign) {}
@@ -103,11 +89,11 @@ async function getGitRev(useGithubApiFallback = false) {
  * @returns {Promise<string?>}
  */
 async function getGitTimestamp(commitSha, useGithubApiFallback = false) {
-  const gitRoot = await findGitRoot();
-  if (gitRoot) {
+  const fullGitPath = await getFullGitPath();
+  if (fullGitPath) {
     try {
-      const {stdout} = await exec(GIT_BINARY, ['show', '-s', '--format=%ci', commitSha], {
-        cwd: gitRoot,
+      const {stdout} = await exec(fullGitPath, ['show', '-s', '--format=%ci', commitSha], {
+        cwd: __dirname,
       });
       return stdout.trim();
     } catch (ign) {}
@@ -149,28 +135,6 @@ function checkNodeOk() {
   }
 }
 
-export async function checkNpmOk() {
-  const npmVersion = await getNpmVersion();
-  if (!semver.satisfies(npmVersion, MIN_NPM_VERSION)) {
-    throw new Error(
-      `npm version must be at least ${MIN_NPM_VERSION}; current is ${npmVersion}. Run "npm install -g npm" to upgrade.`
-    );
-  }
-}
-
-function warnNodeDeprecations() {
-  /**
-   * Uncomment this section to get node version deprecation warnings
-   * Also add test cases to config-specs.js to cover the cases added
-   **/
-  // const version = getNodeVersion();
-  // if (version.major < 8) {
-  //   logger.warn(`Appium support for versions of node < ${version.major} has been ` +
-  //               'deprecated and will be removed in a future version. Please ' +
-  //               'upgrade!');
-  // }
-}
-
 async function showBuildInfo() {
   await updateBuildInfo(true);
   console.log(JSON.stringify(getBuildInfo())); // eslint-disable-line no-console
@@ -311,16 +275,36 @@ function showConfig(nonDefaultPreConfigParsedArgs, configResult, defaults, parse
 }
 
 /**
- * @param {string} tmpDir
+ * @param {string} root
+ * @param {boolean} [requireWriteable=true]
+ * @param {string} [displayName='folder path']
+ * @throws {Error}
  */
-async function validateTmpDir(tmpDir) {
+export async function requireDir(root, requireWriteable = true, displayName = 'folder path') {
+  let stat;
   try {
-    await fs.mkdirp(tmpDir);
+    stat = await fs.stat(root);
   } catch (e) {
-    throw new Error(
-      `We could not ensure that the temp dir you specified ` +
-        `(${tmpDir}) exists. Please make sure it's writeable.`
-    );
+    if (e.code === 'ENOENT') {
+      try {
+        await fs.mkdir(root, {recursive: true});
+        return;
+      } catch {}
+    }
+    throw new Error(`The ${displayName} '${root}' must exist and be a valid directory`);
+  }
+  if (stat && !stat.isDirectory()) {
+    throw new Error(`The ${displayName} '${root}' must be a valid directory`);
+  }
+  if (requireWriteable) {
+    try {
+      await fs.access(root, fs.constants.W_OK);
+    } catch (e) {
+      throw new Error(
+        `The ${displayName} '${root}' must be ` +
+        `writeable for the current user account '${os.userInfo().username}'`
+      );
+    }
   }
 }
 
@@ -330,11 +314,8 @@ export {
   getBuildInfo,
   checkNodeOk,
   showBuildInfo,
-  warnNodeDeprecations,
-  validateTmpDir,
   getNonDefaultServerArgs,
   getGitRev,
-  APPIUM_VER,
   updateBuildInfo,
   showConfig,
   rootDir,

package/lib/constants.js

@@ -64,6 +64,7 @@ export const EXT_SUBCOMMAND_INSTALL = 'install';
 export const EXT_SUBCOMMAND_UNINSTALL = 'uninstall';
 export const EXT_SUBCOMMAND_UPDATE = 'update';
 export const EXT_SUBCOMMAND_RUN = 'run';
+export const EXT_SUBCOMMAND_DOCTOR = 'doctor';
 
 /**
  * Current revision of the manifest (`extensions.yaml`) schema
@@ -77,3 +78,14 @@ export const CURRENT_SCHEMA_REV = 4;
  * memory usage, perf, and/or log output, and higher limits may be difficult to scan.
  */
 export const LONG_STACKTRACE_LIMIT = 100;
+
+/**
+ * Where should the bidi websocket handler live on the server?
+ */
+export const BIDI_BASE_PATH = '/bidi';
+
+/**
+ * The name of the event for drivers to emit when they want to send bidi events to a client over
+ * a bidi socket
+ */
+export const BIDI_EVENT_NAME = 'bidiEvent';