appium 3.2.2 → 3.3.1

package/lib/bootstrap/startup-config.ts

@@ -0,0 +1,143 @@
+/* eslint-disable no-console */
+import _ from 'lodash';
+import {getDefaultsForSchema, getAllArgSpecs} from '../schema/schema';
+import type {Args} from 'appium/types';
+import type {ReadConfigFileResult} from './config-file';
+
+interface FlattenedArg {
+  value: unknown;
+  argSpec: {dest: string};
+}
+
+/**
+ * Returns key/value pairs of server arguments that differ from schema defaults (flattened comparison).
+ *
+ * @param parsedArgs - Fully merged server args (CLI + config + defaults)
+ */
+export function getNonDefaultServerArgs(parsedArgs: Args): Args {
+  /**
+   * Flattens parsed args into a single level object for comparison with
+   * flattened defaults across server args and extension args.
+   */
+  const flatten = (args: Args): Record<string, FlattenedArg> => {
+    const argSpecs = getAllArgSpecs();
+    const flattened = _.reduce(
+      [...argSpecs.values()],
+      (acc: Record<string, FlattenedArg>, argSpec: {dest: string}) => {
+        if (_.has(args, argSpec.dest)) {
+          acc[argSpec.dest] = {value: _.get(args, argSpec.dest), argSpec};
+        }
+        return acc;
+      },
+      {}
+    );
+
+    return flattened;
+  };
+
+  const args = flatten(parsedArgs);
+
+  // hopefully these function names are descriptive enough
+  const typesDiffer = (dest: string): boolean =>
+    typeof args[dest].value !== typeof defaultsFromSchema[dest];
+
+  const defaultValueIsArray = (dest: string): boolean => _.isArray(defaultsFromSchema[dest]);
+
+  const argsValueIsArray = (dest: string): boolean => _.isArray(args[dest].value);
+
+  const arraysDiffer = (dest: string): boolean =>
+    _.gt(_.size(_.difference(args[dest].value as any[], defaultsFromSchema[dest] as any[])), 0);
+
+  const valuesDiffer = (dest: string): boolean => args[dest].value !== defaultsFromSchema[dest];
+
+  const defaultIsDefined = (dest: string): boolean => !_.isUndefined(defaultsFromSchema[dest]);
+
+  // note that `_.overEvery` is like an "AND", and `_.overSome` is like an "OR"
+  const argValueNotArrayOrArraysDiffer = _.overSome([_.negate(argsValueIsArray), arraysDiffer]);
+
+  const defaultValueNotArrayAndValuesDiffer = _.overEvery([
+    _.negate(defaultValueIsArray),
+    valuesDiffer,
+  ]);
+
+  /**
+   * 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
+   */
+  const isNotDefault = _.overEvery([
+    defaultIsDefined,
+    _.overSome([
+      typesDiffer,
+      _.overEvery([defaultValueIsArray, argValueNotArrayOrArraysDiffer]),
+      defaultValueNotArrayAndValuesDiffer,
+    ]),
+  ]);
+
+  const defaultsFromSchema = getDefaultsForSchema(true) as Record<string, unknown>;
+
+  return _.reduce(
+    _.pickBy(args, (_v, key) => isNotDefault(key)),
+    // explodes the flattened object back into nested one
+    (acc: Args, {value, argSpec}: FlattenedArg) => _.set(acc, argSpec.dest, value),
+    {} as Args
+  );
+}
+
+/**
+ * Prints a breakdown of configuration: defaults, config file, CLI/programmatic overrides, and final merged args.
+ *
+ * The actual shape of `nonDefaultPreConfigParsedArgs` 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 nonDefaultPreConfigParsedArgs - CLI-only (or programmatic) args that differ from defaults
+ * @param configResult - Result of {@link readConfigFile}
+ * @param defaults - Schema default values
+ * @param parsedArgs - Final merged configuration
+ */
+export function showConfig(
+  nonDefaultPreConfigParsedArgs: Partial<Args>,
+  configResult: ReadConfigFileResult,
+  defaults: Partial<Args>,
+  parsedArgs: Args
+): void {
+  console.log('Appium Configuration\n');
+  console.log('from defaults:\n');
+  console.dir(compactConfig(defaults));
+  if (configResult.config) {
+    console.log(`\nfrom config file at ${configResult.filepath}:\n`);
+    console.dir(compactConfig(configResult.config));
+  } else {
+    console.log(`\n(no configuration file loaded)`);
+  }
+  const compactedNonDefaultPreConfigArgs = compactConfig(nonDefaultPreConfigParsedArgs);
+  if (_.isEmpty(compactedNonDefaultPreConfigArgs)) {
+    console.log(`\n(no CLI parameters provided)`);
+  } else {
+    console.log('\nvia CLI or function call:\n');
+    console.dir(compactedNonDefaultPreConfigArgs);
+  }
+  console.log('\nfinal configuration:\n');
+  console.dir(compactConfig(parsedArgs));
+}
+
+/**
+ * Compacts an object for {@link showConfig}:
+ * 1. Removes `subcommand` key/value
+ * 2. Removes `undefined` values
+ * 3. Removes empty objects (but not `false` values)
+ * Does not operate recursively.
+ */
+const compactConfig = _.partial(
+  _.omitBy,
+  _,
+  (value: unknown, key: string) =>
+    key === 'subcommand' || _.isUndefined(value) || (_.isObject(value) && _.isEmpty(value))
+);

package/lib/cli/{args.js → args.ts}

@@ -1,4 +1,7 @@
 import _ from 'lodash';
+import type {ArgumentOptions} from 'argparse';
+import type {ExtensionType} from '@appium/types';
+import type {CliExtensionSubcommand} from 'appium/types';
 import {
   DRIVER_TYPE,
   PLUGIN_TYPE,
@@ -14,18 +17,21 @@ import {toParserArgs} from '../schema/cli-args';
 const DRIVER_EXAMPLE = 'xcuitest';
 const PLUGIN_EXAMPLE = 'images';
 
+export type ArgumentDefinitions = Map<
+  [name: string] | [name: string, alias: string],
+  ArgumentOptions
+>;
+
 /**
  * This is necessary because we pass the array into `argparse`. `argparse` is bad and mutates things. We don't want that.
  * Bad `argparse`! Bad!
  */
 const INSTALL_TYPES_ARRAY = [...INSTALL_TYPES];
 
-/** @type {Set<ExtensionType>} */
-const EXTENSION_TYPES = new Set([DRIVER_TYPE, PLUGIN_TYPE]);
+const EXTENSION_TYPES = new Set<ExtensionType>([DRIVER_TYPE, PLUGIN_TYPE]);
 
 // this set of args works for both drivers and plugins ('extensions')
-/** @type {ArgumentDefinitions} */
-const globalExtensionArgs = new Map([
+const globalExtensionArgs: ArgumentDefinitions = new Map([
   [
     ['--json'],
     {
@@ -39,10 +45,18 @@ const globalExtensionArgs = new Map([
 ]);
 
 /**
- * Builds a Record of extension types to a Record of subcommands to their argument definitions
+ * Returns CLI argument definitions for extension commands by extension type.
+ *
+ * The result is memoized because parser setup is static across process lifetime.
  */
-const getExtensionArgs = _.memoize(function getExtensionArgs() {
-  const extensionArgs = {};
+export const getExtensionArgs = _.memoize(function getExtensionArgs(): Record<
+  ExtensionType,
+  Record<CliExtensionSubcommand, ArgumentDefinitions>
+> {
+  const extensionArgs = {} as Record<
+    ExtensionType,
+    Record<CliExtensionSubcommand, ArgumentDefinitions>
+  >;
   for (const type of EXTENSION_TYPES) {
     extensionArgs[type] = {
       [EXT_SUBCOMMAND_LIST]: makeListArgs(type),
@@ -53,17 +67,23 @@ const getExtensionArgs = _.memoize(function getExtensionArgs() {
       [EXT_SUBCOMMAND_DOCTOR]: makeDoctorArgs(type),
     };
   }
-  return /** @type {Record<ExtensionType, Record<import('appium/types').CliExtensionSubcommand,ArgumentDefinitions>>} */ (
-    extensionArgs
-  );
+  return extensionArgs;
 });
 
 /**
- * Makes the opts for the `list` subcommand for each extension type.
- * @param {ExtensionType} type
- * @returns {ArgumentDefinitions}
+ * Returns CLI argument definitions for the `server` command.
+ *
+ * This includes schema-derived options and additional CLI-only options which
+ * are intentionally disallowed in config files.
  */
-function makeListArgs(type) {
+export function getServerArgs(): ArgumentDefinitions {
+  return new Map([...toParserArgs(), ...serverArgsDisallowedInConfig]);
+}
+
+/**
+ * Builds options for the `list` subcommand for an extension type.
+ */
+function makeListArgs(type: ExtensionType): ArgumentDefinitions {
   return new Map([
     ...globalExtensionArgs,
     [
@@ -100,11 +120,9 @@ function makeListArgs(type) {
 }
 
 /**
- * Makes the opts for the `install` subcommand for each extension type
- * @param {ExtensionType} type
- * @returns {ArgumentDefinitions}
+ * Builds options for the `install` subcommand for an extension type.
  */
-function makeInstallArgs(type) {
+function makeInstallArgs(type: ExtensionType): ArgumentDefinitions {
   return new Map([
     ...globalExtensionArgs,
     [
@@ -144,11 +162,9 @@ function makeInstallArgs(type) {
 }
 
 /**
- * Makes the opts for the `uninstall` subcommand for each extension type
- * @param {ExtensionType} type
- * @returns {ArgumentDefinitions}
+ * Builds options for the `uninstall` subcommand for an extension type.
  */
-function makeUninstallArgs(type) {
+function makeUninstallArgs(type: ExtensionType): ArgumentDefinitions {
   return new Map([
     ...globalExtensionArgs,
     [
@@ -164,11 +180,9 @@ function makeUninstallArgs(type) {
 }
 
 /**
- * Makes the opts for the `doctor` subcommand for each extension type
- * @param {ExtensionType} type
- * @returns {ArgumentDefinitions}
+ * Builds options for the `doctor` subcommand for an extension type.
  */
-function makeDoctorArgs(type) {
+function makeDoctorArgs(type: ExtensionType): ArgumentDefinitions {
   return new Map([
     ...globalExtensionArgs,
     [
@@ -184,11 +198,9 @@ function makeDoctorArgs(type) {
 }
 
 /**
- * Makes the opts for the `update` subcommand for each extension type
- * @param {ExtensionType} type
- * @returns {ArgumentDefinitions}
+ * Builds options for the `update` subcommand for an extension type.
  */
-function makeUpdateArgs(type) {
+function makeUpdateArgs(type: ExtensionType): ArgumentDefinitions {
   return new Map([
     ...globalExtensionArgs,
     [
@@ -216,11 +228,9 @@ function makeUpdateArgs(type) {
 }
 
 /**
- * Makes the opts for the `run` subcommand for each extension type
- * @param {ExtensionType} type
- * @returns {ArgumentDefinitions}
+ * Builds options for the `run` subcommand for an extension type.
  */
-function makeRunArgs(type) {
+function makeRunArgs(type: ExtensionType): ArgumentDefinitions {
   return new Map([
     ...globalExtensionArgs,
     [
@@ -246,20 +256,10 @@ function makeRunArgs(type) {
   ]);
 }
 
-/**
- * Derives the options for the `server` command from the schema, and adds the arguments
- * which are disallowed in the config file.
- * @returns {ArgumentDefinitions}
- */
-function getServerArgs() {
-  return new Map([...toParserArgs(), ...serverArgsDisallowedInConfig]);
-}
-
 /**
  * These don't make sense in the context of a config file for obvious reasons.
- * @type {ArgumentDefinitions}
  */
-const serverArgsDisallowedInConfig = new Map([
+const serverArgsDisallowedInConfig: ArgumentDefinitions = new Map([
   [
     ['--shell'],
     {
@@ -310,14 +310,3 @@ const serverArgsDisallowedInConfig = new Map([
     },
   ],
 ]);
-
-export {getServerArgs, getExtensionArgs};
-
-/**
- * @typedef {import('@appium/types').ExtensionType} ExtensionType
- */
-
-/**
- * A tuple of argument aliases and argument options
- * @typedef {Map<[name: string]|[name: string, alias: string],import('argparse').ArgumentOptions>} ArgumentDefinitions
- */

package/lib/cli/driver-command.ts

@@ -0,0 +1,122 @@
+import _ from 'lodash';
+import type {ExtMetadata, ExtRecord, InstallType} from 'appium/types';
+import ExtensionCliCommand from './extension-command';
+import type {
+  ExtensionArgs,
+  ExtensionCommandOptions,
+  ExtensionUpdateResult,
+  PostInstallText,
+  RunOutput,
+} from './extension-command';
+import {KNOWN_DRIVERS} from '../constants';
+import '@colors/colors';
+
+const REQ_DRIVER_FIELDS = ['driverName', 'automationName', 'platformNames', 'mainClass'];
+type DriverInstallOpts = {driver: string; installType: InstallType; packageName?: string};
+type DriverUninstallOpts = {driver: string};
+type DriverUpdateOpts = {driver: string; unsafe: boolean};
+type DriverRunOptions = {driver: string; scriptName: string; extraArgs?: string[]};
+type DriverDoctorOptions = {driver: string};
+
+export default class DriverCliCommand extends ExtensionCliCommand<'driver'> {
+  constructor({config, json}: ExtensionCommandOptions<'driver'>) {
+    super({config, json});
+    this.knownExtensions = KNOWN_DRIVERS;
+  }
+
+  /**
+   * Install a driver
+   *
+   * @param opts - install options
+   */
+  async install({driver, installType, packageName}: DriverInstallOpts): Promise<ExtRecord<'driver'>> {
+    return await super._install({
+      installSpec: driver,
+      installType,
+      packageName,
+    });
+  }
+
+  /**
+   * Uninstall a driver
+   *
+   * @param opts - uninstall options
+   */
+  async uninstall({driver}: DriverUninstallOpts): Promise<ExtRecord<'driver'>> {
+    return await super._uninstall({installSpec: driver});
+  }
+
+  /**
+   * Update a driver
+   *
+   * @param opts - update options
+   */
+  async update({driver, unsafe}: DriverUpdateOpts): Promise<ExtensionUpdateResult> {
+    return await super._update({installSpec: driver, unsafe});
+  }
+
+  /**
+   * Run a script from a driver
+   *
+   * @param opts - script execution options
+   * @throws {Error} if the script fails to run
+   */
+  async run({driver, scriptName, extraArgs}: DriverRunOptions): Promise<RunOutput> {
+    return await super._run({
+      installSpec: driver,
+      scriptName,
+      extraArgs,
+      bufferOutput: this.isJsonOutput,
+    });
+  }
+
+  /**
+   * Runs doctor checks for the given driver.
+   *
+   * @param opts - doctor command options
+   * @returns The amount of executed doctor checks.
+   * @throws {Error} If any of the mandatory Doctor checks fails.
+   */
+  async doctor({driver}: DriverDoctorOptions): Promise<number> {
+    return await super._doctor({
+      installSpec: driver,
+    });
+  }
+
+  /**
+   * Builds the success message displayed after a driver installation.
+   *
+   * @param args - installed extension name and metadata
+   * @returns formatted success text
+   */
+  override getPostInstallText({extName, extData}: ExtensionArgs<'driver'>): PostInstallText {
+    return (
+      `Driver ${extName}@${extData.version} successfully installed\n`.green +
+      `- automationName: ${extData.automationName.green}\n` +
+      `- platformNames: ${JSON.stringify(extData.platformNames).green}`
+    );
+  }
+
+  /**
+   * Validates fields in `appium` field of `driverMetadata`
+   *
+   * For any `package.json` fields which a driver requires, validate the type of
+   * those fields on the `package.json` data, throwing an error if anything is
+   * amiss.
+   * @param driverMetadata - `appium` metadata from extension package
+   * @param installSpec - install spec from CLI
+   */
+  override validateExtensionFields(driverMetadata: ExtMetadata<'driver'>, installSpec: string): void {
+    const missingFields = REQ_DRIVER_FIELDS.reduce(
+      (acc, field) => (driverMetadata[field] ? acc : [...acc, field]),
+      []
+    );
+
+    if (!_.isEmpty(missingFields)) {
+      throw new Error(
+        `Driver "${installSpec}" did not expose correct fields for compatibility ` +
+          `with Appium. Missing fields: ${JSON.stringify(missingFields)}`
+      );
+    }
+  }
+}