appium 2.0.0-beta.21 → 2.0.0-beta.25

package/lib/schema/arg-spec.js

@@ -73,6 +73,11 @@ export class ArgSpec {
    */
   dest;
 
+  /**
+   * The same as {@link ArgSpec.dest} but without the leading `<extType>.<extName>.` prefix.
+   */
+  rawDest;
+
   /**
    * Whatever the default value of this argument is, as specified by the
    * `default` property of the schema.
@@ -100,10 +105,10 @@ export class ArgSpec {
 
     // 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 rawDest = _.camelCase(dest ?? name);
 
     const destKeypath =
-      extType && extName ? [extType, extName, baseDest].join('.') : baseDest;
+      extType && extName ? [extType, extName, rawDest].join('.') : rawDest;
 
     this.defaultValue = defaultValue;
     this.name = name;
@@ -112,6 +117,7 @@ export class ArgSpec {
     this.arg = arg;
     this.dest = destKeypath;
     this.ref = ref;
+    this.rawDest = rawDest;
   }
 
   /**
@@ -170,7 +176,7 @@ export class ArgSpec {
   /**
    * 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}}
+   * @returns { {extType: ExtensionType|undefined, normalizedExtName: string|undefined} }
    */
   static extensionInfoFromRootSchemaId (schemaId) {
     const matches = schemaId.match(SCHEMA_ID_REGEXP);
@@ -216,3 +222,7 @@ export class ArgSpec {
  * @property {string} [dest]
  * @property {D} [defaultValue]
  */
+
+/**
+ * @typedef {import('../ext-config-io').ExtensionType} ExtensionType
+ */

package/lib/schema/cli-args.js

@@ -79,26 +79,36 @@ function getSchemaValidator ({ref: schemaId}, coerce = _.identity) {
   };
 }
 
+/**
+ * Determine the description for display on the CLI, given the schema.
+ * @param {AppiumJSONSchema} schema
+ * @returns {string}
+ */
+function makeDescription (schema) {
+  const {appiumCliDescription, description = '', appiumDeprecated} = schema;
+  let desc = appiumCliDescription ?? description;
+  if (appiumDeprecated) {
+    desc = `[DEPRECATED] ${desc}`;
+  }
+  return desc;
+}
+
 /**
  * Given arg `name`, a JSON schema `subSchema`, and options, return an argument definition
  * as understood by `argparse`.
  * @param {AppiumJSONSchema} subSchema - JSON schema for the option
  * @param {ArgSpec} argSpec - Argument spec tuple
- * @param {SubSchemaToArgDefOptions} [opts] - Options
  * @returns {[string[], import('argparse').ArgumentOptions]} Tuple of flag and options
  */
-function subSchemaToArgDef (subSchema, argSpec, opts = {}) {
-  const {overrides = {}} = opts;
+function subSchemaToArgDef (subSchema, argSpec) {
   let {
     type,
     appiumCliAliases,
     appiumCliTransformer,
-    appiumCliDescription,
-    description,
     enum: enumValues,
   } = subSchema;
 
-  const {name, arg, dest} = argSpec;
+  const {name, arg} = argSpec;
 
   const aliases = [
     aliasToFlag(argSpec),
@@ -110,7 +120,7 @@ function subSchemaToArgDef (subSchema, argSpec, opts = {}) {
   /** @type {import('argparse').ArgumentOptions} */
   let argOpts = {
     required: false,
-    help: appiumCliDescription ?? description,
+    help: makeDescription(subSchema)
   };
 
   /**
@@ -130,7 +140,8 @@ function subSchemaToArgDef (subSchema, argSpec, opts = {}) {
   switch (type) {
     // booleans do not have a type per `ArgumentOptions`, just an "action"
     case TYPENAMES.BOOLEAN: {
-      argOpts.action = 'store_true';
+      argOpts.action = 'store_const';
+      argOpts.const = true;
       break;
     }
 
@@ -215,16 +226,6 @@ function subSchemaToArgDef (subSchema, argSpec, opts = {}) {
     }
   }
 
-  // overrides override anything we computed here.  usually this involves "custom types",
-  // which are really just transform functions.
-  argOpts = _.merge(
-    argOpts,
-    /** should the override keys correspond to the prop name or the prop dest?
-     * the prop dest is computed by {@link aliasToDest}.
-     */
-    overrides[dest] ?? {},
-  );
-
   return [aliases, argOpts];
 }
 
@@ -232,32 +233,19 @@ function subSchemaToArgDef (subSchema, argSpec, opts = {}) {
  * Converts the finalized, flattened schema representation into
  * ArgumentDefinitions for handoff to `argparse`.
  *
- * @param {ToParserArgsOptions} opts - Options
  * @throws If schema has not been added to ajv (via `finalizeSchema()`)
  * @returns {import('../cli/args').ArgumentDefinitions} A map of arryas of
  * aliases to `argparse` arguments; empty if no schema found
  */
-export function toParserArgs (opts = {}) {
-  const flattened = flattenSchema();
+export function toParserArgs () {
+  const flattened = flattenSchema().filter(({schema}) => !schema.appiumCliIgnored);
   return new Map(
     _.map(flattened, ({schema, argSpec}) =>
-      subSchemaToArgDef(schema, argSpec, opts),
+      subSchemaToArgDef(schema, argSpec),
     ),
   );
 }
 
-/**
- * Options for {@link toParserArgs}
- * @typedef {SubSchemaToArgDefOptions} ToParserArgsOptions
- */
-
-/**
- * Options for {@link subSchemaToArgDef}.
- * @typedef {Object} SubSchemaToArgDefOptions
- * @property {string} [prefix] - The prefix to use for the flag, if any
- * @property {{[key: string]: import('argparse').ArgumentOptions}} [overrides] - An object of key/value pairs to override the default values
- */
-
 /**
  * @template T
  * @typedef {import('ajv/dist/types').FormatValidator<T>} FormatValidator<T>

package/lib/schema/keywords.js

@@ -86,11 +86,26 @@ export const keywords = {
    * Flag to tell Appium to _not_ provide this property as a CLI argument.
    * @type {KeywordDefinition}
    */
-  appiumCliIgnore: {
-    keyword: 'appiumCliIgnore',
+  appiumCliIgnored: {
+    keyword: 'appiumCliIgnored',
     metaSchema: {
       type: 'boolean',
-      description: 'If `true`, Appium will not provide this property as a CLI argument.'
+      description: 'If `true`, Appium will not provide this property as a CLI argument. This is NOT the same as a "hidden" argument.',
+      enum: [true]
+    }
+  },
+
+  /**
+   * Mark this property as deprecated.
+   * @type {KeywordDefinition}
+   */
+  appiumDeprecated: {
+    keyword: 'appiumDeprecated',
+    metaSchema: {
+      type: 'boolean',
+      description: 'If `true`, this property will be displayed as "deprecated" to the user',
+      enum: [true],
+      $comment: 'JSON schema draft-2019-09 keyword `deprecated` serves the same purpose. This keyword should itself be deprecated if we move to draft-2019-09!'
     }
   }
 };
@@ -109,8 +124,9 @@ export const keywords = {
  * @property {string} [appiumCliDest]
  * @property {string} [appiumCliDescription]
  * @property {string[]} [appiumCliAliases]
- * @property {boolean} [appiumCliIgnore]
+ * @property {boolean} [appiumCliIgnored]
  * @property {AppiumCliTransformerName} [appiumCliTransformer]
+ * @property {boolean} [appiumDeprecated]
  */
 
 

package/lib/schema/schema.js

@@ -4,11 +4,11 @@ import Ajv from 'ajv';
 import addFormats from 'ajv-formats';
 import _ from 'lodash';
 import path from 'path';
-import {DRIVER_TYPE, PLUGIN_TYPE} from '../extension-config';
-import {ReadonlyMap} from '../utils';
+import { DRIVER_TYPE, PLUGIN_TYPE } from '../extension-config';
+import { ReadonlyMap } from '../utils';
 import appiumConfigSchema from './appium-config-schema';
-import {ArgSpec, SERVER_PROP_NAME, APPIUM_CONFIG_SCHEMA_ID} from './arg-spec';
-import {keywords} from './keywords';
+import { APPIUM_CONFIG_SCHEMA_ID, ArgSpec, SERVER_PROP_NAME } from './arg-spec';
+import { keywords } from './keywords';
 
 /**
  * Extensions that an extension schema file can have.
@@ -89,8 +89,10 @@ class AppiumSchema {
     _.bindAll(instance, [
       'finalize',
       'flatten',
+      'getAllArgSpecs',
       'getArgSpec',
       'getDefaults',
+      'getDefaultsForExtension',
       'getSchema',
       'hasArgSpec',
       'isFinalized',
@@ -123,6 +125,10 @@ class AppiumSchema {
     return Boolean(this._finalizedSchemas);
   }
 
+  getAllArgSpecs () {
+    return this._argSpecs;
+  }
+
   /**
    * Call this when no more schemas will be registered.
    *
@@ -152,7 +158,7 @@ class AppiumSchema {
     const ajv = this._ajv;
 
     // Ajv will _mutate_ the schema, so we need to clone it.
-    const baseSchema = _.cloneDeep(/** @type {StrictSchemaObject} */(appiumConfigSchema));
+    const baseSchema = _.cloneDeep(appiumConfigSchema);
 
     /**
      *
@@ -202,7 +208,7 @@ class AppiumSchema {
           ajv.validateSchema(schema, true);
           addArgSpecs(schema.properties, extType, extName);
           ajv.addSchema(schema, $ref);
-          finalizedSchemas[$ref] = /** @type {StrictSchemaObject} */(schema);
+          finalizedSchemas[$ref] = /** @type {StrictSchemaObject} */ (schema);
         });
         return baseSchema;
       },
@@ -277,12 +283,14 @@ class AppiumSchema {
    * @returns {void}
    */
   registerSchema (extType, extName, schema) {
-    if (!(extType && extName && !_.isEmpty(schema))) {
+    if (!(extType && extName) || _.isUndefined(schema)) {
       throw new TypeError(
-        'Expected nonempty extension type, extension name and schema parameters',
+        'Expected extension type, extension name, and a defined schema',
       );
     }
-
+    if (!AppiumSchema.isSupportedSchemaType(schema)) {
+      throw new SchemaUnsupportedSchemaError(schema, extType, extName);
+    }
     const normalizedExtName = _.kebabCase(extName);
     if (this.hasRegisteredSchema(extType, normalizedExtName)) {
       if (this._registeredSchemas[extType].get(normalizedExtName) === schema) {
@@ -320,22 +328,67 @@ class AppiumSchema {
   /**
    * Returns a `Record` of argument "dest" strings to default values.
    *
-   * The "dest" string is the property name in object returned by `argparse.ArgumentParser['parse_args']`.
-   * @returns {Record<string,ArgSpec['defaultValue']>}
+   * The "dest" string is the property name in object returned by
+   * `argparse.ArgumentParser['parse_args']`.
+   * @template {boolean|undefined} Flattened
+   * @param {Flattened} [flatten=true] - If `true`, flattens the returned object
+   * using "keypath"-style keys of the format `<extType>.<extName>.<argName>`.
+   * Otherwise, returns a nested object using `extType` and `extName` as
+   * properties. Base arguments (server arguments) are always at the top level.
+   * @returns {DefaultValues<Flattened>}
    */
-  getDefaults () {
+  getDefaults (flatten = /** @type {Flattened} */ (true)) {
     if (!this.isFinalized()) {
       throw new SchemaFinalizationError();
     }
-    return [...this._argSpecs.values()].reduce(
-      (defaults, {defaultValue, dest}) => {
+
+    /**
+     * @private
+     * @callback DefaultReducer
+     * @param {DefaultValues<Flattened>} defaults
+     * @param {ArgSpec} argSpec
+     * @returns {DefaultValues<Flattened>}
+     */
+    /** @type {DefaultReducer} */
+    const reducer = flatten
+      ? (defaults, {defaultValue, dest}) => {
         if (!_.isUndefined(defaultValue)) {
           defaults[dest] = defaultValue;
         }
         return defaults;
-      },
-      {},
+      }
+      : (defaults, {defaultValue, dest}) => {
+        if (!_.isUndefined(defaultValue)) {
+          _.set(defaults, dest, defaultValue);
+        }
+        return defaults;
+      };
+
+    /** @type {DefaultValues<Flattened>} */
+    const retval = {};
+    return [...this._argSpecs.values()].reduce(reducer, retval);
+  }
+
+  /**
+   * Returns a flattened Record of defaults for a specific extension. Keys will
+   * be of format `<argName>`.
+   * @param {ExtensionType} extType - Extension type
+   * @param {string} extName - Extension name
+   * @returns {Record<string,ArgSpecDefaultValue>}
+   */
+  getDefaultsForExtension (extType, extName) {
+    if (!this.isFinalized()) {
+      throw new SchemaFinalizationError();
+    }
+    const specs = [...this._argSpecs.values()].filter(
+      (spec) => spec.extType === extType && spec.extName === extName,
     );
+    return specs.reduce((defaults, {defaultValue, rawDest}) => {
+      if (!_.isUndefined(defaultValue)) {
+        defaults[rawDest] = defaultValue;
+      }
+      return defaults;
+    }, {});
   }
 
   /**
@@ -355,7 +408,7 @@ class AppiumSchema {
   flatten () {
     const schema = this.getSchema();
 
-    /** @type {{properties: SchemaObject, prefix: string[]}[]} */
+    /** @type { {properties: SchemaObject, prefix: string[]}[] } */
     const stack = [{properties: schema.properties, prefix: []}];
     /** @type {FlattenedSchema} */
     const flattened = [];
@@ -416,7 +469,7 @@ class AppiumSchema {
    * Retrieves the schema itself
    * @public
    * @param {string} [ref] - Schema ID
-   * @throws If the schema has not yet been _finalized_
+   * @throws If the schema has not yet been finalized
    * @returns {SchemaObject}
    */
   getSchema (ref = APPIUM_CONFIG_SCHEMA_ID) {
@@ -450,9 +503,7 @@ class AppiumSchema {
    * @returns {import('ajv').ErrorObject[]} Array of errors, if any.
    */
   validate (value, ref = APPIUM_CONFIG_SCHEMA_ID) {
-    const validator = /** @type {import('ajv').ValidateFunction} */ (
-      this._getValidator(ref)
-    );
+    const validator = this._getValidator(ref);
     return !validator(value) && _.isArray(validator.errors)
       ? [...validator.errors]
       : [];
@@ -466,6 +517,15 @@ class AppiumSchema {
   static isAllowedSchemaFileExtension (filename) {
     return ALLOWED_SCHEMA_EXTENSIONS.has(path.extname(filename));
   }
+
+  /**
+   * Returns `true` if `schema` is a plain object with a non-true `$async` property.
+   * @param {any} schema - Schema to check
+   * @returns {schema is SchemaObject}
+   */
+  static isSupportedSchemaType (schema) {
+    return _.isPlainObject(schema) && schema.$async !== true;
+  }
 }
 
 /**
@@ -534,10 +594,59 @@ export class SchemaUnknownSchemaError extends ReferenceError {
   }
 }
 
+/**
+ * Thrown when a schema is provided, but it's of an unsupported type.
+ *
+ * "Valid" schemas which are unsupported include boolean schemas and async schemas
+ * (having a `true` `$async` property).
+ */
+export class SchemaUnsupportedSchemaError extends TypeError {
+  /**
+   * @type {Readonly<string>}
+   */
+  code = 'APPIUMERR_SCHEMA_UNSUPPORTED_SCHEMA';
+
+  /**
+   * @type {Readonly<{schema: any, extType: ExtensionType, extName: string}>}
+   */
+  data;
+
+  /**
+   * @param {any} schema
+   * @param {ExtensionType} extType
+   * @param {string} extName
+   */
+  constructor (schema, extType, extName) {
+    // https://github.com/Microsoft/TypeScript/issues/8277
+    super(
+      (() => {
+        let msg = `Unsupported schema from ${extType} "${extName}":`;
+        if (_.isBoolean(schema)) {
+          return `${msg} schema cannot be a boolean`;
+        }
+        if (_.isPlainObject(schema)) {
+          if (schema.$async) {
+            return `${msg} schema cannot be an async schema`;
+          }
+          /* istanbul ignore next */
+          throw new TypeError(
+            `schema IS supported; this error should not be thrown (this is a bug). value of schema: ${JSON.stringify(
+              schema,
+            )}`,
+          );
+        }
+        return `${msg} schema must be a plain object without a true "$async" property`;
+      })(),
+    );
+    this.data = {schema, extType, extName};
+  }
+}
+
 const appiumSchema = AppiumSchema.create();
 
 export const {
   registerSchema,
+  getAllArgSpecs,
   getArgSpec,
   hasArgSpec,
   isFinalized,
@@ -546,12 +655,14 @@ export const {
   validate,
   getSchema,
   flatten: flattenSchema,
-  getDefaults: getDefaultsFromSchema,
+  getDefaults: getDefaultsForSchema,
+  getDefaultsForExtension,
 } = appiumSchema;
 export const {isAllowedSchemaFileExtension} = AppiumSchema;
 
 /**
- * @typedef {import('ajv').SchemaObject} SchemaObject
+ * Appium only supports schemas that are plain objects; not arrays.
+ * @typedef {import('ajv').SchemaObject & {[key: number]: never}} SchemaObject
  */
 
 /**
@@ -573,5 +684,20 @@ export const {isAllowedSchemaFileExtension} = AppiumSchema;
  * A list of schemas associated with properties and their corresponding {@link ArgSpec} objects.
  *
  * Intermediate data structure used when converting the entire schema down to CLI arguments.
- * @typedef {{schema: SchemaObject, argSpec: ArgSpec}[]} FlattenedSchema
+ * @typedef { {schema: SchemaObject, argSpec: ArgSpec}[] } FlattenedSchema
+ */
+
+/**
+ * @typedef {ArgSpec['defaultValue']} ArgSpecDefaultValue
+ */
+
+/**
+ * e.g. `{driver: {foo: 'bar'}}` where `foo` is the arg name and `bar` is the default value.
+ * @typedef {Record<string,Record<string,ArgSpecDefaultValue>>} NestedArgSpecDefaultValue
+ */
+
+/**
+ * Helper type for the return value of {@link AppiumSchema.getDefaults}
+ * @template {boolean|undefined} Flattened
+ * @typedef {Record<string,Flattened extends true ? ArgSpecDefaultValue : ArgSpecDefaultValue | NestedArgSpecDefaultValue>} DefaultValues
  */

package/lib/utils.js

@@ -1,37 +1,36 @@
+// @ts-check
+
 import _ from 'lodash';
 import logger from './logger';
+// @ts-ignore
 import { processCapabilities, PROTOCOLS } from '@appium/base-driver';
 import { fs } from '@appium/support';
+import { inspect as dump } from 'util';
 
 const W3C_APPIUM_PREFIX = 'appium';
 
-function inspectObject (args) {
-  function getValueArray (obj, indent = '  ') {
-    if (!_.isObject(obj)) {
-      return [obj];
-    }
+/**
+ *
+ * If `stdout` is a TTY, this is `true`.
+ *
+ * Used for tighter control over log output.
+ * @type {boolean}
+ */
+const isStdoutTTY = process.stdout.isTTY;
 
-    let strArr = ['{'];
-    for (let [arg, value] of _.toPairs(obj)) {
-      if (!_.isObject(value)) {
-        strArr.push(`${indent}  ${arg}: ${value}`);
-      } else {
-        value = getValueArray(value, `${indent}  `);
-        strArr.push(`${indent}  ${arg}: ${value.shift()}`);
-        strArr.push(...value);
-      }
-    }
-    strArr.push(`${indent}}`);
-    return strArr;
-  }
-  for (let [arg, value] of _.toPairs(args)) {
-    value = getValueArray(value);
-    logger.info(`  ${arg}: ${value.shift()}`);
-    for (let val of value) {
-      logger.info(val);
-    }
-  }
-}
+/**
+ * Dumps to value to the console using `info` logger.
+ *
+ * @todo May want to force color to be `false` if {@link isStdoutTTY} is `false`.
+ */
+const inspect = _.flow(
+  _.partialRight(
+    /** @type {(object: any, options: import('util').InspectOptions) => string} */(dump),
+    {colors: true, depth: null, compact: !isStdoutTTY}
+  ),
+  (...args) => {
+    logger.info(...args);
+  });
 
 /**
  * Takes the caps that were provided in the request and translates them
@@ -236,8 +235,8 @@ class ReadonlyMap extends Map {
     return super.set(key, value);
   }
 
-  delete (key) {
-    throw new Error(`${key} cannot be deleted`);
+  delete () {
+    return false;
   }
 
   clear () {
@@ -246,6 +245,6 @@ class ReadonlyMap extends Map {
 }
 
 export {
-  inspectObject, parseCapsForInnerDriver, insertAppiumPrefixes, rootDir,
+  inspect, parseCapsForInnerDriver, insertAppiumPrefixes, rootDir,
   getPackageVersion, pullSettings, removeAppiumPrefixes, ReadonlyMap
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appium",
-  "version": "2.0.0-beta.21",
+  "version": "2.0.0-beta.25",
   "description": "Automation for Apps.",
   "keywords": [
     "automation",
@@ -21,9 +21,8 @@
   },
   "license": "Apache-2.0",
   "author": "https://github.com/appium",
-  "main": "./build/lib/main.js",
   "bin": {
-    "appium": "./build/lib/main.js"
+    "appium": "index.js"
   },
   "directories": {
     "lib": "./lib"
@@ -31,25 +30,25 @@
   "files": [
     "bin",
     "lib",
-    "build/lib",
+    "build",
+    "index.js",
     "postinstall.js",
     "types"
   ],
   "scripts": {
     "generate-docs": "gulp transpile && node ./build/commands-yml/parse.js",
     "postinstall": "node ./postinstall.js",
-    "install-fake-driver": "node . driver install --source=local ../fake-driver",
     "upload": "gulp github-upload",
     "zip": "zip -qr appium.zip .",
     "zip-and-upload": "npm run zip && npm run upload"
   },
   "dependencies": {
-    "@appium/base-driver": "^8.2.0",
+    "@appium/base-driver": "^8.2.4",
     "@appium/base-plugin": "1.8.0",
-    "@appium/support": "^2.55.1",
+    "@appium/support": "^2.55.4",
     "@babel/runtime": "7.16.3",
     "@sidvind/better-ajv-errors": "0.9.2",
-    "ajv": "8.8.0",
+    "ajv": "8.8.2",
     "ajv-formats": "2.1.1",
     "argparse": "2.0.1",
     "async-lock": "1.3.0",
@@ -65,16 +64,12 @@
     "ora": "5.4.1",
     "resolve-from": "5.0.0",
     "semver": "7.3.5",
-    "source-map-support": "0.5.20",
+    "source-map-support": "0.5.21",
     "teen_process": "1.16.0",
     "winston": "3.3.3",
     "word-wrap": "1.2.3",
     "yaml": "1.10.2"
   },
-  "devDependencies": {
-    "@appium/fake-driver": "^3.2.0",
-    "@appium/gulp-plugins": "^5.5.5"
-  },
   "engines": {
     "node": ">=12",
     "npm": ">=6"
@@ -84,5 +79,5 @@
     "tag": "next"
   },
   "homepage": "https://appium.io",
-  "gitHead": "ec6a90a797d2dadb407922426be16efaec9def07"
+  "gitHead": "42f4a2de2d763d57cf0bdb6fb6c9a3bc9c3d232f"
 }

package/types/types.d.ts

@@ -160,6 +160,11 @@ interface MoreArgs {
   /**
    * If true, show the build info and exit
    */
+  showBuildInfo: boolean;
+
+  /**
+   * If true, show config and exit
+   */
   showConfig: boolean;
 
   /**