appium 2.0.0-beta.25 → 2.0.0-beta.26

package/lib/config-file.js

@@ -181,7 +181,7 @@ 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
@@ -191,7 +191,7 @@ export function normalizeConfig (config) {
 
 /**
  * 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.
  */
 
@@ -217,7 +217,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

@@ -2,10 +2,9 @@
 
 /* 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';
@@ -289,17 +288,19 @@ 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
 };
 
 /**

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
+ */
+