appium 2.0.0-beta.2 → 2.0.0-beta.20

package/lib/config-file.js

@@ -0,0 +1,227 @@
+// @ts-check
+
+import betterAjvErrors from '@sidvind/better-ajv-errors';
+import { lilconfig } from 'lilconfig';
+import _ from 'lodash';
+import yaml from 'yaml';
+import { getSchema, validate } from './schema/schema';
+
+/**
+ * lilconfig loader to handle `.yaml` files
+ * @type {import('lilconfig').LoaderSync}
+ */
+function yamlLoader (filepath, content) {
+  return yaml.parse(content);
+}
+
+/**
+ * A cache of the raw config file (a JSON string) at a filepath.
+ * This is used for better error reporting.
+ * Note that config files needn't be JSON, but it helps if they are.
+ * @type {Map<string,RawJson>}
+ */
+const rawConfig = new Map();
+
+/**
+ * Custom JSON loader that caches the raw config file (for use with `better-ajv-errors`).
+ * If it weren't for this cache, this would be unnecessary.
+ * @type {import('lilconfig').LoaderSync}
+ */
+function jsonLoader (filepath, content) {
+  rawConfig.set(filepath, content);
+  return JSON.parse(content);
+}
+
+/**
+ * Loads a config file from an explicit path
+ * @param {LilconfigAsyncSearcher} lc - lilconfig instance
+ * @param {string} filepath - Path to config file
+ * @returns {Promise<import('lilconfig').LilconfigResult>}
+ */
+async function loadConfigFile (lc, filepath) {
+  try {
+    // removing "await" will cause any rejection to _not_ be caught in this block!
+    return await lc.load(filepath);
+  } catch (/** @type {unknown} */err) {
+    if (/** @type {NodeJS.ErrnoException} */(err).code === 'ENOENT') {
+      /** @type {NodeJS.ErrnoException} */(err).message = `Config file not found at user-provided path: ${filepath}`;
+      throw err;
+    } else if (err instanceof SyntaxError) {
+      // generally invalid JSON
+      err.message = `Config file at user-provided path ${filepath} is invalid:\n${err.message}`;
+      throw err;
+    }
+    throw err;
+  }
+}
+
+/**
+ * Searches for a config file
+ * @param {LilconfigAsyncSearcher} lc - lilconfig instance
+ * @returns {Promise<import('lilconfig').LilconfigResult>}
+ */
+async function searchConfigFile (lc) {
+  return await lc.search();
+}
+
+/**
+ * Given an array of errors and the result of loading a config file, generate a
+ * helpful string for the user.
+ *
+ * - If `opts` contains a `json` property, this should be the original JSON
+ *   _string_ of the config file.  This is only applicable if the config file
+ *   was in JSON format. If present, it will associate line numbers with errors.
+ * - If `errors` happens to be empty, this will throw.
+ * @param {import('ajv').ErrorObject[]} errors - Non-empty array of errors. Required.
+ * @param {ReadConfigFileResult['config']|any} [config] -
+ * Configuration & metadata
+ * @param {FormatConfigErrorsOptions} [opts]
+ * @throws {TypeError} If `errors` is empty
+ * @returns {string}
+ */
+export function formatErrors (errors = [], config = {}, opts = {}) {
+  if (errors && !errors.length) {
+    throw new TypeError('Array of errors must be non-empty');
+  }
+  return betterAjvErrors(getSchema(opts.schemaId), config, errors, {
+    json: opts.json,
+    format: 'cli',
+  });
+}
+
+/**
+ * Given an optional path, read a config file. Validates the config file.
+ *
+ * Call {@link validate} if you already have a config object.
+ * @param {string} [filepath] - Path to config file, if we have one
+ * @param {ReadConfigFileOptions} [opts] - Options
+ * @public
+ * @returns {Promise<ReadConfigFileResult>} Contains config and filepath, if found, and any errors
+ */
+export async function readConfigFile (filepath, opts = {}) {
+  const lc = lilconfig('appium', {
+    loaders: {
+      '.yaml': yamlLoader,
+      '.yml': yamlLoader,
+      '.json': jsonLoader,
+      noExt: jsonLoader,
+    },
+    packageProp: 'appiumConfig'
+  });
+
+  const result = filepath
+    ? await loadConfigFile(lc, filepath)
+    : await searchConfigFile(lc);
+
+  if (result && !result.isEmpty && result.filepath) {
+    const {normalize = true, pretty = true} = opts;
+    try {
+      /** @type {ReadConfigFileResult} */
+      let configResult;
+      const errors = validate(result.config);
+      if (_.isEmpty(errors)) {
+        configResult = {...result, errors};
+      } else {
+        const reason = formatErrors(errors, result.config, {
+          json: rawConfig.get(result.filepath),
+          pretty,
+        });
+        configResult = reason
+          ? {...result, errors, reason}
+          : {...result, errors};
+      }
+
+      if (normalize) {
+        // normalize (to camel case) all top-level property names of the config file
+        configResult.config = normalizeConfig(
+          /** @type {AppiumConfig} */ (configResult.config),
+        );
+      }
+
+      return configResult;
+    } finally {
+      // clean up the raw config file cache, which is only kept to better report errors.
+      rawConfig.delete(result.filepath);
+    }
+  }
+  return result ?? {};
+}
+
+/**
+ * Convert schema property names to either a) the value of the `appiumCliDest` property, if any; or b) camel-case
+ * @param {AppiumConfig} config - Configuration object
+ * @returns {NormalizedAppiumConfig} New object with camel-cased keys (or `dest` keys).
+ */
+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
+   * @returns Normalized section of config
+   */
+  const normalize = (config, section) => {
+    const obj = _.isUndefined(section) ? config : _.get(config, section, config);
+
+    const mappedObj = _.mapKeys(obj, (__, prop) =>
+      schema.properties[prop]?.appiumCliDest ?? _.camelCase(prop),
+    );
+
+    return _.mapValues(mappedObj, (value, property) => {
+      const nextSection = section ? `${section}.${property}` : property;
+      return isSchemaTypeObject(value) ? normalize(config, nextSection) : value;
+    });
+  };
+
+  /**
+   * Returns `true` if the schema prop references an object, or if it's an object itself
+   * @param {import('ajv').SchemaObject|object} schema - Referencing schema object
+   */
+  const isSchemaTypeObject = (schema) => Boolean(schema.properties);
+
+  return normalize(config);
+}
+
+/**
+ * Result of calling {@link readConfigFile}.
+ * @typedef {Object} 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 {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
+ * @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.
+ */
+
+/**
+ * This is an `AsyncSearcher` which is inexplicably _not_ exported by the `lilconfig` type definition.
+ * @typedef {ReturnType<import('lilconfig')["lilconfig"]>} LilconfigAsyncSearcher
+ */
+
+/**
+ * The contents of an Appium config file. Generated from schema
+ * @typedef {import('../types/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
+ */
+
+/**
+ * The string should be a raw JSON string.
+ * @typedef {string} RawJson
+ */
+
+/**
+ * Options for {@link formatErrors}.
+ * @typedef {Object} 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,14 +1,18 @@
 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 {
+  StoreDeprecatedDefaultCapabilityAction, DEFAULT_CAPS_ARG,
+} from './cli/argparse-actions';
+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;
 
@@ -24,6 +28,11 @@ function getNodeVersion () {
   return semver.coerce(process.version);
 }
 
+function isSubClass (candidateClass, superClass) {
+  return _.isFunction(superClass) && _.isFunction(candidateClass)
+    && (candidateClass.prototype instanceof superClass || candidateClass === superClass);
+}
+
 async function updateBuildInfo (useGithubApiFallback = false) {
   const sha = await getGitRev(useGithubApiFallback);
   if (!sha) {
@@ -36,11 +45,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 +89,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 +157,89 @@ 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];
+  }
+
+  function defaultValueIsArray (dest) {
+    return _.isArray(defaultsFromSchema[dest]);
+  }
+
+  function argsValueIsArray (dest) {
+    return _.isArray(args[dest]);
+  }
+
+  function arraysDiffer (dest) {
+    return _.difference(args[dest], defaultsFromSchema[dest]).length > 0;
   }
-  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 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));
 }
 
-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 getDeprecatedArgs (parser, args) {
+  // go through the server command line arguments and figure
+  // out which of the ones used are deprecated
+  return parser.rawArgs.reduce((acc, [[name], {dest, default: defaultValue, action}]) => {
+    if (!args[dest] || args[dest] === defaultValue) {
+      return acc;
     }
-  }
 
-  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]}`);
-      }
+    if (action?.deprecated_for) {
+      acc[name] = action.deprecated_for;
+    } else if (isSubClass(action, StoreDeprecatedDefaultCapabilityAction)) {
+      acc[name] = DEFAULT_CAPS_ARG;
     }
-  }
+    return acc;
+  }, {});
 }
 
 async function validateTmpDir (tmpDir) {
@@ -206,7 +252,8 @@ 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,
+  getDeprecatedArgs
 };

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}'. ` +