appium 2.0.0-beta.3 → 2.0.0-beta.34

package/lib/cli/args.js

@@ -1,443 +1,240 @@
-import { DEFAULT_BASE_PATH } from 'appium-base-driver';
-import { parseSecurityFeatures, parseDefaultCaps, parsePluginNames, parseInstallTypes } from './parser-helpers';
-import { INSTALL_TYPES, DEFAULT_APPIUM_HOME, DRIVER_TYPE, PLUGIN_TYPE } from '../extension-config';
 
+// @ts-ignore
+import _ from 'lodash';
+import { DRIVER_TYPE, PLUGIN_TYPE, EXT_SUBCOMMAND_INSTALL, EXT_SUBCOMMAND_LIST, EXT_SUBCOMMAND_RUN, EXT_SUBCOMMAND_UNINSTALL, EXT_SUBCOMMAND_UPDATE } from '../constants';
+import { INSTALL_TYPES } from '../extension/extension-config';
+import { toParserArgs } from '../schema/cli-args';
 const DRIVER_EXAMPLE = 'xcuitest';
 const PLUGIN_EXAMPLE = 'find_by_image';
-const USE_ALL_PLUGINS = 'all';
 
-// sharedArgs will be added to every subcommand
-const sharedArgs = [
-  [['-ah', '--home', '--appium-home'], {
-    required: false,
-    defaultValue: process.env.APPIUM_HOME || DEFAULT_APPIUM_HOME,
-    help: 'The path to the directory where Appium will keep installed drivers, plugins, and any other metadata necessary for its operation',
-    dest: 'appiumHome',
-  }],
-
-  [['--log-filters'], {
-    dest: 'logFilters',
-    defaultValue: null,
-    required: false,
-    help: 'Set the full path to a JSON file containing one or more log filtering rules',
-    example: '/home/rules.json',
-  }],
-];
-
-const serverArgs = [
-  [['--shell'], {
-    required: false,
-    defaultValue: null,
-    help: 'Enter REPL mode',
-    nargs: 0,
-    dest: 'shell',
-  }],
-
-  [['--plugins'], {
-    required: false,
-    defaultValue: [],
-    help: `A comma-separated list of installed plugin names that should be active for this ` +
-          `server. To activate all plugins, you can use the single string "${USE_ALL_PLUGINS}" ` +
-          `as the value (e.g. --plugins=${USE_ALL_PLUGINS})`,
-    type: parsePluginNames,
-    dest: 'plugins',
-  }],
-
-  [['--allow-cors'], {
-    required: false,
-    defaultValue: false,
-    action: 'storeTrue',
-    help: 'Whether the Appium server should allow web browser connections from any host',
-    nargs: 0,
-    dest: 'allowCors',
-  }],
-
-  [['--reboot'], {
-    defaultValue: false,
-    dest: 'reboot',
-    action: 'storeTrue',
-    required: false,
-    help: '(Android-only) reboot emulator after each session and kill it at the end',
-    nargs: 0,
-  }],
-
-  [['-a', '--address'], {
-    defaultValue: '0.0.0.0',
-    required: false,
-    example: '0.0.0.0',
-    help: 'IP Address to listen on',
-    dest: 'address',
-  }],
-
-  [['-p', '--port'], {
-    defaultValue: 4723,
-    required: false,
-    type: 'int',
-    example: '4723',
-    help: 'port to listen on',
-    dest: 'port',
-  }],
-
-  [['-pa', '--base-path'], {
-    required: false,
-    defaultValue: DEFAULT_BASE_PATH,
-    dest: 'basePath',
-    example: '/path/prefix',
-    help: 'Base path to use as the prefix for all webdriver routes running' +
-          `on this server (default: ${DEFAULT_BASE_PATH})`
-  }],
-
-  [['-ca', '--callback-address'], {
-    required: false,
-    dest: 'callbackAddress',
-    defaultValue: null,
-    example: '127.0.0.1',
-    help: 'callback IP Address (default: same as --address)',
-  }],
-
-  [['-cp', '--callback-port'], {
-    required: false,
-    dest: 'callbackPort',
-    defaultValue: null,
-    type: 'int',
-    example: '4723',
-    help: 'callback port (default: same as port)',
-  }],
-
-  [['--session-override'], {
-    defaultValue: false,
-    dest: 'sessionOverride',
-    action: 'storeTrue',
-    required: false,
-    help: 'Enables session override (clobbering)',
-    nargs: 0,
-  }],
-
-  [['-g', '--log'], {
-    defaultValue: null,
-    dest: 'logFile',
-    required: false,
-    example: '/path/to/appium.log',
-    help: 'Also send log output to this file',
-  }],
-
-  [['--log-level'], {
-    choices: [
-      'info', 'info:debug', 'info:info', 'info:warn', 'info:error',
-      'warn', 'warn:debug', 'warn:info', 'warn:warn', 'warn:error',
-      'error', 'error:debug', 'error:info', 'error:warn', 'error:error',
-      'debug', 'debug:debug', 'debug:info', 'debug:warn', 'debug:error',
-    ],
-    defaultValue: 'debug',
-    dest: 'loglevel',
-    required: false,
-    example: 'debug',
-    help: 'log level; default (console[:file]): debug[:debug]',
-  }],
-
-  [['--log-timestamp'], {
-    defaultValue: false,
-    required: false,
-    help: 'Show timestamps in console output',
-    nargs: 0,
-    action: 'storeTrue',
-    dest: 'logTimestamp',
-  }],
-
-  [['--local-timezone'], {
-    defaultValue: false,
-    required: false,
-    help: 'Use local timezone for timestamps',
-    nargs: 0,
-    action: 'storeTrue',
-    dest: 'localTimezone',
-  }],
-
-  [['--log-no-colors'], {
-    defaultValue: false,
-    required: false,
-    help: 'Do not use colors in console output',
-    nargs: 0,
-    action: 'storeTrue',
-    dest: 'logNoColors',
-  }],
-
-  [['-G', '--webhook'], {
-    defaultValue: null,
-    required: false,
-    example: 'localhost:9876',
-    dest: 'webhook',
-    help: 'Also send log output to this HTTP listener',
-  }],
-
-  [['--nodeconfig'], {
-    required: false,
-    defaultValue: null,
-    dest: 'nodeconfig',
-    help: 'Configuration JSON file to register appium with selenium grid',
-    example: '/abs/path/to/nodeconfig.json',
-  }],
-
-  [['--chromedriver-port'], {
-    defaultValue: null,
-    dest: 'chromeDriverPort',
-    required: false,
-    type: 'int',
-    example: '9515',
-    help: 'Port upon which ChromeDriver will run. If not given, Android driver will pick a random available port.',
-  }],
-
-  [['--chromedriver-executable'], {
-    defaultValue: null,
-    dest: 'chromedriverExecutable',
-    required: false,
-    help: 'ChromeDriver executable full path',
-  }],
-
-  [['--show-config'], {
-    defaultValue: false,
-    dest: 'showConfig',
-    action: 'storeTrue',
-    required: false,
-    help: 'Show info about the appium server configuration and exit',
-  }],
-
-  [['--no-perms-check'], {
-    defaultValue: false,
-    dest: 'noPermsCheck',
-    action: 'storeTrue',
-    required: false,
-    help: 'Bypass Appium\'s checks to ensure we can read/write necessary files',
-  }],
+/**
+ * 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];
 
-  [['--strict-caps'], {
-    defaultValue: false,
-    dest: 'enforceStrictCaps',
-    action: 'storeTrue',
-    required: false,
-    help: 'Cause sessions to fail if desired caps are sent in that Appium ' +
-          'does not recognize as valid for the selected device',
-    nargs: 0,
-  }],
-
-  [['--tmp'], {
-    defaultValue: null,
-    dest: 'tmpDir',
-    required: false,
-    help: 'Absolute path to directory Appium can use to manage temporary ' +
-          'files, like built-in iOS apps it needs to move around. On *nix/Mac ' +
-          'defaults to /tmp, on Windows defaults to C:\\Windows\\Temp',
-  }],
-
-  [['--trace-dir'], {
-    defaultValue: null,
-    dest: 'traceDir',
-    required: false,
-    help: 'Absolute path to directory Appium use to save ios instruments ' +
-          'traces, defaults to <tmp dir>/appium-instruments',
-  }],
-
-  [['--debug-log-spacing'], {
-    dest: 'debugLogSpacing',
-    defaultValue: false,
-    action: 'storeTrue',
-    required: false,
-    help: 'Add exaggerated spacing in logs to help with visual inspection',
-  }],
-
-  [['--suppress-adb-kill-server'], {
-    dest: 'suppressKillServer',
-    defaultValue: false,
-    action: 'storeTrue',
-    required: false,
-    help: '(Android-only) If set, prevents Appium from killing the adb server instance',
-    nargs: 0,
-  }],
-
-  [['--long-stacktrace'], {
-    dest: 'longStacktrace',
-    defaultValue: false,
-    required: false,
-    action: 'storeTrue',
-    help: 'Add long stack traces to log entries. Recommended for debugging only.',
-  }],
-
-  [['--webkit-debug-proxy-port'], {
-    defaultValue: 27753,
-    dest: 'webkitDebugProxyPort',
-    required: false,
-    type: 'int',
-    example: '27753',
-    help: '(IOS-only) Local port used for communication with ios-webkit-debug-proxy'
-  }],
-
-  [['--webdriveragent-port'], {
-    defaultValue: 8100,
-    dest: 'wdaLocalPort',
-    required: false,
-    type: 'int',
-    example: '8100',
-    help: '(IOS-only, XCUITest-only) Local port used for communication with WebDriverAgent'
-  }],
-
-  [['-dc', '--default-capabilities'], {
-    dest: 'defaultCapabilities',
-    defaultValue: {},
-    type: parseDefaultCaps,
-    required: false,
-    example: '[ \'{"app": "myapp.app", "deviceName": "iPhone Simulator"}\' ' +
-             '| /path/to/caps.json ]',
-    help: 'Set the default desired capabilities, which will be set on each ' +
-          'session unless overridden by received capabilities.'
-  }],
-
-  [['--relaxed-security'], {
-    defaultValue: false,
-    dest: 'relaxedSecurityEnabled',
-    action: 'storeTrue',
-    required: false,
-    help: 'Disable additional security checks, so it is possible to use some advanced features, provided ' +
-          'by drivers supporting this option. Only enable it if all the ' +
-          'clients are in the trusted network and it\'s not the case if a client could potentially ' +
-          'break out of the session sandbox. Specific features can be overridden by ' +
-          'using the --deny-insecure flag',
-    nargs: 0
-  }],
-
-  [['--allow-insecure'], {
-    dest: 'allowInsecure',
-    defaultValue: [],
-    type: parseSecurityFeatures,
-    required: false,
-    example: 'execute_driver_script,adb_shell',
-    help: 'Set which insecure features are allowed to run in this server\'s sessions. ' +
-          'Features are defined on a driver level; see documentation for more details. ' +
-          'This should be either a comma-separated list of feature names, or a path to ' +
-          'a file where each feature name is on a line. Note that features defined via ' +
-          '--deny-insecure will be disabled, even if also listed here.',
-  }],
-
-  [['--deny-insecure'], {
-    dest: 'denyInsecure',
-    defaultValue: [],
-    type: parseSecurityFeatures,
-    required: false,
-    example: 'execute_driver_script,adb_shell',
-    help: 'Set which insecure features are not allowed to run in this server\'s sessions. ' +
-          'Features are defined on a driver level; see documentation for more details. ' +
-          'This should be either a comma-separated list of feature names, or a path to ' +
-          'a file where each feature name is on a line. Features listed here will not be ' +
-          'enabled even if also listed in --allow-insecure, and even if --relaxed-security ' +
-          'is turned on.',
-  }],
-];
+/** @type {Set<ExtensionType>} */
+const EXTENSION_TYPES = new Set([DRIVER_TYPE, PLUGIN_TYPE]);
 
 // this set of args works for both drivers and plugins ('extensions')
-const globalExtensionArgs = [
+/** @type {ArgumentDefinitions} */
+const globalExtensionArgs = new Map([
   [['--json'], {
     required: false,
-    defaultValue: false,
-    action: 'storeTrue',
+    default: false,
+    action: 'store_true',
     help: 'Use JSON for output format',
-    nargs: 0,
     dest: 'json'
   }]
-];
-
-const extensionArgs = {[DRIVER_TYPE]: {}, [PLUGIN_TYPE]: {}};
-
+]);
+
+/**
+ * Builds a Record of extension types to a Record of subcommands to their argument definitions
+ */
+const getExtensionArgs = _.memoize(function getExtensionArgs () {
+  const extensionArgs = {};
+  for (const type of EXTENSION_TYPES) {
+    extensionArgs[type] = {
+      [EXT_SUBCOMMAND_LIST]: makeListArgs(type),
+      [EXT_SUBCOMMAND_INSTALL]: makeInstallArgs(type),
+      [EXT_SUBCOMMAND_UNINSTALL]: makeUninstallArgs(type),
+      [EXT_SUBCOMMAND_UPDATE]: makeUpdateArgs(type),
+      [EXT_SUBCOMMAND_RUN]: makeRunArgs(type),
+    };
+  }
+  return /** @type {Record<ExtensionType, Record<import('../../types/cli').CliExtensionSubcommand,ArgumentDefinitions>>} */(extensionArgs);
+});
+
+/**
+ * Makes the opts for the `list` subcommand for each extension type.
+ * @param {ExtensionType} type
+ * @returns {ArgumentDefinitions}
+ */
 function makeListArgs (type) {
-  return [
+  return new Map([
     ...globalExtensionArgs,
     [['--installed'], {
       required: false,
-      defaultValue: false,
-      action: 'storeTrue',
+      default: false,
+      action: 'store_true',
       help: `List only installed ${type}s`,
-      nargs: 0,
       dest: 'showInstalled'
     }],
     [['--updates'], {
       required: false,
-      defaultValue: false,
-      action: 'storeTrue',
+      default: false,
+      action: 'store_true',
       help: 'Show information about newer versions',
-      nargs: 0,
       dest: 'showUpdates'
     }]
-  ];
+  ]);
 }
 
-
+/**
+ * Makes the opts for the `install` subcommand for each extension type
+ * @param {ExtensionType} type
+ * @returns {ArgumentDefinitions}
+ */
 function makeInstallArgs (type) {
-  return [
+  return new Map([
     ...globalExtensionArgs,
     [[type], {
-      type: 'string',
-      example: type === DRIVER_TYPE ? DRIVER_EXAMPLE : PLUGIN_EXAMPLE,
-      help: `Name of the ${type} to install`,
+      type: 'str',
+      help: `Name of the ${type} to install, for example: ` +
+            type === DRIVER_TYPE ? DRIVER_EXAMPLE : PLUGIN_EXAMPLE,
     }],
     [['--source'], {
       required: false,
-      defaultValue: null,
-      type: parseInstallTypes,
+      default: null,
+      choices: INSTALL_TYPES_ARRAY,
       help: `Where to look for the ${type} if it is not one of Appium's verified ` +
-            `${type}s. Possible values: ${JSON.stringify(INSTALL_TYPES)}`,
+            `${type}s. Possible values: ${INSTALL_TYPES_ARRAY.join(', ')}`,
       dest: 'installType'
     }],
     [['--package'], {
       required: false,
-      defaultValue: null,
-      type: 'string',
+      default: null,
+      type: 'str',
       help: `If installing from Git or GitHub, the package name, as defined in the plugin's ` +
             `package.json file in the "name" field, cannot be determined automatically, and ` +
             `should be reported here, otherwise the install will probably fail.`,
       dest: 'packageName',
     }],
-  ];
+  ]);
 }
 
+
+/**
+ * Makes the opts for the `uninstall` subcommand for each extension type
+ * @param {ExtensionType} type
+ * @returns {ArgumentDefinitions}
+ */
 function makeUninstallArgs (type) {
-  return [
+  return new Map([
     ...globalExtensionArgs,
     [[type], {
-      type: 'string',
-      example: type === DRIVER_TYPE ? DRIVER_EXAMPLE : PLUGIN_EXAMPLE,
-      help: 'Name of the driver to uninstall',
+      type: 'str',
+      help: 'Name of the driver to uninstall, for example: ' +
+            type === DRIVER_TYPE ? DRIVER_EXAMPLE : PLUGIN_EXAMPLE
     }],
-  ];
+  ]);
 }
 
+/**
+ * Makes the opts for the `update` subcommand for each extension type
+ * @param {ExtensionType} type
+ * @returns {ArgumentDefinitions}
+ */
 function makeUpdateArgs (type) {
-  return [
+  return new Map([
     ...globalExtensionArgs,
     [[type], {
-      type: 'string',
-      example: type === DRIVER_TYPE ? DRIVER_EXAMPLE : PLUGIN_EXAMPLE,
+      type: 'str',
       help: `Name of the ${type} to update, or the word "installed" to update all installed ` +
-            `${type}s. To see available updates, run "appium ${type} list --installed --updates"`,
+            `${type}s. To see available updates, run "appium ${type} list --installed --updates". ` +
+            'For example: ' + type === DRIVER_TYPE ? DRIVER_EXAMPLE : PLUGIN_EXAMPLE,
     }],
     [['--unsafe'], {
       required: false,
-      defaultValue: false,
-      action: 'storeTrue',
-      nargs: 0,
+      default: false,
+      action: 'store_true',
       help: `Include updates that might have a new major revision, and potentially include ` +
             `breaking changes`,
     }],
-  ];
+  ]);
+}
+
+/**
+ * Makes the opts for the `run` subcommand for each extension type
+ * @param {ExtensionType} type
+ * @returns {ArgumentDefinitions}
+ */
+function makeRunArgs (type) {
+  return new Map([
+    ...globalExtensionArgs,
+    [[type], {
+      type: 'str',
+      help: `Name of the ${type} to run a script from, for example: ` +
+            type === DRIVER_TYPE ? DRIVER_EXAMPLE : PLUGIN_EXAMPLE,
+    }],
+    [['scriptName'], {
+      default: null,
+      type: 'str',
+      help: `Name of the script to run from the ${type}. The script name must be cached ` +
+            `inside the "scripts" field under "appium" inside the ${type}'s "package.json" file`
+    }],
+  ]);
 }
 
-for (const type of [DRIVER_TYPE, PLUGIN_TYPE]) {
-  extensionArgs[type].list = makeListArgs(type);
-  extensionArgs[type].install = makeInstallArgs(type);
-  extensionArgs[type].uninstall = makeUninstallArgs(type);
-  extensionArgs[type].update = makeUpdateArgs(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([
+  [
+    ['--shell'],
+    {
+      required: false,
+      help: 'Enter REPL mode',
+      action: 'store_const',
+      const: true,
+      dest: 'shell',
+    },
+  ],
+  [
+    ['--show-build-info'],
+    {
+      dest: 'showBuildInfo',
+      action: 'store_const',
+      const: true,
+      required: false,
+      help: 'Show info about the Appium build and exit',
+    },
+  ],
+  [
+    ['--show-config'],
+    {
+      dest: 'showConfig',
+      action: 'store_const',
+      const: true,
+      required: false,
+      help: 'Show the current Appium configuration and exit',
+    }
+  ],
+  [
+    ['--config'],
+    {
+      dest: 'configFile',
+      type: 'string',
+      required: false,
+      help: 'Explicit path to Appium configuration file',
+    },
+  ],
+]);
+
 export {
-  sharedArgs,
-  serverArgs,
-  extensionArgs,
-  USE_ALL_PLUGINS,
+  getServerArgs,
+  getExtensionArgs
 };
+
+/**
+ * Alias
+ * @typedef {import('../extension/manifest').ExtensionType} ExtensionType
+ */
+
+/**
+ * A tuple of argument aliases and argument options
+ * @typedef {Map<string[],import('argparse').ArgumentOptions>} ArgumentDefinitions
+ */

package/lib/cli/driver-command.js

@@ -1,27 +1,36 @@
 import _ from 'lodash';
 import ExtensionCommand from './extension-command';
-import { DRIVER_TYPE } from '../extension-config';
-import { KNOWN_DRIVERS } from '../drivers';
+import { KNOWN_DRIVERS } from '../constants';
+import '@colors/colors';
 
 const REQ_DRIVER_FIELDS = ['driverName', 'automationName', 'platformNames', 'mainClass'];
-
+/**
+ * @extends {ExtensionCommand<import('../extension/manifest').DriverType>}
+ */
 export default class DriverCommand extends ExtensionCommand {
 
+  /**
+   * @param {DriverCommandOptions} opts
+   */
   constructor ({config, json}) {
-    super({config, json, type: DRIVER_TYPE});
+    super({config, json});
     this.knownExtensions = KNOWN_DRIVERS;
   }
 
   async install ({driver, installType, packageName}) {
-    return await super.install({ext: driver, installType, packageName});
+    return await super._install({ext: driver, installType, packageName});
   }
 
   async uninstall ({driver}) {
-    return await super.uninstall({ext: driver});
+    return await super._uninstall({ext: driver});
   }
 
   async update ({driver, unsafe}) {
-    return await super.update({ext: driver, unsafe});
+    return await super._update({ext: driver, unsafe});
+  }
+
+  async run ({driver, scriptName}) {
+    return await super._run({ext: driver, scriptName});
   }
 
   getPostInstallText ({extName, extData}) {
@@ -43,3 +52,9 @@ export default class DriverCommand extends ExtensionCommand {
   }
 
 }
+
+/**
+ * @typedef DriverCommandOptions
+ * @property {import('../extension/extension-config').ExtensionConfig<import('../extension/manifest').DriverType>} config
+ * @property {boolean} json
+ */