appium 2.0.0-beta.4 → 2.0.0-beta.42

package/lib/cli/args.js

@@ -1,443 +1,288 @@
-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';
-
+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',
-  }],
-
-  [['--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
-  }],
+/**
+ * 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];
 
-  [['--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 = [
-  [['--json'], {
-    required: false,
-    defaultValue: false,
-    action: 'storeTrue',
-    help: 'Use JSON for output format',
-    nargs: 0,
-    dest: 'json'
-  }]
-];
-
-const extensionArgs = {[DRIVER_TYPE]: {}, [PLUGIN_TYPE]: {}};
-
-function makeListArgs (type) {
-  return [
-    ...globalExtensionArgs,
-    [['--installed'], {
-      required: false,
-      defaultValue: false,
-      action: 'storeTrue',
-      help: `List only installed ${type}s`,
-      nargs: 0,
-      dest: 'showInstalled'
-    }],
-    [['--updates'], {
+/** @type {ArgumentDefinitions} */
+const globalExtensionArgs = new Map([
+  [
+    ['--json'],
+    {
       required: false,
-      defaultValue: false,
-      action: 'storeTrue',
-      help: 'Show information about newer versions',
-      nargs: 0,
-      dest: 'showUpdates'
-    }]
-  ];
+      default: false,
+      action: 'store_true',
+      help: 'Use JSON for output format',
+      dest: 'json',
+    },
+  ],
+]);
+
+/**
+ * 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('appium/types').CliExtensionSubcommand,ArgumentDefinitions>>} */ (
+    extensionArgs
+  );
+});
+
+/**
+ * Makes the opts for the `list` subcommand for each extension type.
+ * @param {ExtensionType} type
+ * @returns {ArgumentDefinitions}
+ */
+function makeListArgs(type) {
+  return new Map([
+    ...globalExtensionArgs,
+    [
+      ['--installed'],
+      {
+        required: false,
+        default: false,
+        action: 'store_true',
+        help: `List only installed ${type}s`,
+        dest: 'showInstalled',
+      },
+    ],
+    [
+      ['--updates'],
+      {
+        required: false,
+        default: false,
+        action: 'store_true',
+        help: 'Show information about newer versions',
+        dest: 'showUpdates',
+      },
+    ],
+  ]);
 }
 
+/**
+ * Makes the opts for the `install` subcommand for each extension type
+ * @param {ExtensionType} type
+ * @returns {ArgumentDefinitions}
+ */
+function makeInstallArgs(type) {
+  return new Map([
+    ...globalExtensionArgs,
+    [
+      [type],
+      {
+        type: 'str',
+        help:
+          `Name of the ${type} to install, for example: ` + type === DRIVER_TYPE
+            ? DRIVER_EXAMPLE
+            : PLUGIN_EXAMPLE,
+      },
+    ],
+    [
+      ['--source'],
+      {
+        required: false,
+        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: ${INSTALL_TYPES_ARRAY.join(', ')}`,
+        dest: 'installType',
+      },
+    ],
+    [
+      ['--package'],
+      {
+        required: false,
+        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',
+      },
+    ],
+  ]);
+}
 
-function makeInstallArgs (type) {
-  return [
+/**
+ * Makes the opts for the `uninstall` subcommand for each extension type
+ * @param {ExtensionType} type
+ * @returns {ArgumentDefinitions}
+ */
+function makeUninstallArgs(type) {
+  return new Map([
     ...globalExtensionArgs,
-    [[type], {
-      type: 'string',
-      example: type === DRIVER_TYPE ? DRIVER_EXAMPLE : PLUGIN_EXAMPLE,
-      help: `Name of the ${type} to install`,
-    }],
-    [['--source'], {
-      required: false,
-      defaultValue: null,
-      type: parseInstallTypes,
-      help: `Where to look for the ${type} if it is not one of Appium's verified ` +
-            `${type}s. Possible values: ${JSON.stringify(INSTALL_TYPES)}`,
-      dest: 'installType'
-    }],
-    [['--package'], {
-      required: false,
-      defaultValue: null,
-      type: 'string',
-      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',
-    }],
-  ];
+    [
+      [type],
+      {
+        type: 'str',
+        help:
+          'Name of the driver to uninstall, for example: ' + type === DRIVER_TYPE
+            ? DRIVER_EXAMPLE
+            : PLUGIN_EXAMPLE,
+      },
+    ],
+  ]);
 }
 
-function makeUninstallArgs (type) {
-  return [
+/**
+ * Makes the opts for the `update` subcommand for each extension type
+ * @param {ExtensionType} type
+ * @returns {ArgumentDefinitions}
+ */
+function makeUpdateArgs(type) {
+  return new Map([
     ...globalExtensionArgs,
-    [[type], {
-      type: 'string',
-      example: type === DRIVER_TYPE ? DRIVER_EXAMPLE : PLUGIN_EXAMPLE,
-      help: 'Name of the driver to uninstall',
-    }],
-  ];
+    [
+      [type],
+      {
+        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". ` +
+            'For example: ' +
+            type ===
+          DRIVER_TYPE
+            ? DRIVER_EXAMPLE
+            : PLUGIN_EXAMPLE,
+      },
+    ],
+    [
+      ['--unsafe'],
+      {
+        required: false,
+        default: false,
+        action: 'store_true',
+        help:
+          `Include updates that might have a new major revision, and potentially include ` +
+          `breaking changes`,
+      },
+    ],
+  ]);
 }
 
-function makeUpdateArgs (type) {
-  return [
+/**
+ * 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: 'string',
-      example: type === DRIVER_TYPE ? DRIVER_EXAMPLE : PLUGIN_EXAMPLE,
-      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"`,
-    }],
-    [['--unsafe'], {
-      required: false,
-      defaultValue: false,
-      action: 'storeTrue',
-      nargs: 0,
-      help: `Include updates that might have a new major revision, and potentially include ` +
-            `breaking changes`,
-    }],
-  ];
+    [
+      [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 a key ` +
+          `inside the "appium.scripts" field 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]);
 }
 
-export {
-  sharedArgs,
-  serverArgs,
-  extensionArgs,
-  USE_ALL_PLUGINS,
-};
+/**
+ * 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 {getServerArgs, getExtensionArgs};
+
+/**
+ * @typedef {import('@appium/types').ExtensionType} ExtensionType
+ */
+
+/**
+ * A tuple of argument aliases and argument options
+ * @typedef {Map<string[],import('argparse').ArgumentOptions>} ArgumentDefinitions
+ */