appium 2.0.0-beta.2 → 2.0.0-beta.23

package/lib/config.js

@@ -1,14 +1,15 @@
 import _ from 'lodash';
-import path from 'path';
-import { mkdirp, fs, system } from 'appium-support';
+import { mkdirp, 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 { getDefaultsFromSchema } from './schema/schema';
 
+const npmPackage = fs.readPackageJsonFrom(__dirname);
 
-const npmPackage = require(path.resolve(rootDir, 'package.json'));
 const APPIUM_VER = npmPackage.version;
 const MIN_NODE_VERSION = npmPackage.engines.node;
 
@@ -36,11 +37,23 @@ 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 {string|void} Path to dir or `undefined` if not found
+ */
+async function findGitRoot () {
+  return await findUp(GIT_META_ROOT, {cwd: rootDir, type: 'directory'});
+}
+
 async function getGitRev (useGithubApiFallback = false) {
-  if (await fs.exists(path.resolve(rootDir, GIT_META_ROOT))) {
+  const gitRoot = await findGitRoot();
+  if (gitRoot) {
     try {
       const {stdout} = await exec(GIT_BINARY, ['rev-parse', 'HEAD'], {
-        cwd: rootDir
+        cwd: gitRoot
       });
       return stdout.trim();
     } catch (ign) {}
@@ -68,10 +81,11 @@ async function getGitRev (useGithubApiFallback = false) {
 }
 
 async function getGitTimestamp (commitSha, useGithubApiFallback = false) {
-  if (await fs.exists(path.resolve(rootDir, GIT_META_ROOT))) {
+  const gitRoot = await findGitRoot();
+  if (gitRoot) {
     try {
       const {stdout} = await exec(GIT_BINARY, ['show', '-s', '--format=%ci', commitSha], {
-        cwd: rootDir
+        cwd: gitRoot
       });
       return stdout.trim();
     } catch (ign) {}
@@ -135,65 +149,72 @@ async function showConfig () {
   console.log(JSON.stringify(getBuildInfo())); // eslint-disable-line no-console
 }
 
-function getNonDefaultArgs (parser, args) {
-  let nonDefaults = {};
-  for (let rawArg of parser.rawArgs) {
-    let arg = rawArg[1].dest;
-    if (args[arg] && args[arg] !== rawArg[1].defaultValue) {
-      nonDefaults[arg] = args[arg];
-    }
+function getNonDefaultServerArgs (parser, args) {
+  // hopefully these function names are descriptive enough
+
+  function typesDiffer (dest) {
+    return typeof args[dest] !== typeof defaultsFromSchema[dest];
   }
-  return nonDefaults;
-}
 
-function checkValidPort (port, portName) {
-  if (port > 0 && port < 65536) return true; // eslint-disable-line curly
-  logger.error(`Port '${portName}' must be greater than 0 and less than 65536. Currently ${port}`);
-  return false;
-}
+  function defaultValueIsArray (dest) {
+    return _.isArray(defaultsFromSchema[dest]);
+  }
 
-function validateServerArgs (parser, args) {
-  // arguments that cannot both be set
-  let exclusives = [
-    ['noReset', 'fullReset'],
-    ['ipa', 'safari'],
-    ['app', 'safari'],
-    ['forceIphone', 'forceIpad'],
-    ['deviceName', 'defaultDevice']
-  ];
-
-  for (let exSet of exclusives) {
-    let numFoundInArgs = 0;
-    for (let opt of exSet) {
-      if (_.has(args, opt) && args[opt]) {
-        numFoundInArgs++;
-      }
-    }
-    if (numFoundInArgs > 1) {
-      throw new Error(`You can't pass in more than one argument from the ` +
-                      `set ${JSON.stringify(exSet)}, since they are ` +
-                      `mutually exclusive`);
-    }
+  function argsValueIsArray (dest) {
+    return _.isArray(args[dest]);
   }
 
-  const validations = {
-    port: checkValidPort,
-    callbackPort: checkValidPort,
-    bootstrapPort: checkValidPort,
-    chromedriverPort: checkValidPort,
-    robotPort: checkValidPort,
-    backendRetries: (r) => r >= 0
-  };
-
-  const nonDefaultArgs = getNonDefaultArgs(parser, args);
-
-  for (let [arg, validator] of _.toPairs(validations)) {
-    if (_.has(nonDefaultArgs, arg)) {
-      if (!validator(args[arg], arg)) {
-        throw new Error(`Invalid argument for param ${arg}: ${args[arg]}`);
-      }
-    }
+  function arraysDiffer (dest) {
+    return _.difference(args[dest], defaultsFromSchema[dest]).length > 0;
+  }
+
+  function valuesUnequal (dest) {
+    return args[dest] !== defaultsFromSchema[dest];
+  }
+
+  function defaultIsDefined (dest) {
+    return !_.isUndefined(defaultsFromSchema[dest]);
   }
+
+  // note that `_.overEvery` is like an "AND", and `_.overSome` is like an "OR"
+
+  const argValueNotArrayOrArraysDiffer = _.overSome([
+    _.negate(argsValueIsArray),
+    arraysDiffer
+  ]);
+
+  const defaultValueNotArrayAndValuesUnequal = _.overEvery([
+    _.negate(defaultValueIsArray), valuesUnequal
+  ]);
+
+  /**
+   * This used to be a hideous conditional, but it's broken up into a hideous function instead.
+   * hopefully this makes things a little more understandable.
+   * - checks if the default value is defined
+   * - if so, and the default is not an array:
+   *   - ensures the types are the same
+   *   - ensures the values are equal
+   * - if so, and the default is an array:
+   *   - ensures the args value is an array
+   *   - ensures the args values do not differ from the default values
+   * @param {string} dest - argument name (`dest` value)
+   * @returns {boolean}
+   */
+  const isNotDefault = _.overEvery([
+    defaultIsDefined,
+    _.overSome([
+      typesDiffer,
+      _.overEvery([
+        defaultValueIsArray,
+        argValueNotArrayOrArraysDiffer
+      ]),
+      defaultValueNotArrayAndValuesUnequal
+    ])
+  ]);
+
+  const defaultsFromSchema = getDefaultsFromSchema();
+
+  return _.pickBy(args, (__, key) => isNotDefault(key));
 }
 
 async function validateTmpDir (tmpDir) {
@@ -206,7 +227,7 @@ async function validateTmpDir (tmpDir) {
 }
 
 export {
-  getBuildInfo, validateServerArgs, checkNodeOk, showConfig,
-  warnNodeDeprecations, validateTmpDir, getNonDefaultArgs,
-  getGitRev, checkValidPort, APPIUM_VER, updateBuildInfo,
+  getBuildInfo, checkNodeOk, showConfig,
+  warnNodeDeprecations, validateTmpDir, getNonDefaultServerArgs,
+  getGitRev, APPIUM_VER, updateBuildInfo
 };

package/lib/driver-config.js

@@ -1,25 +1,74 @@
+// @ts-check
+
 import _ from 'lodash';
-import ExtensionConfig, { DRIVER_TYPE } from './extension-config';
+import ExtensionConfig from './extension-config';
+import { DRIVER_TYPE } from './ext-config-io';
 
 export default class DriverConfig extends ExtensionConfig {
-  constructor (appiumHome, logFn = null) {
+  /**
+   * A mapping of `APPIUM_HOME` values to {@link DriverConfig} instances.
+   * Each `APPIUM_HOME` should only have one associated `DriverConfig` instance.
+   * @type {Record<string,DriverConfig>}
+   * @private
+   */
+  static _instances = {};
+
+  /**
+   * Call {@link DriverConfig.getInstance} instead.
+   * @private
+   * @param {string} appiumHome
+   * @param {(...args: any[]) => void} [logFn]
+   */
+  constructor (appiumHome, logFn) {
     super(appiumHome, DRIVER_TYPE, logFn);
+    /** @type {Set<string>} */
+    this.knownAutomationNames = new Set();
+  }
+
+  async read () {
+    this.knownAutomationNames.clear();
+    return await super.read();
   }
 
-  getConfigProblems (driver) {
+  /**
+   * Creates or gets an instance of {@link DriverConfig} based value of `appiumHome`
+   * @param {string} appiumHome - `APPIUM_HOME` path
+   * @param {(...args: any[]) => void} [logFn] - Optional logging function
+   * @returns {DriverConfig}
+   */
+  static getInstance (appiumHome, logFn) {
+    const instance = DriverConfig._instances[appiumHome] ?? new DriverConfig(appiumHome, logFn);
+    DriverConfig._instances[appiumHome] = instance;
+    return instance;
+  }
+
+  /**
+   *
+   * @param {object} extData
+   * @param {string} extName
+   * @returns {import('./extension-config').Problem[]}
+   */
+  // eslint-disable-next-line no-unused-vars
+  getConfigProblems (extData, extName) {
     const problems = [];
-    const automationNames = [];
-    const {platformNames, automationName} = driver;
+    const {platformNames, automationName} = extData;
 
     if (!_.isArray(platformNames)) {
       problems.push({
-        err: 'Missing or incorrect supported platformName list.',
+        err: 'Missing or incorrect supported platformNames list.',
         val: platformNames
       });
     } else {
-      for (const pName of platformNames) {
-        if (!_.isString(pName)) {
-          problems.push({err: 'Incorrectly formatted platformName.', val: pName});
+      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});
+          }
         }
       }
     }
@@ -28,17 +77,23 @@ export default class DriverConfig extends ExtensionConfig {
       problems.push({err: 'Missing or incorrect automationName', val: automationName});
     }
 
-    if (_.includes(automationNames, automationName)) {
+    if (this.knownAutomationNames.has(automationName)) {
       problems.push({
         err: 'Multiple drivers claim support for the same automationName',
         val: automationName
       });
     }
-    automationNames.push(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 {string} driverName
+   * @param {object} extData
+   */
   extensionDesc (driverName, {version, automationName}) {
     return `${driverName}@${version} (automationName '${automationName}')`;
   }

package/lib/drivers.js

@@ -12,9 +12,12 @@ const KNOWN_DRIVERS = {
   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',
 };
 
 function getDriverBySupport (drivers, matchAutomationName, matchPlatformName) {
@@ -64,7 +67,7 @@ function findMatchingDriver (config, {automationName, platformName}) {
     if (!driver) {
       throw new Error(`MainClass ${mainClass} did not result in a driver object`);
     }
-    return {driver, version};
+    return {driver, version, driverName};
   } catch (err) {
     const msg = `Could not find a driver for automationName ` +
                 `'${automationName}' and platformName ${platformName}'. ` +

package/lib/ext-config-io.js

@@ -0,0 +1,287 @@
+// @ts-check
+
+/**
+ * Module containing {@link ExtConfigIO} which handles reading & writing of extension config files.
+ */
+
+import { fs, mkdirp } from '@appium/support';
+import _ from 'lodash';
+import path from 'path';
+import YAML from 'yaml';
+
+const CONFIG_FILE_NAME = 'extensions.yaml';
+
+/**
+ * Current configuration schema revision!
+ */
+const CONFIG_SCHEMA_REV = 2;
+
+export const DRIVER_TYPE = 'driver';
+export const PLUGIN_TYPE = 'plugin';
+
+/**
+ * Set of valid extension types.
+ * @type {Readonly<Set<ExtensionType>>}
+ */
+const VALID_EXT_TYPES = new Set([DRIVER_TYPE, PLUGIN_TYPE]);
+
+const CONFIG_DATA_DRIVER_KEY = `${DRIVER_TYPE}s`;
+const CONFIG_DATA_PLUGIN_KEY = `${PLUGIN_TYPE}s`;
+
+/**
+ * Handles reading & writing of extension config files.
+ *
+ * Only one instance of this class exists per value of `APPIUM_HOME`.
+ */
+class ExtConfigIO {
+  /**
+   * "Dirty" flag. If true, the data has changed since the last write.
+   * @type {boolean}
+   * @private
+   */
+  _dirty;
+
+  /**
+   * The entire contents of a parsed YAML extension config file.
+   * @type {object?}
+   * @private
+   */
+  _data;
+
+  /**
+   * A mapping of extension type to configuration data. Configuration data is
+   * keyed on extension name.
+   *
+   * Consumers get the values of this `Map` (corresponding to the
+   * `extensionType` of the consumer, which will be a subclass of
+   * `ExtensionConfig`) and do not have access to the entire data object.
+   * @private
+   * @type {Map<ExtensionType,object>}
+   */
+  _extDataByType = new Map();
+
+  /**
+   * Path to config file.
+   * @private
+   * @type {Readonly<string>}
+   */
+  _filepath;
+
+  /**
+   * Path to `APPIUM_HOME`
+   * @private
+   * @type {Readonly<string>}
+   */
+  _appiumHome;
+
+  /**
+   * Helps avoid writing multiple times.
+   *
+   * If this is `null`, calling {@link ExtConfigIO.write} will cause it to be
+   * set to a `Promise`. When the call to `write()` is complete, the `Promise`
+   * will resolve and then this value will be set to `null`.  Concurrent calls
+   * made while this value is a `Promise` will return the `Promise` itself.
+   * @private
+   * @type {Promise<boolean>?}
+   */
+  _writing = null;
+
+  /**
+   * Helps avoid reading multiple times.
+   *
+   * If this is `null`, calling {@link ExtConfigIO.read} will cause it to be
+   * set to a `Promise`. When the call to `read()` is complete, the `Promise`
+   * will resolve and then this value will be set to `null`.  Concurrent calls
+   * made while this value is a `Promise` will return the `Promise` itself.
+   * @private
+   * @type {Promise<void>?}
+   */
+  _reading = null;
+
+  /**
+   * @param {string} appiumHome
+   */
+  constructor (appiumHome) {
+    this._filepath = path.resolve(appiumHome, CONFIG_FILE_NAME);
+    this._appiumHome = appiumHome;
+  }
+
+  /**
+   * Creaes a `Proxy` which watches for changes to the extension-type-specific
+   * config data.
+   *
+   * When changes are detected, it sets a `_dirty` flag.  The next call to
+   * {@link ExtConfigIO.write} will check if this flag is `true` before
+   * proceeding.
+   * @param {ExtensionType} extensionType
+   * @param {Record<string,object>} data - Extension config data, keyed by name
+   * @private
+   * @returns {Record<string,object>}
+   */
+  _createProxy (extensionType, data) {
+    return new Proxy(data[`${extensionType}s`], {
+      set: (target, prop, value) => {
+        if (value !== target[prop]) {
+          this._dirty = true;
+        }
+        target[prop] = value;
+        return Reflect.set(target, prop, value);
+      },
+      deleteProperty: (target, prop) => {
+        if (prop in target) {
+          this._dirty = true;
+        }
+        return Reflect.deleteProperty(target, prop);
+      },
+    });
+  }
+
+  /**
+   * Returns the path to the config file.
+   */
+  get filepath () {
+    return this._filepath;
+  }
+
+  /**
+   * Gets data for an extension type.  Reads the config file if necessary.
+   *
+   * Force-reading is _not_ supported, as it's likely to be a source of
+   * bugs--it's easy to mutate the data and then overwrite memory with the file
+   * contents
+   *
+   * Ideally this will only ever read the file _once_.
+   * @param {ExtensionType} extensionType - Which bit of the config data we
+   * want
+   * @returns {Promise<object>} The data
+   */
+  async read (extensionType) {
+    if (this._reading) {
+      await this._reading;
+      return this._extDataByType.get(extensionType);
+    }
+
+    this._reading = (async () => {
+      if (!VALID_EXT_TYPES.has(extensionType)) {
+        throw new TypeError(
+          `Invalid extension type: ${extensionType}. Valid values are: ${[
+            ...VALID_EXT_TYPES,
+          ].join(', ')}`,
+        );
+      }
+      if (this._extDataByType.has(extensionType)) {
+        return;
+      }
+
+      let data;
+      let isNewFile = false;
+      try {
+        await mkdirp(this._appiumHome);
+        const yaml = await fs.readFile(this.filepath, 'utf8');
+        data = YAML.parse(yaml);
+      } catch (err) {
+        if (err.code === 'ENOENT') {
+          data = {
+            [CONFIG_DATA_DRIVER_KEY]: {},
+            [CONFIG_DATA_PLUGIN_KEY]: {},
+            schemaRev: CONFIG_SCHEMA_REV,
+          };
+          isNewFile = true;
+        } else {
+          throw new Error(
+            `Appium had trouble loading the extension installation ` +
+              `cache file (${this.filepath}). Ensure it exists and is ` +
+              `readable. Specific error: ${err.message}`,
+          );
+        }
+      }
+
+      this._data = data;
+      this._extDataByType.set(
+        DRIVER_TYPE,
+        this._createProxy(DRIVER_TYPE, data),
+      );
+      this._extDataByType.set(
+        PLUGIN_TYPE,
+        this._createProxy(PLUGIN_TYPE, data),
+      );
+
+      if (isNewFile) {
+        await this.write(true);
+      }
+    })();
+    try {
+      await this._reading;
+      return this._extDataByType.get(extensionType);
+    } finally {
+      this._reading = null;
+    }
+  }
+
+  /**
+   * Writes the data if it needs writing.
+   *
+   * If the `schemaRev` prop needs updating, the file will be written.
+   * @param {boolean} [force=false] - Whether to force a write even if the data is clean
+   * @returns {Promise<boolean>} Whether the data was written
+   */
+  async write (force = false) {
+    if (this._writing) {
+      return this._writing;
+    }
+    this._writing = (async () => {
+      try {
+        if (!this._dirty && !force) {
+          return false;
+        }
+
+        if (!this._data) {
+          throw new ReferenceError('No data to write. Call `read()` first');
+        }
+
+        const dataToWrite = {
+          ...this._data,
+          [CONFIG_DATA_DRIVER_KEY]: this._extDataByType.get(DRIVER_TYPE),
+          [CONFIG_DATA_PLUGIN_KEY]: this._extDataByType.get(PLUGIN_TYPE),
+        };
+
+        try {
+          await fs.writeFile(
+            this.filepath,
+            YAML.stringify(dataToWrite),
+            'utf8',
+          );
+          this._dirty = false;
+          return true;
+        } catch {
+          throw new Error(
+            `Appium could not parse or write from the Appium Home directory ` +
+              `(${this._appiumHome}). Please ensure it is writable.`,
+          );
+        }
+      } finally {
+        this._writing = null;
+      }
+    })();
+    return await this._writing;
+  }
+}
+
+/**
+ * Factory function for {@link ExtConfigIO}.
+ *
+ * Maintains one instance per value of `APPIUM_HOME`.
+ * @param {string} appiumHome - `APPIUM_HOME`
+ * @returns {ExtConfigIO}
+ */
+export const getExtConfigIOInstance = _.memoize(
+  (appiumHome) => new ExtConfigIO(appiumHome),
+);
+
+/**
+ * @typedef {ExtConfigIO} ExtensionConfigIO
+ */
+
+/**
+ * @typedef {typeof DRIVER_TYPE | typeof PLUGIN_TYPE} ExtensionType
+ */