appium 2.2.3 → 2.4.0

package/lib/doctor/doctor.js

@@ -0,0 +1,209 @@
+import '@colors/colors';
+import _ from 'lodash';
+import { util, doctor, logger } from '@appium/support';
+
+export class Doctor {
+  /**
+   * @param {DoctorCheck[]} [checks=[]]
+   */
+  constructor(checks = []) {
+    this.log = logger.getLogger('Doctor');
+    /** @type {DoctorCheck[]} */
+    this.checks = checks;
+    this.checks
+      .filter((c) => _.isNil(c.log))
+      .forEach((c) => { c.log = this.log; });
+    /** @type {DoctorIssue[]} */
+    this.foundIssues = [];
+  }
+
+  /**
+   * @returns {DoctorIssue[]}
+   */
+  get issuesRequiredToFix() {
+    return this.foundIssues.filter((f) => !f.check.isOptional());
+  }
+
+  /**
+   * @returns {DoctorIssue[]}
+   */
+  get issuesOptionalToFix() {
+    return this.foundIssues.filter((f) => f.check.isOptional());
+  }
+
+  /**
+   * The doctor shows the report
+   */
+  async diagnose() {
+    this.log.info(`### Starting doctor diagnostics  ###`);
+    this.foundIssues = [];
+    for (const check of this.checks) {
+      const res = await check.diagnose();
+      const issue = this.toIssue(res, check);
+      if (issue) {
+        this.foundIssues.push(issue);
+      }
+    }
+    this.log.info(
+      `### Diagnostic completed, ${this.buildFixMessage()}. ###`
+    );
+    this.log.info('');
+  }
+
+  /**
+   * @returns {Promise<boolean>}
+   */
+  async reportManualIssues() {
+    const manualIssues = _.filter(this.issuesRequiredToFix, (f) => !f.check.hasAutofix());
+    const manualIssuesOptional = _.filter(this.issuesOptionalToFix, (f) => !f.check.hasAutofix());
+
+    const handleIssues = async (headerLogs, issues) => {
+      if (_.isEmpty(issues)) {
+        return;
+      }
+
+      for (const logMsg of headerLogs) {
+        this.log.info(logMsg);
+      }
+      /** @type {string[]} */
+      const fixMessages = [];
+      for (const issue of issues) {
+        const message = await issue.check.fix();
+        if (message) {
+          fixMessages.push(message);
+        }
+      }
+      for (const m of _.uniq(fixMessages)) {
+        this.log.warn(` \u279C ${m}`);
+      }
+      this.log.info('');
+    };
+
+    await handleIssues([
+      '### Manual Fixes Needed ###',
+      'The configuration cannot be automatically fixed, please do the following first:',
+    ], manualIssues);
+    await handleIssues([
+      '### Optional Manual Fixes  ###',
+      'To fix these optional issues, please do the following manually:',
+    ], manualIssuesOptional);
+
+    if (manualIssues.length > 0) {
+      this.log.info('###');
+      this.log.info('');
+      this.log.info('Bye! Run doctor again when all manual fixes have been applied!');
+      this.log.info('');
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * @param {DoctorIssue} f
+   */
+  async runAutoFix(f) {
+    this.log.info(`### Fixing: ${f.error} ###`);
+    try {
+      await f.check.fix();
+    } catch (err) {
+      if (err.constructor.name === doctor.FixSkippedError.name) {
+        this.log.info(`### Skipped fix ###`);
+        return;
+      } else {
+        this.log.warn(`${err}`.replace(/\n$/g, ''));
+        this.log.info(`### Fix did not succeed ###`);
+        return;
+      }
+    }
+    this.log.info('Checking if this was fixed:');
+    const res = await f.check.diagnose();
+    if (res.ok) {
+      f.fixed = true;
+      this.log.info(` ${'\u2714'.green} ${res.message}`);
+      this.log.info(`### Fix was successfully applied ###`);
+    } else {
+      this.log.info(` ${'\u2716'.red} ${res.message}`);
+      this.log.info(`### Fix was applied but issue remains ###`);
+    }
+  }
+
+  async runAutoFixes() {
+    const autoFixes = _.filter(this.foundIssues, (f) => f.check.hasAutofix());
+    for (const f of autoFixes) {
+      await this.runAutoFix(f);
+      this.log.info('');
+    }
+    if (_.find(autoFixes, (f) => !f.fixed)) {
+      // a few issues remain.
+      this.log.info('Bye! A few issues remain, fix manually and/or rerun doctor!');
+    } else {
+      // nothing left to fix.
+      this.log.info('Bye! All issues have been fixed!');
+    }
+    this.log.info('');
+  }
+
+  async run() {
+    await this.diagnose();
+    if (this.reportSuccess()) {
+      return;
+    }
+    if (await this.reportManualIssues()) {
+      return;
+    }
+    await this.runAutoFixes();
+  }
+
+  /**
+   * @param {DoctorCheckResult} result
+   * @param {DoctorCheck} check
+   * @returns {DoctorIssue?}
+   */
+  toIssue(result, check) {
+    if (result.ok) {
+      this.log.info(` ${'\u2714'.green} ${result.message}`);
+      return null;
+    }
+
+    const errorMessage = result.optional
+      ? ` ${'\u2716'.yellow} ${result.message}`
+      : ` ${'\u2716'.red} ${result.message}`;
+    this.log.warn(errorMessage);
+    return {
+      error: errorMessage,
+      check,
+    };
+  }
+
+  /**
+   * @returns {string}
+   */
+  buildFixMessage() {
+    return `${util.pluralize('required fix', this.issuesRequiredToFix.length, true)} needed, ` +
+      `${util.pluralize('optional fix', this.issuesOptionalToFix.length, true)} possible`;
+  }
+
+  /**
+   * @returns {boolean}
+   */
+  reportSuccess() {
+    if (this.issuesRequiredToFix.length === 0 && this.issuesOptionalToFix.length === 0) {
+      this.log.info('Everything looks good, bye!');
+      this.log.info('');
+      return true;
+    }
+    return false;
+  }
+}
+
+/**
+ * @typedef DoctorIssue
+ * @property {DoctorCheck} check
+ * @property {string} error
+ * @property {boolean} [fixed]
+ */
+
+/**
+ * @typedef {import('@appium/types').IDoctorCheck} DoctorCheck
+ * @typedef {import('@appium/types').DoctorCheckResult} DoctorCheckResult
+ */

package/lib/extension/driver-config.js

@@ -135,9 +135,9 @@ export class DriverConfig extends ExtensionConfig {
    * Given capabilities, find a matching driver within the config. Load its class and return it along with version and driver name.
    * @template {import('@appium/types').StringRecord} C
    * @param {C} caps
-   * @returns {MatchedDriver}
+   * @returns {Promise<MatchedDriver>}
    */
-  findMatchingDriver({automationName, platformName}) {
+  async findMatchingDriver({automationName, platformName}) {
     if (!_.isString(platformName)) {
       throw new Error('You must include a platformName capability');
     }
@@ -158,7 +158,7 @@ export class DriverConfig extends ExtensionConfig {
       );
       log.info(`The '${driverName}' driver was installed and matched caps.`);
       log.info(`Will require it at ${this.getInstallPath(driverName)}`);
-      const driver = this.require(driverName);
+      const driver = await this.requireAsync(driverName);
       if (!driver) {
         throw new Error(
           `Driver '${driverName}' did not export a class with name '${mainClass}'. Contact the author of the driver!`

package/lib/extension/extension-config.js

@@ -1,4 +1,4 @@
-import {util} from '@appium/support';
+import {util, fs, system} from '@appium/support';
 import B from 'bluebird';
 import _ from 'lodash';
 import path from 'path';
@@ -12,6 +12,7 @@ import {
   isAllowedSchemaFileExtension,
   registerSchema,
 } from '../schema/schema';
+import { pathToFileURL } from 'url';
 
 /**
  * "npm" install type
@@ -554,28 +555,45 @@ export class ExtensionConfig {
   }
 
   /**
-   * Loads extension and returns its main class (constructor)
+   *
    * @param {ExtName<ExtType>} extName
-   * @returns {ExtClass<ExtType>}
+   * @returns {Promise<[string, string]>}
    */
-  require(extName) {
+  async _resolveExtension(extName) {
     const {mainClass} = this.installedExtensions[extName];
-    const reqPath = this.getInstallPath(extName);
-    /** @type {string} */
-    let reqResolved;
+    const moduleRoot = this.getInstallPath(extName);
+    const packageJsonPath = path.join(moduleRoot, 'package.json');
+    let entryPointPath;
     try {
-      reqResolved = require.resolve(reqPath);
-    } catch (err) {
-      throw new ReferenceError(`Could not find a ${this.extensionType} installed at ${reqPath}`);
+      entryPointPath = JSON.parse(await fs.readFile(packageJsonPath, 'utf8')).main ?? 'index.js';
+    } catch (e) {
+      throw new ReferenceError(`Could not find a ${this.extensionType} installed at ${moduleRoot}`);
+    }
+    if (entryPointPath) {
+      entryPointPath = path.resolve(moduleRoot, entryPointPath);
+    } else {
+      throw new ReferenceError(`Cannot find a valid ${this.extensionType} main entry point in '${packageJsonPath}'`);
     }
     // note: this will only reload the entry point
-    if (process.env.APPIUM_RELOAD_EXTENSIONS && require.cache[reqResolved]) {
-      log.debug(`Removing ${reqResolved} from require cache`);
-      delete require.cache[reqResolved];
+    if (process.env.APPIUM_RELOAD_EXTENSIONS && require.cache[entryPointPath]) {
+      log.debug(`Removing ${entryPointPath} from require cache`);
+      delete require.cache[entryPointPath];
     }
+    return [entryPointPath, mainClass];
+  }
+
+  /**
+   * Loads extension asynchronously and returns its main class (constructor)
+   *
+   * @param {ExtName<ExtType>} extName
+   * @returns {Promise<ExtClass<ExtType>>}
+   */
+  async requireAsync(extName) {
+    const [reqPath, mainClass] = await this._resolveExtension(extName);
     log.debug(`Requiring ${this.extensionType} at ${reqPath}`);
-    // eslint-disable-next-line @typescript-eslint/no-var-requires
-    const MainClass = require(reqPath)[mainClass];
+    // https://github.com/nodejs/node/issues/31710
+    const importPath = system.isWindows() ? pathToFileURL(reqPath).href : reqPath;
+    const MainClass = (await import(importPath))[mainClass];
     if (!MainClass) {
       throw new ReferenceError(
         `Could not find a class named "${mainClass}" exported by ${this.extensionType} "${extName}"`

package/lib/extension/index.js

@@ -3,6 +3,7 @@ import {USE_ALL_PLUGINS} from '../constants';
 import log from '../logger';
 import {DriverConfig} from './driver-config';
 import {Manifest} from './manifest';
+import {timing} from '@appium/support';
 import {PluginConfig} from './plugin-config';
 import B from 'bluebird';
 
@@ -27,6 +28,47 @@ export async function loadExtensions(appiumHome) {
   return {driverConfig, pluginConfig};
 }
 
+/**
+ * @template {'driver'|'plugin'} TExtType
+ * @param {TExtType} extType
+ * @param {import('./extension-config').ExtensionConfig} config
+ * @param {string[]} extNames
+ * @param {number} asyncImportChunkSize
+ * @returns {Promise<[TExtType extends 'driver' ? DriverClass : PluginClass, string][]>}
+ */
+async function importExtensions(extType, config, extNames, asyncImportChunkSize) {
+  /** @type {B[]} */
+  const allPromises = [];
+  /** @type {B[]} */
+  const activePromisesChunk = [];
+  for (const extName of extNames) {
+    _.remove(activePromisesChunk, (p) => p.isFulfilled());
+    if (activePromisesChunk.length >= asyncImportChunkSize) {
+      await B.any(activePromisesChunk);
+    }
+    const promise = B.resolve((async () => {
+      log.info(`Attempting to load ${extType} ${extName}...`);
+      const timer = new timing.Timer().start();
+      try {
+        const extClass = await config.requireAsync(extName);
+        log.debug(`${extClass.name} has been successfully loaded in ${timer.getDuration().asSeconds.toFixed(3)}s`);
+        return extClass;
+      } catch (err) {
+        log.error(
+          `Could not load ${extType} '${extName}', so it will not be available. Error ` +
+            `in loading the ${extType} was: ${err.message}`
+        );
+        log.debug(err.stack);
+      }
+    })());
+    activePromisesChunk.push(promise);
+    allPromises.push(promise);
+  }
+  return /** @type {[TExtType extends 'driver' ? DriverClass : PluginClass, string][]} */ (
+    _.zip(await B.all(allPromises), extNames).filter(([extClass,]) => Boolean(extClass))
+  );
+}
+
 /**
  * Find any plugin name which has been installed, and which has been requested for activation by
  * using the --use-plugins flag, and turn each one into its class, so we can send them as objects
@@ -34,10 +76,15 @@ export async function loadExtensions(appiumHome) {
  * to wrap command execution
  *
  * @param {import('./plugin-config').PluginConfig} pluginConfig - a plugin extension config
+ * @param {number} maxParallelImports the maximum amount of plugins to import in parallel
  * @param {string[]} usePlugins
- * @returns {PluginNameMap} Mapping of PluginClass to name
+ * @returns {Promise<PluginNameMap>} Mapping of PluginClass to name
  */
-export function getActivePlugins(pluginConfig, usePlugins = []) {
+export async function getActivePlugins(pluginConfig, maxParallelImports, usePlugins = []) {
+  if (_.isEmpty(usePlugins)) {
+    return new Map();
+  }
+
   /** @type {string[]} */
   let filteredPluginNames = [];
   if (usePlugins.length === 1 && usePlugins[0] === USE_ALL_PLUGINS) {
@@ -52,31 +99,17 @@ export function getActivePlugins(pluginConfig, usePlugins = []) {
           `The reserved plugin name '${pluginName}' cannot be combined with other names.`
         );
       } else {
+        const suffix = _.isEmpty(pluginConfig.installedExtensions)
+          ? `You don't have any plugins installed yet.`
+          : `Only the following ${_.size(pluginConfig.installedExtensions) === 1 ? `plugin is` : `plugins are`} ` +
+            `available: ${_.keys(pluginConfig.installedExtensions)}`;
         throw new Error(
-          `Could not load the plugin '${pluginName}' because it is not installed. ` +
-          `Only the following plugins are available: ${_.keys(pluginConfig.installedExtensions)}`
+          `Could not load the plugin '${pluginName}' because it is not installed. ${suffix}`
         );
       }
     }
   }
-  return new Map(
-    _.compact(
-      filteredPluginNames
-        .map((pluginName) => {
-          try {
-            log.info(`Attempting to load plugin ${pluginName}...`);
-            const PluginClass = pluginConfig.require(pluginName);
-            return [PluginClass, pluginName];
-          } catch (err) {
-            log.error(
-              `Could not load plugin '${pluginName}', so it will not be available. Error ` +
-                `in loading the plugin was: ${err.message}`
-            );
-            log.debug(err.stack);
-          }
-        })
-    )
-  );
+  return new Map(await importExtensions('plugin', pluginConfig, filteredPluginNames, maxParallelImports));
 }
 
 /**
@@ -85,29 +118,33 @@ export function getActivePlugins(pluginConfig, usePlugins = []) {
  * If the --drivers flag was given, this method only loads the given drivers.
  *
  * @param {import('./driver-config').DriverConfig} driverConfig - a driver extension config
+ * @param {number} maxParallelImports the maximum amount of plugins to import in parallel
  * @param {string[]} [useDrivers] - optional list of drivers to load
- * @returns {DriverNameMap}
+ * @returns {Promise<DriverNameMap>}
  */
-export function getActiveDrivers(driverConfig, useDrivers = []) {
-  return new Map(
-    _.compact(
-      Object.keys(driverConfig.installedExtensions)
-        .filter((driverName) => _.includes(useDrivers, driverName) || useDrivers.length === 0)
-        .map((driverName) => {
-          try {
-            log.info(`Attempting to load driver ${driverName}...`);
-            const DriverClass = driverConfig.require(driverName);
-            return [DriverClass, driverName];
-          } catch (err) {
-            log.error(
-              `Could not load driver '${driverName}', so it will not be available. Error ` +
-                `in loading the driver was: ${err.message}`
-            );
-            log.debug(err.stack);
-          }
-        })
-    )
-  );
+export async function getActiveDrivers(driverConfig, maxParallelImports, useDrivers = []) {
+  /** @type {string[]} */
+  let filteredDriverNames = [];
+  if (_.isEmpty(useDrivers)) {
+    // load all drivers if none are requested
+    filteredDriverNames = _.keys(driverConfig.installedExtensions);
+  } else {
+    // Load drivers in the same order that was used while enumerating them
+    for (const driverName of useDrivers) {
+      if (driverName in driverConfig.installedExtensions) {
+        filteredDriverNames.push(driverName);
+      } else {
+        const suffix = _.isEmpty(driverConfig.installedExtensions)
+          ? `You don't have any drivers installed yet.`
+          : `Only the following ${_.size(driverConfig.installedExtensions) === 1 ? `driver is` : `drivers are`} ` +
+            `available: ${_.keys(driverConfig.installedExtensions)}`;
+        throw new Error(
+          `Could not load the driver '${driverName}' because it is not installed. ${suffix}`
+        );
+      }
+    }
+  }
+  return new Map(await importExtensions('driver', driverConfig, filteredDriverNames, maxParallelImports));
 }
 
 /**

package/lib/grid-register.js

@@ -30,10 +30,9 @@ async function registerNode(data, addr, port, basePath) {
     try {
       data = JSON.parse(data);
     } catch (err) {
-      logger.errorAndThrow(
+      throw logger.errorWithException(
         `Syntax error in node configuration file ${configFilePath}: ${err.message}`
       );
-      return;
     }
   }