appium 2.0.0-beta.23 → 2.0.0-beta.26

package/lib/schema/schema.js

@@ -4,11 +4,41 @@ 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 '../constants';
 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';
+
+/**
+ * Key/value pairs go in... but they don't come out.
+ *
+ * @template K,V
+ * @extends {Map<K,V>}
+ */
+export class RoachHotelMap extends Map {
+  /**
+   * @param {K} key
+   * @param {V} value
+   */
+  set (key, value) {
+    if (this.has(key)) {
+      throw new Error(`${key} is already set`);
+    }
+    return super.set(key, value);
+  }
+
+  /**
+   * @param {K} key
+   */
+  // eslint-disable-next-line no-unused-vars
+  delete (key) {
+    return false;
+  }
+
+  clear () {
+    throw new Error(`Cannot clear RoachHotelMap`);
+  }
+}
 
 /**
  * Extensions that an extension schema file can have.
@@ -28,9 +58,9 @@ class AppiumSchema {
    *
    * Used to provide easy lookups of argument metadata when converting between different representations of those arguments.
    * @private
-   * @type {ReadonlyMap<string,ArgSpec>}
+   * @type {RoachHotelMap<string,ArgSpec>}
    */
-  _argSpecs = new ReadonlyMap();
+  _argSpecs = new RoachHotelMap();
 
   /**
    * A map of extension types to extension names to schema objects.
@@ -83,23 +113,27 @@ class AppiumSchema {
    * @returns {AppiumSchema}
    */
   static create () {
-    const instance = AppiumSchema._instance ?? new AppiumSchema();
-    AppiumSchema._instance = instance;
-
-    _.bindAll(instance, [
-      'finalize',
-      'flatten',
-      'getArgSpec',
-      'getDefaults',
-      'getSchema',
-      'hasArgSpec',
-      'isFinalized',
-      'registerSchema',
-      'reset',
-      'validate',
-    ]);
-
-    return instance;
+    if (!AppiumSchema._instance) {
+      const instance = new AppiumSchema();
+      AppiumSchema._instance = instance;
+      _.bindAll(instance, [
+        'finalize',
+        'flatten',
+        'getAllArgSpecs',
+        'getArgSpec',
+        'getDefaults',
+        'getDefaultsForExtension',
+        'getSchema',
+        'hasArgSpec',
+        'isFinalized',
+        'registerSchema',
+        'hasRegisteredSchema',
+        'reset',
+        'validate',
+      ]);
+    }
+
+    return AppiumSchema._instance;
   }
 
   /**
@@ -123,6 +157,10 @@ class AppiumSchema {
     return Boolean(this._finalizedSchemas);
   }
 
+  getAllArgSpecs () {
+    return this._argSpecs;
+  }
+
   /**
    * Call this when no more schemas will be registered.
    *
@@ -144,7 +182,7 @@ class AppiumSchema {
    */
   finalize () {
     if (this.isFinalized()) {
-      return /** @type {Record<string,StrictSchemaObject>} */ (
+      return /** @type {NonNullable<typeof this._finalizedSchemas>} */ (
         this._finalizedSchemas
       );
     }
@@ -152,7 +190,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 +240,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;
       },
@@ -253,7 +291,7 @@ class AppiumSchema {
     for (const schemaId of Object.keys(this._finalizedSchemas ?? {})) {
       this._ajv.removeSchema(schemaId);
     }
-    this._argSpecs = new ReadonlyMap();
+    this._argSpecs = new RoachHotelMap();
     this._registeredSchemas = {
       [DRIVER_TYPE]: new Map(),
       [PLUGIN_TYPE]: new Map(),
@@ -270,19 +308,21 @@ class AppiumSchema {
    * This is "fail-fast" in that the schema will immediately be validated against JSON schema draft-07 _or_ whatever the value of the schema's `$schema` prop is.
    *
    * Does _not_ add the schema to the `ajv` instance (this is done by {@link AppiumSchema.finalize}).
-   * @param {import('../ext-config-io').ExtensionType} extType - Extension type
+   * @param {ExtensionType} extType - Extension type
    * @param {string} extName - Unique extension name for `type`
    * @param {SchemaObject} schema - Schema object
    * @throws {SchemaNameConflictError} If the schema is an invalid
    * @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 +360,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 +440,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 +501,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 +535,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 +549,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 +626,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,21 +687,23 @@ 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
  */
 
 /**
- * @typedef {import('../ext-config-io').ExtensionType} ExtensionType
+ * @typedef {import('../extension/manifest').ExtensionType} ExtensionType
  */
 
 /**
  * An object having property `additionalProperties: false`
- * @typedef {Object} StrictProp
+ * @typedef StrictProp
  * @property {false} additionalProperties
  */
 
@@ -573,5 +716,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,35 @@
+// @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
@@ -216,36 +214,7 @@ function pullSettings (caps) {
   return result;
 }
 
-const rootDir = fs.findRoot(__dirname);
-
-
-/**
- * A Map where you can set properties, but only once. And you can't remove anything. So there.
- * @template K,V
- * @extends {Map<K,V>}
- */
-class ReadonlyMap extends Map {
-  /**
-   * @param {K} key
-   * @param {V} value
-   */
-  set (key, value) {
-    if (this.has(key)) {
-      throw new Error(`${key} is already set`);
-    }
-    return super.set(key, value);
-  }
-
-  delete (key) {
-    throw new Error(`${key} cannot be deleted`);
-  }
-
-  clear () {
-    throw new Error(`Cannot clear ReadonlyMap`);
-  }
-}
-
 export {
-  inspectObject, parseCapsForInnerDriver, insertAppiumPrefixes, rootDir,
-  getPackageVersion, pullSettings, removeAppiumPrefixes, ReadonlyMap
+  inspect, parseCapsForInnerDriver, insertAppiumPrefixes,
+  getPackageVersion, pullSettings, removeAppiumPrefixes
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appium",
-  "version": "2.0.0-beta.23",
+  "version": "2.0.0-beta.26",
   "description": "Automation for Apps.",
   "keywords": [
     "automation",
@@ -12,12 +12,14 @@
     "firefoxos",
     "testing"
   ],
+  "homepage": "https://appium.io",
   "bugs": {
     "url": "https://github.com/appium/appium/issues"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/appium/appium.git"
+    "url": "https://github.com/appium/appium.git",
+    "directory": "packages/appium"
   },
   "license": "Apache-2.0",
   "author": "https://github.com/appium",
@@ -28,45 +30,52 @@
     "lib": "./lib"
   },
   "files": [
-    "bin",
     "lib",
     "build",
     "index.js",
-    "postinstall.js",
+    "scripts/postinstall.js",
     "types"
   ],
   "scripts": {
-    "generate-docs": "gulp transpile && node ./build/commands-yml/parse.js",
-    "postinstall": "node ./postinstall.js",
-    "upload": "gulp github-upload",
-    "zip": "zip -qr appium.zip .",
-    "zip-and-upload": "npm run zip && npm run upload"
+    "build": "babel lib --root-mode=upward --delete-dir-on-start --out-dir=build/lib",
+    "postbuild": "npm run generate-schema-json",
+    "dev": "npm run build -- --watch",
+    "fix": "npm run lint -- --fix",
+    "generate-docs": "node ./scripts/parse-yml-commands.js",
+    "generate-schema-json": "node ./scripts/generate-schema-json.js",
+    "generate-schema-declarations": "node ./scripts/generate-schema-declarations.js",
+    "postinstall": "node ./scripts/postinstall.js",
+    "lint": "eslint -c ../../.eslintrc --ignore-path ../../.eslintignore .",
+    "test": "npm run test:unit",
+    "test:e2e": "mocha --require ../../test/setup-babel.js --timeout 20s --slow 10s \"./test/e2e/**/*.spec.js\"",
+    "test:unit": "mocha --require ../../test/setup-babel.js \"./test/unit/**/*.spec.js\""
   },
   "dependencies": {
-    "@appium/base-driver": "^8.2.2",
-    "@appium/base-plugin": "1.8.0",
-    "@appium/support": "^2.55.2",
-    "@babel/runtime": "7.16.3",
-    "@sidvind/better-ajv-errors": "0.9.2",
-    "ajv": "8.8.2",
+    "@appium/base-driver": "^8.3.0",
+    "@appium/base-plugin": "1.8.1",
+    "@appium/support": "^2.56.0",
+    "@babel/runtime": "7.17.8",
+    "@sidvind/better-ajv-errors": "1.1.1",
+    "ajv": "8.10.0",
     "ajv-formats": "2.1.1",
     "argparse": "2.0.1",
-    "async-lock": "1.3.0",
+    "async-lock": "1.3.1",
     "asyncbox": "2.9.2",
-    "axios": "0.24.0",
+    "axios": "0.26.1",
     "bluebird": "3.7.2",
     "continuation-local-storage": "3.2.1",
     "find-up": "5.0.0",
     "lilconfig": "2.0.4",
     "lodash": "4.17.21",
     "longjohn": "0.2.12",
-    "npmlog": "5.0.1",
+    "npmlog": "6.0.1",
     "ora": "5.4.1",
+    "package-changed": "1.9.0",
     "resolve-from": "5.0.0",
     "semver": "7.3.5",
     "source-map-support": "0.5.21",
     "teen_process": "1.16.0",
-    "winston": "3.3.3",
+    "winston": "3.6.0",
     "word-wrap": "1.2.3",
     "yaml": "1.10.2"
   },
@@ -78,6 +87,5 @@
     "access": "public",
     "tag": "next"
   },
-  "homepage": "https://appium.io",
-  "gitHead": "280d409df6c02d36b4ffc4d02a95ab3f4649b08c"
+  "gitHead": "f5cce0f29d31699decea63ed94c4506f7af469df"
 }

package/{postinstall.js → scripts/postinstall.js}

@@ -12,7 +12,7 @@ async function main () {
 
   let extension;
   try {
-    extension = require('./build/lib/cli/extension');
+    extension = require('../build/lib/cli/extension');
   } catch (e) {
     throw new Error(`Could not load extension CLI file; has the project been transpiled? ` +
                     `(${e.message})`);