appium 2.0.0-beta.2 → 2.0.0-beta.23

package/lib/schema/appium-config-schema.js

@@ -0,0 +1,287 @@
+// @ts-check
+
+const schema = /** @type {const} */ ({
+  $schema: 'http://json-schema.org/draft-07/schema',
+  additionalProperties: false,
+  description: 'A schema for Appium configuration files',
+  properties: {
+    server: {
+      additionalProperties: false,
+      description: 'Configuration when running Appium as a server',
+      properties: {
+        address: {
+          $comment:
+            'I think hostname covers both DNS and IPv4...could be wrong',
+          appiumCliAliases: ['a'],
+          default: '0.0.0.0',
+          description: 'IP address to listen on',
+          format: 'hostname',
+          title: 'address config',
+          type: 'string',
+        },
+        'allow-cors': {
+          description:
+            'Whether the Appium server should allow web browser connections from any host',
+          title: 'allow-cors config',
+          type: 'boolean',
+          default: false,
+        },
+        'allow-insecure': {
+          appiumCliTransformer: 'csv',
+          default: [],
+          description:
+            '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. Note that features defined via "deny-insecure" will be disabled, even if also listed here. If string, a path to a text file containing policy or a comma-delimited list.',
+          items: {
+            type: 'string',
+          },
+          title: 'allow-insecure config',
+          type: 'array',
+          uniqueItems: true,
+        },
+        'base-path': {
+          appiumCliAliases: ['pa'],
+          default: '',
+          description:
+            'Base path to use as the prefix for all webdriver routes running on the server',
+          title: 'base-path config',
+          type: 'string',
+        },
+        'callback-address': {
+          appiumCliAliases: ['ca'],
+          description: 'Callback IP address (default: same as "address")',
+          title: 'callback-address config',
+          type: 'string',
+        },
+        'callback-port': {
+          appiumCliAliases: ['cp'],
+          default: 4723,
+          description: 'Callback port (default: same as "port")',
+          maximum: 65535,
+          minimum: 1,
+          title: 'callback-port config',
+          type: 'integer',
+        },
+        'debug-log-spacing': {
+          default: false,
+          description:
+            'Add exaggerated spacing in logs to help with visual inspection',
+          title: 'debug-log-spacing config',
+          type: 'boolean',
+        },
+        'default-capabilities': {
+          $comment: 'TODO',
+          appiumCliAliases: ['dc'],
+          description:
+            'Set the default desired capabilities, which will be set on each session unless overridden by received capabilities. If a string, a path to a JSON file containing the capabilities, or raw JSON.',
+          title: 'default-capabilities config',
+          type: 'object',
+        },
+        'deny-insecure': {
+          $comment: 'Allowed values are defined by drivers',
+          appiumCliTransformer: 'csv',
+          default: [],
+          description:
+            '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. Features listed here will not be enabled even if also listed in "allow-insecure", and even if "relaxed-security" is enabled. If string, a path to a text file containing policy or a comma-delimited list.',
+          items: {
+            type: 'string',
+          },
+          title: 'deny-insecure config',
+          type: 'array',
+          uniqueItems: true,
+        },
+        driver: {
+          description:
+            'Driver-specific configuration. Keys should correspond to driver package names',
+          properties: {},
+          title: 'driver config',
+          type: 'object',
+        },
+        'keep-alive-timeout': {
+          appiumCliAliases: ['ka'],
+          default: 600,
+          description:
+            'Number of seconds the Appium server should apply as both the keep-alive timeout and the connection timeout for all requests. A value of 0 disables the timeout.',
+          minimum: 0,
+          title: 'keep-alive-timeout config',
+          type: 'integer',
+        },
+        'local-timezone': {
+          default: false,
+          description: 'Use local timezone for timestamps',
+          title: 'local-timezone config',
+          type: 'boolean',
+        },
+        log: {
+          appiumCliAliases: ['g'],
+          appiumCliDest: 'logFile',
+          description: 'Also send log output to this file',
+          title: 'log config',
+          type: 'string',
+        },
+        'log-filters': {
+          $comment: 'TODO',
+          description: 'One or more log filtering rules',
+          items: {
+            type: 'string',
+          },
+          title: 'log-filters config',
+          type: 'array',
+        },
+        'log-level': {
+          appiumCliDest: 'loglevel',
+          default: 'debug',
+          description: 'Log level (console[:file])',
+          enum: [
+            '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',
+          ],
+          title: 'log-level config',
+          type: 'string',
+        },
+        'log-no-colors': {
+          default: false,
+          description: 'Do not use color in console output',
+          title: 'log-no-colors config',
+          type: 'boolean',
+        },
+        'log-timestamp': {
+          default: false,
+          description: 'Show timestamps in console output',
+          title: 'log-timestamp config',
+          type: 'boolean',
+        },
+        'long-stacktrace': {
+          default: false,
+          description:
+            'Add long stack traces to log entries. Recommended for debugging only.',
+          title: 'long-stacktrace config',
+          type: 'boolean',
+        },
+        'no-perms-check': {
+          default: false,
+          description:
+            'Do not check that needed files are readable and/or writable',
+          title: 'no-perms-check config',
+          type: 'boolean',
+        },
+        nodeconfig: {
+          $comment:
+            'Selenium Grid 3 is unmaintained and Selenium Grid 4 no longer supports this file.',
+          description:
+            'Path to configuration JSON file to register Appium as a node with Selenium Grid 3; otherwise the configuration itself',
+          title: 'nodeconfig config',
+          type: 'object',
+        },
+        plugin: {
+          description:
+            'Plugin-specific configuration. Keys should correspond to plugin package names',
+          properties: {},
+          title: 'plugin config',
+          type: 'object',
+        },
+        port: {
+          appiumCliAliases: ['p'],
+          default: 4723,
+          description: 'Port to listen on',
+          maximum: 65535,
+          minimum: 1,
+          title: 'port config',
+          type: 'integer',
+        },
+        'relaxed-security': {
+          default: false,
+          description:
+            '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 "deny-insecure"',
+          title: 'relaxed-security config',
+          type: 'boolean',
+          appiumCliDest: 'relaxedSecurityEnabled'
+        },
+        'session-override': {
+          default: false,
+          description: 'Enables session override (clobbering)',
+          title: 'session-override config',
+          type: 'boolean',
+        },
+        'strict-caps': {
+          default: false,
+          description:
+            'Cause sessions to fail if desired caps are sent in that Appium does not recognize as valid for the selected device',
+          title: 'strict-caps config',
+          type: 'boolean',
+        },
+        tmp: {
+          appiumCliDest: 'tmpDir',
+          description:
+            'Absolute path to directory Appium can use to manage temp files. Defaults to C:\\Windows\\Temp on Windows and /tmp otherwise.',
+          title: 'tmp config',
+          type: 'string',
+        },
+        'trace-dir': {
+          description:
+            'Absolute path to directory Appium can use to save iOS instrument traces; defaults to <tmp>/appium-instruments',
+          title: 'trace-dir config',
+          type: 'string',
+        },
+        'use-drivers': {
+          appiumCliDescription:
+            'A list of drivers to activate. Can be a comma-delimited string or path to CSV file. By default, all installed drivers will be activated.',
+          default: [],
+          description:
+            'A list of drivers to activate. By default, all installed drivers will be activated.',
+          items: {
+            type: 'string',
+          },
+          title: 'use-drivers config',
+          type: 'array',
+          uniqueItems: true,
+        },
+        'use-plugins': {
+          appiumCliDescription:
+            'A list of plugins to activate. Can be a comma-delimited string, path to CSV file, or the string "all" to use all installed plugins.',
+          default: [],
+          description:
+            'A list of plugins to activate. To activate all plugins, the value should be an array with a single item "all".',
+          items: {
+            type: 'string',
+          },
+          title: 'use-plugins config',
+          type: 'array',
+          uniqueItems: true,
+        },
+        webhook: {
+          $comment:
+            'This should probably use a uri-template format to restrict the protocol to http/https',
+          appiumCliAliases: ['G'],
+          description: 'Also send log output to this http listener',
+          format: 'uri',
+          title: 'webhook config',
+          type: 'string',
+        },
+      },
+      title: 'server config',
+      type: 'object',
+    },
+  },
+  title: 'Appium Configuration',
+  type: 'object',
+});
+
+export default schema;

package/lib/schema/arg-spec.js

@@ -0,0 +1,222 @@
+import _ from 'lodash';
+
+/**
+ * The original ID of the Appium config schema.
+ * We use this in the CLI to convert it to `argparse` options.
+ */
+export const APPIUM_CONFIG_SCHEMA_ID = 'appium.json';
+
+/**
+ * The schema prop containing server-related options. Everything in here
+ * is "native" to Appium.
+ * Used by {@link flattenSchema} for transforming the schema into CLI args.
+ */
+export const SERVER_PROP_NAME = 'server';
+
+/**
+ * Used to parse extension info from a schema ID.
+ */
+const SCHEMA_ID_REGEXP = /^(?<extType>.+?)-(?<normalizedExtName>.+)\.json$/;
+
+/**
+ * Avoid typos by using constants!
+ */
+const PROPERTIES = 'properties';
+
+/**
+ * An `ArgSpec` is a class representing metadata about an argument (or config
+ * option) used for cross-referencing.
+ *
+ * This class has no instance methods, and is basically just a read-only "struct".
+ */
+export class ArgSpec {
+  /**
+   * The canonical name of the argument. Corresponds to key in schema's `properties` prop.
+   * @type {string}
+   */
+  name;
+
+  /**
+   * The `ExtensionType` of the argument. This will be set if the arg came from an extension;
+   * otherwise it will be `undefined`.
+   * @type {ExtensionType|undefined}
+   */
+  extType;
+
+  /**
+   * The name of the extension, if this argument came from an extension.
+   *
+   * Otherwise `undefined`.
+   * @type {string|undefined}
+   */
+  extName;
+
+  /**
+   * The schema ID (`$id`) for the argument.  This is automatically determined, and any user-provided `$id`s will be overwritten.
+   *
+   * @type {string}
+   */
+  ref;
+
+  /**
+   * The CLI argument, sans leading dashes.
+   * @type {string}
+   */
+  arg;
+
+  /**
+   * The desired keypath for the argument after arguments have been parsed.
+   *
+   * Typically this is camelCased.  If the arg came from an extension, it will be prefixed with
+   * `<extType>.<extName>.`
+   * @type {string}
+   */
+  dest;
+
+  /**
+   * Whatever the default value of this argument is, as specified by the
+   * `default` property of the schema.
+   * @type {D}
+   */
+  defaultValue;
+
+  /**
+   * Builds some computed fields and assigns them to the instance.
+   *
+   * Undefined properties are not assigned.
+   *
+   * The _constructor_ is private. Use {@link ArgSpec.create} instead.
+   * @private
+   * @template D
+   * @param {string} name
+   * @param {ArgSpecOptions<D>} [opts]
+   */
+  constructor (name, {extType, extName, dest, defaultValue} = {}) {
+    // we must normalize the extension name to fit into our convention for CLI
+    // args.
+    const arg = ArgSpec.toArg(name, extType, extName);
+
+    const ref = ArgSpec.toSchemaRef(name, extType, extName);
+
+    // if no explicit `dest` provided, just camelCase the name to avoid needing
+    // to use bracket syntax when accessing props on the parsed args object.
+    const baseDest = _.camelCase(dest ?? name);
+
+    const destKeypath =
+      extType && extName ? [extType, extName, baseDest].join('.') : baseDest;
+
+    this.defaultValue = defaultValue;
+    this.name = name;
+    this.extType = extType;
+    this.extName = extName;
+    this.arg = arg;
+    this.dest = destKeypath;
+    this.ref = ref;
+  }
+
+  /**
+   * Return the schema ID (`$id`) for the **argument** given the parameters.
+   *
+   * If you need the "root" or "base" schema ID, use {@link ArgSpec.toSchemaBaseRef} instead.
+   * @param {string} name - Argument name
+   * @param {ExtensionType} [extType] - Extension type
+   * @param {string} [extName] - Extension name
+   * @returns {string} Schema ID
+   */
+  static toSchemaRef (name, extType, extName) {
+    const baseRef = ArgSpec.toSchemaBaseRef(extType, extName);
+    if (extType && extName) {
+      return [`${baseRef}#`, PROPERTIES, name].join('/');
+    }
+    return [`${baseRef}#`, PROPERTIES, SERVER_PROP_NAME, PROPERTIES, name].join('/');
+  }
+
+  /**
+   * Return the schema ID for an extension or the base schema ID.
+   * @param {ExtensionType} [extType] - Extension type
+   * @param {string} [extName] - Extension name
+   */
+  static toSchemaBaseRef (extType, extName) {
+    if (extType && extName) {
+      return `${extType}-${ArgSpec.toNormalizedExtName(extName)}.json`;
+    }
+    return APPIUM_CONFIG_SCHEMA_ID;
+  }
+
+  /**
+   * Return the unique ID for the argument given the parameters.
+   * @param {string} name - Argument name
+   * @param {ExtensionType} [extType] - Extension type
+   * @param {string} [extName] - Extension name
+   * @returns {string} Unique ID
+   */
+  static toArg (name, extType, extName) {
+    const properName = _.kebabCase(name.replace(/^--?/, ''));
+    if (extType && extName) {
+      return [extType, _.kebabCase(extName), properName].join('-');
+    }
+    return properName;
+  }
+
+  /**
+   * Normalizes a raw extension name (not including the type).
+   * @param {string} extName - Extension name
+   * @returns {string} Normalized extension name
+   */
+  static toNormalizedExtName (extName) {
+    return _.kebabCase(extName);
+  }
+
+  /**
+   * When given the root ID of a schema for an extension (`<extType>-<normalizedExtName>.json`) Returns an object containing the extension type and the _normalized_ extension name.
+   * @param {string} schemaId - Root schema ID
+   * @returns {{extType: ExtensionType|undefined, normalizedExtName: string|undefined}}
+   */
+  static extensionInfoFromRootSchemaId (schemaId) {
+    const matches = schemaId.match(SCHEMA_ID_REGEXP);
+    if (matches?.groups) {
+      const {extType, normalizedExtName} = matches.groups;
+      return {extType, normalizedExtName};
+    }
+    return {};
+  }
+
+  /**
+   * Creates an `ArgSpec`
+   *
+   * @param {string} name - The canonical name of the argument. Corresponds to a key in a schema's
+   * `properties` property.
+   * @param {ArgSpecOptions} [opts] - Options
+   * @returns {Readonly<ArgSpec>}
+   */
+  static create (name, opts) {
+    return Object.freeze(new ArgSpec(name, opts));
+  }
+
+  /**
+   * String representation, useful for debugging
+   * @returns {string}
+   */
+  /* istanbul ignore next */
+  toString () {
+    let str = `[ArgSpec] ${this.name} (${this.ref})`;
+    if (this.extType && this.extName) {
+      str += ` (ext: ${this.extType}/${this.extName})`;
+    }
+    return str;
+  }
+}
+
+/**
+ * Options for {@link ArgSpec.create}
+ * @template D
+ * @typedef {Object} ArgSpecOptions
+ * @property {string} [extName]
+ * @property {ExtensionType} [extType]
+ * @property {string} [dest]
+ * @property {D} [defaultValue]
+ */
+
+/**
+ * @typedef {import('../ext-config-io').ExtensionType} ExtensionType
+ */