appium 2.3.0 → 2.4.0

package/lib/cli/driver-command.js

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

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,6 +850,24 @@ 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}'`
@@ -874,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 GIT_META_ROOT = '.git';
 const GIT_BINARY = `git${system.isWindows() ? '.exe' : ''}`;
 const GITHUB_API = 'https://api.github.com/repos/appium/appium';
 
@@ -44,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) {}
@@ -94,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) {}
@@ -321,7 +316,6 @@ export {
   showBuildInfo,
   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';