appium 2.0.0-beta.24 → 2.0.0-beta.27

package/lib/config-file.js

@@ -113,10 +113,9 @@ export async function readConfigFile (filepath, opts = {}) {
     ? await loadConfigFile(lc, filepath)
     : await searchConfigFile(lc);
 
-  if (result && !result.isEmpty && result.filepath) {
-    const {normalize = true, pretty = true} = opts;
+  if (result?.filepath && !result?.isEmpty) {
+    const {pretty = true} = opts;
     try {
-      /** @type {ReadConfigFileResult} */
       let configResult;
       const errors = validate(result.config);
       if (_.isEmpty(errors)) {
@@ -131,12 +130,10 @@ export async function readConfigFile (filepath, opts = {}) {
           : {...result, errors};
       }
 
-      if (normalize) {
-        // normalize (to camel case) all top-level property names of the config file
-        configResult.config = normalizeConfig(
-          /** @type {AppiumConfig} */ (configResult.config),
-        );
-      }
+      // normalize (to camel case) all top-level property names of the config file
+      configResult.config = normalizeConfig(
+        /** @type {AppiumConfig} */ (configResult.config),
+      );
 
       return configResult;
     } finally {
@@ -152,11 +149,12 @@ export async function readConfigFile (filepath, opts = {}) {
  * @param {AppiumConfig} config - Configuration object
  * @returns {NormalizedAppiumConfig} New object with camel-cased keys (or `dest` keys).
  */
-function normalizeConfig (config) {
+export function normalizeConfig (config) {
   const schema = getSchema();
   /**
    * @param {AppiumConfig} config
    * @param {string} [section] - Keypath (lodash `_.get()` style) to section of config. If omitted, assume root Appium config schema
+   * @todo Rewrite as a loop
    * @returns Normalized section of config
    */
   const normalize = (config, section) => {
@@ -183,19 +181,18 @@ 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 {AppiumConfig} [config] - The parsed configuration
+ * @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.
  */
 
 /**
  * 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.
- * @property {boolean} [normalize=true] If `false`, do not normalize key names to camel case.
  */
 
 /**
@@ -220,7 +217,7 @@ 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

@@ -2,14 +2,13 @@
 
 /* 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';
-import { getDefaultsForSchema } from './schema/schema';
+import { getDefaultsForSchema, getAllArgSpecs } from './schema/schema';
 
 const npmPackage = fs.readPackageJsonFrom(__dirname);
 
@@ -159,21 +158,40 @@ async function showBuildInfo () {
 
 /**
  * Returns k/v pairs of server arguments which are _not_ the defaults.
- * @param {ParsedArgs} args
+ * @param {ParsedArgs} parsedArgs
  * @returns {Partial<ParsedArgs>}
  */
-function getNonDefaultServerArgs (args) {
-  // hopefully these function names are descriptive enough
+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 }>}
+   */
+  const flatten = (args) => {
+    const argSpecs = getAllArgSpecs();
+    const flattened = _.reduce([...argSpecs.values()], (acc, argSpec) => {
+      if (_.has(args, argSpec.dest)) {
+        acc[argSpec.dest] = {value: _.get(args, argSpec.dest), argSpec};
+      }
+      return acc;
+    }, /** @type {Record<string, { value: any, argSpec: import('./schema/arg-spec').ArgSpec }>} */({}));
+
+    return flattened;
+  };
+
+  const args = flatten(parsedArgs);
 
-  const typesDiffer = /** @param {string} dest */(dest) => typeof args[dest] !== typeof defaultsFromSchema[dest];
+  // hopefully these function names are descriptive enough
+  const typesDiffer = /** @param {string} dest */(dest) => typeof args[dest].value !== typeof defaultsFromSchema[dest];
 
   const defaultValueIsArray = /** @param {string} dest */(dest) => _.isArray(defaultsFromSchema[dest]);
 
-  const argsValueIsArray = /** @param {string} dest */(dest) => _.isArray(args[dest]);
+  const argsValueIsArray = /** @param {string} dest */(dest) => _.isArray(args[dest].value);
 
-  const arraysDiffer = /** @param {string} dest */(dest) => _.gt(_.size(_.difference(args[dest], defaultsFromSchema[dest])), 0);
+  const arraysDiffer = /** @param {string} dest */(dest) => _.gt(_.size(_.difference(args[dest].value, defaultsFromSchema[dest])), 0);
 
-  const valuesDiffer = /** @param {string} dest */(dest) => args[dest] !== defaultsFromSchema[dest];
+  const valuesDiffer = /** @param {string} dest */(dest) => args[dest].value !== defaultsFromSchema[dest];
 
   const defaultIsDefined = /** @param {string} dest */(dest) => !_.isUndefined(defaultsFromSchema[dest]);
 
@@ -212,9 +230,13 @@ function getNonDefaultServerArgs (args) {
     ])
   ]);
 
-  const defaultsFromSchema = getDefaultsForSchema();
+  const defaultsFromSchema = getDefaultsForSchema(true);
 
-  return _.pickBy(args, (__, key) => isNotDefault(key));
+  return _.reduce(
+    _.pickBy(args, (__, key) => isNotDefault(key)),
+    // explodes the flattened object back into nested one
+    (acc, {value, argSpec}) => _.set(acc, argSpec.dest, value), /** @type {Partial<ParsedArgs>} */({})
+  );
 }
 
 /**
@@ -236,22 +258,29 @@ const compactConfig = _.partial(
  * The actual shape of `preConfigParsedArgs` and `defaults` does not matter for the purposes of this function,
  * but it's intended to be called with values of type {@link ParsedArgs} and `DefaultValues<true>`, respectively.
  *
- * @param {object} preConfigParsedArgs - Parsed CLI args (or param to `init()`) before config & defaults applied
- * @param {import('./config-file').ReadConfigFileResult} configResult - Result of attempting to load a config file
- * @param {object} defaults - Configuration defaults from schemas
+ * @param {Partial<ParsedArgs>} nonDefaultPreConfigParsedArgs - Parsed CLI args (or param to `init()`) before config & defaults applied
+ * @param {import('./config-file').ReadConfigFileResult} configResult - Result of attempting to load a config file.  _Must_ be normalized
+ * @param {Partial<ParsedArgs>} defaults - Configuration defaults from schemas
+ * @param {ParsedArgs} parsedArgs - Entire parsed args object
  */
-function showConfig (preConfigParsedArgs, configResult, defaults) {
+function showConfig (nonDefaultPreConfigParsedArgs, configResult, defaults, parsedArgs) {
   console.log('Appium Configuration\n');
+  console.log('from defaults:\n');
+  console.dir(compactConfig(defaults));
   if (configResult.config) {
-    console.log(`via config file at ${configResult.filepath}:\n`);
+    console.log(`\nfrom config file at ${configResult.filepath}:\n`);
     console.dir(compactConfig(configResult.config));
   } else {
-    console.log(`(no configuration file loaded)\n`);
+    console.log(`\n(no configuration file loaded)`);
   }
-  console.log('via CLI or function call:\n');
-  console.dir(compactConfig(preConfigParsedArgs));
-  console.log('\nvia defaults:\n');
-  console.dir(compactConfig(defaults));
+  if (_.isEmpty(nonDefaultPreConfigParsedArgs)) {
+    console.log(`\n(no CLI parameters provided)`);
+  } else {
+    console.log('\nvia CLI or function call:\n');
+    console.dir(compactConfig(nonDefaultPreConfigParsedArgs));
+  }
+  console.log('\nfinal configuration:\n');
+  console.dir(compactConfig(parsedArgs));
 }
 
 /**
@@ -259,17 +288,19 @@ function showConfig (preConfigParsedArgs, configResult, defaults) {
  */
 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
 };
 
 /**

package/lib/constants.js

@@ -0,0 +1,79 @@
+// @ts-check
+
+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,230 @@
+// @ts-check
+
+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 {ManifestDriverData} 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 {ManifestDriverData} 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 { { automationName: string, platformName: string } } caps
+   * @returns { { driver: import('./manifest').DriverClass, version: string, driverName: string } }
+   */
+   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 {ManifestDriverData & { driverName: string } }
+   */
+   _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
+ */
+
+/**
+ * @typedef {import('./manifest').ExternalData<DriverType>} ExternalDriverData
+ * @typedef {import('./manifest').ManifestDriverData} ManifestDriverData
+ * @typedef {import('./manifest').ManifestData} ManifestData
+ * @typedef {import('./manifest').DriverType} DriverType
+ * @typedef {import('./manifest').Manifest} Manifest
+ */
+
+/**
+ * @template T
+ * @typedef {import('./extension-config').ExtRecord<T>} ExtRecord
+ */
+
+/**
+ * @template T
+ * @typedef {import('./extension-config').ExtName<T>} ExtName
+ */
+