appium 2.0.0-beta.25 → 2.0.0-beta.28

package/lib/cli/extension.js

@@ -2,11 +2,13 @@
 
 import DriverCommand from './driver-command';
 import PluginCommand from './plugin-command';
-import DriverConfig from '../driver-config';
-import PluginConfig from '../plugin-config';
-import { DRIVER_TYPE } from '../extension-config';
+import { DRIVER_TYPE, PLUGIN_TYPE } from '../constants';
 import { errAndQuit, log, JSON_SPACES } from './utils';
-import { APPIUM_HOME } from './args';
+
+const commandClasses = Object.freeze(/** @type {const} */({
+  [DRIVER_TYPE]: DriverCommand,
+  [PLUGIN_TYPE]: PluginCommand
+}));
 
 /**
  * Run a subcommand of the 'appium driver' type. Each subcommand has its own set of arguments which
@@ -14,13 +16,14 @@ import { APPIUM_HOME } from './args';
  *
  * @param {Object} args - JS object where the key is the parameter name (as defined in
  * driver-parser.js)
- * @param {import('../ext-config-io').ExtensionType} type - Extension type
- * @oaram {ExtensionConfig} [configObject] - Extension config object, if we have one
+ * @template {import('../extension/manifest').ExtensionType} ExtType
+ * @param {import('../extension/extension-config').ExtensionConfig<ExtType>} configObject - Extension config object
  */
-async function runExtensionCommand (args, type, configObject) {
+async function runExtensionCommand (args, configObject) {
   // TODO driver config file should be locked while any of these commands are
   // running to prevent weird situations
   let jsonResult = null;
+  const {extensionType: type} = configObject;
   const extCmd = args[`${type}Command`];
   if (!extCmd) {
     throw new TypeError(`Cannot call ${type} command without a subcommand like 'install'`);
@@ -30,17 +33,11 @@ async function runExtensionCommand (args, type, configObject) {
     json = true;
   }
   const logFn = (msg) => log(json, msg);
-  let config;
-  if (configObject) {
-    config = configObject;
-    config.log = logFn;
-  } else {
-    config = (type === DRIVER_TYPE ? DriverConfig : PluginConfig).getInstance(APPIUM_HOME, logFn);
-  }
-  const CommandClass = type === DRIVER_TYPE ? DriverCommand : PluginCommand;
+  let config = configObject;
+  config.log = logFn;
+  const CommandClass = /** @type {ExtCommand<ExtType>} */(commandClasses[type]);
   const cmd = new CommandClass({config, json});
   try {
-    await config.read();
     jsonResult = await cmd.execute(args);
   } catch (err) {
     // in the suppress output case, we are calling this function internally and should
@@ -61,3 +58,8 @@ async function runExtensionCommand (args, type, configObject) {
 export {
   runExtensionCommand,
 };
+
+/**
+ * @template {import('../../types').ExtensionType} ExtType
+ * @typedef {ExtType extends import('../../types').DriverType ? import('@appium/types').Class<DriverCommand> : ExtType extends import('../../types').PluginType ? import('@appium/types').Class<PluginCommand> : never} ExtCommand
+ */

package/lib/cli/parser.js

@@ -1,22 +1,16 @@
-// @ts-check
 
 import { fs } from '@appium/support';
 import { ArgumentParser } from 'argparse';
-import B from 'bluebird';
 import _ from 'lodash';
 import path from 'path';
-import { DRIVER_TYPE, PLUGIN_TYPE } from '../extension-config';
+import { DRIVER_TYPE, PLUGIN_TYPE, SERVER_SUBCOMMAND } from '../constants';
 import { finalizeSchema, getArgSpec, hasArgSpec } from '../schema';
-import { rootDir } from '../utils';
+import { rootDir } from '../config';
 import {
-  driverConfig,
   getExtensionArgs,
-  getServerArgs,
-  pluginConfig
+  getServerArgs
 } from './args';
 
-export const SERVER_SUBCOMMAND = 'server';
-
 /**
  * If the parsed args do not contain any of these values, then we
  * will automatially inject the `server` subcommand.
@@ -106,7 +100,7 @@ class ArgParser {
    *
    * `ArgParser.prototype.parse_args` is an alias of this method.
    * @param {string[]} [args] - Array of arguments, ostensibly from `process.argv`. Gathers args from `process.argv` if not provided.
-   * @returns {import('../../types/types').ParsedArgs} - The parsed arguments
+   * @returns {import('../../types/cli').ParsedArgs} - The parsed arguments
    */
   parseArgs (args = process.argv.slice(2)) {
     if (!NON_SERVER_ARGS.has(args[0])) {
@@ -258,19 +252,16 @@ class ArgParser {
 }
 
 /**
- * Creates a {@link ArgParser} instance.  Necessarily reads extension configuration
- * beforehand, and finalizes the config schema.
+ * Creates a {@link ArgParser} instance; finalizes the config schema.
  *
  * @constructs ArgParser
  * @param {boolean} [debug] - If `true`, throw instead of exit upon parsing error
- * @returns {Promise<ArgParser>}
+ * @returns {ArgParser}
  */
-async function getParser (debug = false) {
-  await B.all([driverConfig.read(), pluginConfig.read()]);
+function getParser (debug) {
   finalizeSchema();
 
   return new ArgParser(debug);
 }
 
-export default getParser;
 export { getParser, ArgParser };

package/lib/cli/plugin-command.js

@@ -1,31 +1,34 @@
 import _ from 'lodash';
 import ExtensionCommand from './extension-command';
-import { PLUGIN_TYPE } from '../extension-config';
-import { KNOWN_PLUGINS } from '../plugins';
+import { KNOWN_PLUGINS } from '../constants';
 
 const REQ_PLUGIN_FIELDS = ['pluginName', 'mainClass'];
 
 export default class PluginCommand extends ExtensionCommand {
 
+  /**
+   *
+   * @param {PluginCommandOptions} opts
+   */
   constructor ({config, json}) {
-    super({config, json, type: PLUGIN_TYPE});
+    super({config, json});
     this.knownExtensions = KNOWN_PLUGINS;
   }
 
   async install ({plugin, installType, packageName}) {
-    return await super.install({ext: plugin, installType, packageName});
+    return await super._install({ext: plugin, installType, packageName});
   }
 
   async uninstall ({plugin}) {
-    return await super.uninstall({ext: plugin});
+    return await super._uninstall({ext: plugin});
   }
 
   async update ({plugin, unsafe}) {
-    return await super.update({ext: plugin, unsafe});
+    return await super._update({ext: plugin, unsafe});
   }
 
   async run ({plugin, scriptName}) {
-    return await super.run({ext: plugin, scriptName});
+    return await super._run({ext: plugin, scriptName});
   }
 
   getPostInstallText ({extName, extData}) {
@@ -45,3 +48,9 @@ export default class PluginCommand extends ExtensionCommand {
   }
 
 }
+
+/**
+ * @typedef PluginCommandOptions
+ * @property {import('../extension/extension-config').ExtensionConfig<import('../extension/manifest').PluginType>} config
+ * @property {boolean} json
+ */

package/lib/cli/utils.js

@@ -7,7 +7,7 @@ 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 {string} msg - error message
+ * @param {any} msg - error message, object, Error instance, etc.
  */
 function errAndQuit (json, msg) {
   if (json) {

package/lib/config-file.js

@@ -1,4 +1,3 @@
-// @ts-check
 
 import betterAjvErrors from '@sidvind/better-ajv-errors';
 import { lilconfig } from 'lilconfig';
@@ -181,17 +180,17 @@ export function normalizeConfig (config) {
 
 /**
  * Result of calling {@link readConfigFile}.
- * @typedef {Object} ReadConfigFileResult
+ * @typedef ReadConfigFileResult
  * @property {import('ajv').ErrorObject[]} [errors] - Validation errors
  * @property {string} [filepath] - The path to the config file, if found
  * @property {boolean} [isEmpty] - If `true`, the config file exists but is empty
  * @property {NormalizedAppiumConfig} [config] - The parsed configuration
- * @property {string|betterAjvErrors.IOutputError[]} [reason] - Human-readable error messages and suggestions. If the `pretty` option is `true`, this will be a nice string to print.
+ * @property {string|import('@sidvind/better-ajv-errors').IOutputError[]} [reason] - Human-readable error messages and suggestions. If the `pretty` option is `true`, this will be a nice string to print.
  */
 
 /**
  * Options for {@link readConfigFile}.
- * @typedef {Object} ReadConfigFileOptions
+ * @typedef ReadConfigFileOptions
  * @property {boolean} [pretty=true] If `false`, do not use color and fancy formatting in the `reason` property of the {@link ReadConfigFileResult}. The value of `reason` is then suitable for machine-reading.
  */
 
@@ -202,12 +201,12 @@ export function normalizeConfig (config) {
 
 /**
  * The contents of an Appium config file. Generated from schema
- * @typedef {import('../types/types').AppiumConfig} AppiumConfig
+ * @typedef {import('@appium/types').AppiumConfig} AppiumConfig
  */
 
 /**
  * The contents of an Appium config file with camelcased property names (and using `appiumCliDest` value if present). Generated from {@link AppiumConfig}
- * @typedef {import('../types/types').NormalizedAppiumConfig} NormalizedAppiumConfig
+ * @typedef {import('@appium/types').NormalizedAppiumConfig} NormalizedAppiumConfig
  */
 
 /**
@@ -217,7 +216,7 @@ export function normalizeConfig (config) {
 
 /**
  * Options for {@link formatErrors}.
- * @typedef {Object} FormatConfigErrorsOptions
+ * @typedef FormatConfigErrorsOptions
  * @property {import('./config-file').RawJson} [json] - Raw JSON config (as string)
  * @property {boolean} [pretty=true] - Whether to format errors as a CLI-friendly string
  * @property {string}  [schemaId] - Specific ID of a prop; otherwise entire schema

package/lib/config.js

@@ -1,11 +1,8 @@
-// @ts-check
-
 /* eslint-disable no-console */
 import _ from 'lodash';
-import { mkdirp, system, fs } from '@appium/support';
+import { system, fs } from '@appium/support';
 import axios from 'axios';
 import { exec } from 'teen_process';
-import { rootDir } from './utils';
 import logger from './logger';
 import semver from 'semver';
 import findUp from 'find-up';
@@ -20,6 +17,9 @@ const GIT_META_ROOT = '.git';
 const GIT_BINARY = `git${system.isWindows() ? '.exe' : ''}`;
 const GITHUB_API = 'https://api.github.com/repos/appium/appium';
 
+/**
+ * @type {import('../types/cli').BuildInfo}
+ */
 const BUILD_INFO = {
   version: APPIUM_VER,
 };
@@ -35,7 +35,7 @@ async function updateBuildInfo (useGithubApiFallback = false) {
   }
   BUILD_INFO['git-sha'] = sha;
   const built = await getGitTimestamp(sha, useGithubApiFallback);
-  if (!_.isEmpty(built)) {
+  if (built) {
     BUILD_INFO.built = built;
   }
 }
@@ -86,7 +86,7 @@ async function getGitRev (useGithubApiFallback = false) {
 /**
  * @param {string} commitSha
  * @param {boolean} [useGithubApiFallback]
- * @returns {Promise<number?>}
+ * @returns {Promise<string?>}
  */
 async function getGitTimestamp (commitSha, useGithubApiFallback = false) {
   const gitRoot = await findGitRoot();
@@ -122,10 +122,11 @@ async function getGitTimestamp (commitSha, useGithubApiFallback = false) {
 }
 
 /**
- * @return Mutable object containing Appium build information. By default it
+ * Mutable object containing Appium build information. By default it
  * only contains the Appium version, but is updated with the build timestamp
  * and git commit hash asynchronously as soon as `updateBuildInfo` is called
  * and succeeds.
+ * @returns {import('../types/cli').BuildInfo}
  */
 function getBuildInfo () {
   return BUILD_INFO;
@@ -167,7 +168,7 @@ function getNonDefaultServerArgs (parsedArgs) {
    * Flattens parsed args into a single level object for comparison with
    * flattened defaults across server args and extension args.
    * @param {ParsedArgs} args
-   * @returns {Record<string, { value: any, argSpec: import('./schema/arg-spec').ArgSpec }>}
+   * @returns {Record<string, { value: any, argSpec: ArgSpec }>}
    */
   const flatten = (args) => {
     const argSpecs = getAllArgSpecs();
@@ -176,7 +177,7 @@ function getNonDefaultServerArgs (parsedArgs) {
         acc[argSpec.dest] = {value: _.get(args, argSpec.dest), argSpec};
       }
       return acc;
-    }, /** @type {Record<string, { value: any, argSpec: import('./schema/arg-spec').ArgSpec }>} */({}));
+    }, /** @type {Record<string, { value: any, argSpec: ArgSpec }>} */({}));
 
     return flattened;
   };
@@ -289,19 +290,23 @@ function showConfig (nonDefaultPreConfigParsedArgs, configResult, defaults, pars
  */
 async function validateTmpDir (tmpDir) {
   try {
-    await mkdirp(tmpDir);
+    await fs.mkdirp(tmpDir);
   } catch (e) {
     throw new Error(`We could not ensure that the temp dir you specified ` +
                     `(${tmpDir}) exists. Please make sure it's writeable.`);
   }
 }
 
+const rootDir = fs.findRoot(__dirname);
+
 export {
   getBuildInfo, checkNodeOk, showBuildInfo,
   warnNodeDeprecations, validateTmpDir, getNonDefaultServerArgs,
-  getGitRev, APPIUM_VER, updateBuildInfo, showConfig
+  getGitRev, APPIUM_VER, updateBuildInfo, showConfig, rootDir
 };
 
 /**
- * @typedef {import('../types/types').ParsedArgs} ParsedArgs
+ * @typedef {import('../types/cli').ParsedArgs} ParsedArgs
+ * @typedef {import('./schema/arg-spec').ArgSpec} ArgSpec
  */
+

package/lib/constants.js

@@ -0,0 +1,78 @@
+
+import path from 'path';
+
+/**
+ * The name of the extension type for drivers
+ */
+export const DRIVER_TYPE = 'driver';
+
+/**
+ * The name of the extension type for plugins
+ */
+export const PLUGIN_TYPE = 'plugin';
+
+/**
+ * The `server` command of the `appium` CLI
+ */
+export const SERVER_SUBCOMMAND = 'server';
+
+/**
+ * The value of `--use-plugins` if _all_ plugins should be loaded
+ */
+export const USE_ALL_PLUGINS = 'all';
+
+// This is a map of plugin names to npm packages representing those plugins.
+// The plugins in this list will be available to the CLI so users can just
+// type 'appium plugin install 'name'', rather than having to specify the full
+// npm package. I.e., these are the officially recognized plugins.
+export const KNOWN_PLUGINS = Object.freeze(
+  /** @type {const} */ ({
+    images: '@appium/images-plugin',
+    'execute-driver': '@appium/execute-driver-plugin',
+    'relaxed-caps': '@appium/relaxed-caps-plugin',
+  }),
+);
+
+// This is a map of driver names to npm packages representing those drivers.
+// The drivers in this list will be available to the CLI so users can just
+// type 'appium driver install 'name'', rather than having to specify the full
+// npm package. I.e., these are the officially recognized drivers.
+export const KNOWN_DRIVERS = Object.freeze(
+  /** @type {const} */ ({
+    uiautomator2: 'appium-uiautomator2-driver',
+    xcuitest: 'appium-xcuitest-driver',
+    youiengine: 'appium-youiengine-driver',
+    windows: 'appium-windows-driver',
+    mac: 'appium-mac-driver',
+    mac2: 'appium-mac2-driver',
+    espresso: 'appium-espresso-driver',
+    tizen: 'appium-tizen-driver',
+    flutter: 'appium-flutter-driver',
+    safari: 'appium-safari-driver',
+    gecko: 'appium-geckodriver',
+  }),
+);
+
+/**
+ * Relative path to directory containing any Appium internal files
+ */
+export const CACHE_DIR_RELATIVE_PATH = path.join(
+  'node_modules',
+  '.cache',
+  'appium',
+);
+
+/**
+ * Relative path to hashfile (from `APPIUM_HOME`) of consuming project's `package.json` (if it exists)
+ */
+export const PKG_HASHFILE_RELATIVE_PATH = path.join(
+  CACHE_DIR_RELATIVE_PATH,
+  'package.hash',
+);
+
+
+export const EXT_SUBCOMMAND_LIST = 'list';
+export const EXT_SUBCOMMAND_INSTALL = 'install';
+export const EXT_SUBCOMMAND_UNINSTALL = 'uninstall';
+export const EXT_SUBCOMMAND_UPDATE = 'update';
+export const EXT_SUBCOMMAND_RUN = 'run';

package/lib/extension/driver-config.js

@@ -0,0 +1,249 @@
+
+import _ from 'lodash';
+import { DRIVER_TYPE } from '../constants';
+import log from '../logger';
+import { ExtensionConfig } from './extension-config';
+
+/**
+ * @extends {ExtensionConfig<DriverType>}
+ */
+export class DriverConfig extends ExtensionConfig {
+
+  /**
+   * A set of unique automation names used by drivers.
+   * @type {Set<string>}
+   */
+  knownAutomationNames;
+
+  /**
+   * A mapping of {@link Manifest} instances to {@link DriverConfig} instances.
+   *
+   * `Manifest` and `ExtensionConfig` have a one-to-many relationship; each `Manifest` should be associated with a `DriverConfig` and a `PluginConfig`; no more, no less.
+   *
+   * This variable tracks the `Manifest`-to-`DriverConfig` portion.
+   *
+   * @type {WeakMap<Manifest,DriverConfig>}
+   * @private
+   */
+   static _instances = new WeakMap();
+
+   /**
+   * Call {@link DriverConfig.create} instead.
+   * @private
+   * @param {import('./manifest').Manifest} manifest - Manifest instance
+   * @param {DriverConfigOptions} [opts]
+   */
+   constructor (manifest, {logFn, extData} = {}) {
+     super(DRIVER_TYPE, manifest, logFn);
+
+     this.knownAutomationNames = new Set();
+
+     if (extData) {
+       this.validate(extData);
+     }
+   }
+
+   /**
+    * Creates a new {@link DriverConfig} instance for a {@link Manifest} instance.
+    *
+    * @param {Manifest} manifest
+    * @param {DriverConfigOptions} [opts]
+    * @throws If `manifest` already associated with a `DriverConfig`
+    * @returns {DriverConfig}
+    */
+   static create (manifest, {extData, logFn} = {}) {
+     const instance = new DriverConfig(manifest, {logFn, extData});
+     if (DriverConfig.getInstance(manifest)) {
+       throw new Error(`Manifest with APPIUM_HOME ${manifest.appiumHome} already has a DriverConfig; use DriverConfig.getInstance() to retrieve it.`);
+     }
+     DriverConfig._instances.set(manifest, instance);
+     return instance;
+   }
+
+   /**
+    * Returns a DriverConfig associated with a Manifest
+    * @param {Manifest} manifest
+    * @returns {DriverConfig|undefined}
+    */
+   static getInstance (manifest) {
+     return DriverConfig._instances.get(manifest);
+   }
+
+   /**
+   * Checks extensions for problems
+   * @param {ExtRecord<DriverType>} exts
+   */
+   validate (exts) {
+     this.knownAutomationNames.clear();
+     return super.validate(exts);
+   }
+
+   /**
+   * @param {ExtManifest<DriverType>} extData
+   * @returns {import('./extension-config').Problem[]}
+   */
+   getConfigProblems (extData) {
+     const problems = [];
+     const {platformNames, automationName} = extData;
+
+     if (!_.isArray(platformNames)) {
+       problems.push({
+         err: 'Missing or incorrect supported platformNames list.',
+         val: platformNames
+       });
+     } else {
+       if (_.isEmpty(platformNames)) {
+         problems.push({
+           err: 'Empty platformNames list.',
+           val: platformNames
+         });
+       } else {
+         for (const pName of platformNames) {
+           if (!_.isString(pName)) {
+             problems.push({err: 'Incorrectly formatted platformName.', val: pName});
+           }
+         }
+       }
+     }
+
+     if (!_.isString(automationName)) {
+       problems.push({err: 'Missing or incorrect automationName', val: automationName});
+     }
+
+     if (this.knownAutomationNames.has(automationName)) {
+       problems.push({
+         err: 'Multiple drivers claim support for the same automationName',
+         val: automationName
+       });
+     }
+
+     // should we retain the name at the end of this function, once we've checked there are no problems?
+     this.knownAutomationNames.add(automationName);
+
+     return problems;
+   }
+
+   /**
+   * @param {ExtName<DriverType>} driverName
+   * @param {ExtManifest<DriverType>} extData
+   * @returns {string}
+   */
+   extensionDesc (driverName, {version, automationName}) {
+     return `${driverName}@${version} (automationName '${automationName}')`;
+   }
+
+   /**
+   * Given capabilities, find a matching driver within the config. Load its class and return it along with version and driver name.
+   * @param {Capabilities} caps
+   * @returns {MatchedDriver}
+   */
+   findMatchingDriver ({automationName, platformName}) {
+     if (!_.isString(platformName)) {
+       throw new Error('You must include a platformName capability');
+     }
+
+     if (!_.isString(automationName)) {
+       throw new Error('You must include an automationName capability');
+     }
+
+     log.info(`Attempting to find matching driver for automationName ` +
+             `'${automationName}' and platformName '${platformName}'`);
+
+     try {
+       const {
+         driverName,
+         mainClass,
+         version,
+       } = this._getDriverBySupport(automationName, platformName);
+       log.info(`The '${driverName}' driver was installed and matched caps.`);
+       log.info(`Will require it at ${this.getInstallPath(driverName)}`);
+       const driver = this.require(driverName);
+       if (!driver) {
+         throw new Error(`Driver '${driverName}' did not export a class with name '${mainClass}'. Contact the author of the driver!`);
+       }
+       return {driver, version, driverName};
+     } catch (err) {
+       const msg = `Could not find a driver for automationName ` +
+                  `'${automationName}' and platformName ${platformName}'. ` +
+                  `Have you installed a driver that supports those ` +
+                  `capabilities? Run 'appium driver list --installed' to see. ` +
+                  `(Lower-level error: ${err.message})`;
+       throw new Error(msg);
+     }
+   }
+
+   /**
+   * Given an automation name and platform name, find a suitable driver and return its extension data.
+   * @param {string} matchAutomationName
+   * @param {string} matchPlatformName
+   * @returns {ExtMetadata<DriverType> & import('../../types/appium-manifest').InternalMetadata & import('../../types/external-manifest').CommonMetadata}
+   */
+   _getDriverBySupport (matchAutomationName, matchPlatformName) {
+     const drivers = this.installedExtensions;
+     for (const [driverName, driverData] of _.toPairs(drivers)) {
+       const {automationName, platformNames} = driverData;
+       const aNameMatches = automationName.toLowerCase() === matchAutomationName.toLowerCase();
+       const pNameMatches = _.includes(platformNames.map(_.toLower),
+                                      matchPlatformName.toLowerCase());
+
+       if (aNameMatches && pNameMatches) {
+         return {driverName, ...driverData};
+       }
+
+       if (aNameMatches) {
+         throw new Error(`Driver '${driverName}' supports automationName ` +
+                        `'${automationName}', but Appium could not find ` +
+                        `support for platformName '${matchPlatformName}'. Supported ` +
+                        `platformNames are: ` +
+                        JSON.stringify(platformNames));
+       }
+     }
+
+     throw new Error(`Could not find installed driver to support given caps`);
+   }
+}
+
+/**
+ * @typedef DriverConfigOptions
+ * @property {import('./extension-config').ExtensionLogFn} [logFn] - Optional logging function
+ * @property {ManifestData['drivers']} [extData] - Extension data
+ */
+
+/**
+ * @template T
+ * @typedef {import('../../types').ExtMetadata<T>} ExtMetadata
+ */
+
+/**
+ * @template T
+ * @typedef {import('../../types').ExtManifest<T>} ExtManifest
+ */
+
+/**
+ * @typedef {import('../../types').ManifestData} ManifestData
+ * @typedef {import('../../types').DriverType} DriverType
+ * @typedef {import('./manifest').Manifest} Manifest
+ */
+
+/**
+ * @template T
+ * @typedef {import('../../types').ExtRecord<T>} ExtRecord
+ */
+
+/**
+ * @template T
+ * @typedef {import('../../types').ExtName<T>} ExtName
+ */
+
+
+/**
+ * Return value of {@linkcode DriverConfig.findMatchingDriver}
+ * @typedef MatchedDriver
+ * @property {import('../../types/extension').DriverClass} driver
+ * @property {string} version
+ * @property {string} driverName
+ */
+
+/**
+ * @typedef {import('@appium/types').Capabilities} Capabilities
+ */