appium 2.0.0-beta.26 → 2.0.0-beta.29

package/lib/schema/cli-transformers.js

@@ -1,4 +1,3 @@
-// @ts-check
 
 import { ArgumentTypeError } from 'argparse';
 import { readFileSync } from 'fs';

package/lib/schema/keywords.js

@@ -1,4 +1,3 @@
-// @ts-check
 
 import { transformers } from './cli-transformers';
 

package/lib/schema/schema.js

@@ -1,11 +1,10 @@
-// @ts-check
 
 import Ajv from 'ajv';
 import addFormats from 'ajv-formats';
 import _ from 'lodash';
 import path from 'path';
 import { DRIVER_TYPE, PLUGIN_TYPE } from '../constants';
-import appiumConfigSchema from './appium-config-schema';
+import { AppiumConfigJsonSchema } from '@appium/schema';
 import { APPIUM_CONFIG_SCHEMA_ID, ArgSpec, SERVER_PROP_NAME } from './arg-spec';
 import { keywords } from './keywords';
 
@@ -190,7 +189,7 @@ class AppiumSchema {
     const ajv = this._ajv;
 
     // Ajv will _mutate_ the schema, so we need to clone it.
-    const baseSchema = _.cloneDeep(appiumConfigSchema);
+    const baseSchema = _.cloneDeep(AppiumConfigJsonSchema);
 
     /**
      *

package/lib/utils.js

@@ -1,8 +1,6 @@
-// @ts-check
 
 import _ from 'lodash';
 import logger from './logger';
-// @ts-ignore
 import { processCapabilities, PROTOCOLS } from '@appium/base-driver';
 import { inspect as dump } from 'util';
 
@@ -35,25 +33,28 @@ const inspect = _.flow(
  * Takes the caps that were provided in the request and translates them
  * into caps that can be used by the inner drivers.
  *
- * @param {Object} jsonwpCapabilities
- * @param {Object} w3cCapabilities
- * @param {Object} constraints
- * @param {Object} defaultCapabilities
+ * @param {any} jsonwpCapabilities
+ * @param {W3CCapabilities} w3cCapabilities
+ * @param {import('@appium/types').Constraints} constraints
+ * @param {import('@appium/types').DefaultCapabilitiesConfig} [defaultCapabilities]
+ * @returns {ParsedDriverCaps|InvalidCaps}
  */
 function parseCapsForInnerDriver (jsonwpCapabilities, w3cCapabilities, constraints = {}, defaultCapabilities = {}) {
   // Check if the caller sent JSONWP caps, W3C caps, or both
   const hasW3CCaps = _.isPlainObject(w3cCapabilities) &&
     (_.has(w3cCapabilities, 'alwaysMatch') || _.has(w3cCapabilities, 'firstMatch'));
   const hasJSONWPCaps = _.isPlainObject(jsonwpCapabilities);
-  let desiredCaps = {};
-  let processedW3CCapabilities = null;
-  let processedJsonwpCapabilities = null;
+  let desiredCaps = /** @type {ParsedDriverCaps['desiredCaps']} */({});
+  /** @type {ParsedDriverCaps['processedW3CCapabilities']} */
+  let processedW3CCapabilities;
+  /** @type {ParsedDriverCaps['processedJsonwpCapabilities']} */
+  let processedJsonwpCapabilities;
 
   if (!hasW3CCaps) {
-    return {
+    return /** @type {InvalidCaps} */({
       protocol: PROTOCOLS.W3C,
       error: new Error('W3C capabilities should be provided'),
-    };
+    });
   }
 
   const {W3C} = PROTOCOLS;
@@ -93,7 +94,7 @@ function parseCapsForInnerDriver (jsonwpCapabilities, w3cCapabilities, constrain
       }
     }
     if (hasJSONWPCaps) {
-      jsonwpCapabilities = Object.assign({}, removeAppiumPrefixes(defaultCapabilities), jsonwpCapabilities);
+      jsonwpCapabilities = {...removeAppiumPrefixes(defaultCapabilities), ...jsonwpCapabilities};
     }
   }
 
@@ -110,13 +111,13 @@ function parseCapsForInnerDriver (jsonwpCapabilities, w3cCapabilities, constrain
       desiredCaps = processCapabilities(w3cCapabilities, constraints, true);
     } catch (error) {
       logger.info(`Could not parse W3C capabilities: ${error.message}`);
-      return {
+      return /** @type {InvalidCaps} */({
         desiredCaps,
         processedJsonwpCapabilities,
         processedW3CCapabilities,
         protocol,
         error,
-      };
+      });
     }
 
     // Create a new w3c capabilities payload that contains only the matching caps in `alwaysMatch`
@@ -126,12 +127,13 @@ function parseCapsForInnerDriver (jsonwpCapabilities, w3cCapabilities, constrain
     };
   }
 
-  return {desiredCaps, processedJsonwpCapabilities, processedW3CCapabilities, protocol};
+  return /** @type {ParsedDriverCaps} */({desiredCaps, processedJsonwpCapabilities, processedW3CCapabilities, protocol});
 }
 
 /**
  * Takes a capabilities objects and prefixes capabilities with `appium:`
- * @param {Object} caps Desired capabilities object
+ * @param {Capabilities} caps Desired capabilities object
+ * @returns {AppiumW3CCapabilities}
  */
 function insertAppiumPrefixes (caps) {
   // Standard, non-prefixed capabilities (see https://www.w3.org/TR/webdriver/#dfn-table-of-standard-capabilities)
@@ -158,11 +160,17 @@ function insertAppiumPrefixes (caps) {
   return prefixedCaps;
 }
 
+/**
+ *
+ * @param {AppiumW3CCapabilities} caps
+ * @returns {Capabilities}
+ */
 function removeAppiumPrefixes (caps) {
   if (!_.isPlainObject(caps)) {
     return caps;
   }
 
+  /** @type {Capabilities} */
   const fixedCaps = {};
   for (let [name, value] of _.toPairs(caps)) {
     fixedCaps[removeAppiumPrefix(name)] = value;
@@ -218,3 +226,28 @@ export {
   inspect, parseCapsForInnerDriver, insertAppiumPrefixes,
   getPackageVersion, pullSettings, removeAppiumPrefixes
 };
+
+/**
+ * @todo protocol is more specific
+ * @typedef ParsedDriverCaps
+ * @property {Capabilities} desiredCaps
+ * @property {string} protocol
+ * @property {any} [processedJsonwpCapabilities]
+ * @property {W3CCapabilities} [processedW3CCapabilities]
+ */
+
+/**
+ * @todo protocol is more specific
+ * @typedef InvalidCaps
+ * @property {Error} error
+ * @property {string} protocol
+ * @property {Capabilities} [desiredCaps]
+ * @property {any} [processedJsonwpCapabilities]
+ * @property {W3CCapabilities} [processedW3CCapabilities]
+ */
+
+/**
+ * @typedef {import('@appium/types').W3CCapabilities} W3CCapabilities
+ * @typedef {import('@appium/types').Capabilities} Capabilities
+ * @typedef {import('@appium/types').AppiumW3CCapabilities} AppiumW3CCapabilities
+ */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appium",
-  "version": "2.0.0-beta.26",
+  "version": "2.0.0-beta.29",
   "description": "Automation for Apps.",
   "keywords": [
     "automation",
@@ -37,13 +37,10 @@
     "types"
   ],
   "scripts": {
-    "build": "babel lib --root-mode=upward --delete-dir-on-start --out-dir=build/lib",
-    "postbuild": "npm run generate-schema-json",
+    "build": "babel lib --root-mode=upward --out-dir=build/lib",
     "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",
@@ -51,31 +48,31 @@
     "test:unit": "mocha --require ../../test/setup-babel.js \"./test/unit/**/*.spec.js\""
   },
   "dependencies": {
-    "@appium/base-driver": "^8.3.0",
+    "@appium/base-driver": "file:../base-driver",
     "@appium/base-plugin": "1.8.1",
-    "@appium/support": "^2.56.0",
-    "@babel/runtime": "7.17.8",
+    "@appium/schema": "file:../schema",
+    "@appium/support": "file:../support",
+    "@babel/runtime": "7.17.9",
     "@sidvind/better-ajv-errors": "1.1.1",
-    "ajv": "8.10.0",
+    "ajv": "8.11.0",
     "ajv-formats": "2.1.1",
     "argparse": "2.0.1",
     "async-lock": "1.3.1",
     "asyncbox": "2.9.2",
     "axios": "0.26.1",
     "bluebird": "3.7.2",
-    "continuation-local-storage": "3.2.1",
     "find-up": "5.0.0",
-    "lilconfig": "2.0.4",
+    "lilconfig": "2.0.5",
     "lodash": "4.17.21",
     "longjohn": "0.2.12",
     "npmlog": "6.0.1",
     "ora": "5.4.1",
     "package-changed": "1.9.0",
     "resolve-from": "5.0.0",
-    "semver": "7.3.5",
+    "semver": "7.3.6",
     "source-map-support": "0.5.21",
     "teen_process": "1.16.0",
-    "winston": "3.6.0",
+    "winston": "3.7.2",
     "word-wrap": "1.2.3",
     "yaml": "1.10.2"
   },
@@ -87,5 +84,6 @@
     "access": "public",
     "tag": "next"
   },
-  "gitHead": "f5cce0f29d31699decea63ed94c4506f7af469df"
+  "types": "./build/lib/index.d.ts",
+  "gitHead": "ec6a90a797d2dadb407922426be16efaec9def07"
 }

package/types/appium-manifest.d.ts

@@ -0,0 +1,61 @@
+import { CommonMetadata, ExtMetadata, SchemaMetadata } from './external-manifest';
+import { ExtensionType, DriverType, PluginType } from '.';
+
+export type InstallType = 'npm' | 'git' | 'local' | 'github';
+
+export interface InternalMetadata {
+  pkgName: string;
+  version: string;
+  installType: InstallType;
+  /**
+   * Whatever the user typed as the extension to install. May be derived from `package.json`
+   */
+  installSpec: string;
+}
+
+/**
+ * Combination of external + internal extension data with `driverName`/`pluginName` removed (it becomes a key in an {@linkcode ExtRecord} object).
+ * Part of `extensions.yaml`.
+ */
+export type ExtManifest<ExtType extends ExtensionType> = Omit<
+  ExtMetadata<ExtType>,
+  ExtType extends DriverType
+    ? 'driverName'
+    : ExtType extends PluginType
+    ? 'pluginName'
+    : never
+> &
+  InternalMetadata &
+  CommonMetadata; // XXX: ExtMetadata should be a union with CommonMetadata. why is this needed?
+
+type WithSchemaManifest = {
+  schema: SchemaMetadata;
+};
+
+/**
+ * This is just a {@linkcode ExtManifest} except it _for sure_ has a `schema` prop.
+ */
+export type ExtManifestWithSchema<ExtType extends ExtensionType> =
+  ExtManifest<ExtType> & WithSchemaManifest;
+
+/**
+ * Generic type for an object keyed by extension name, with values of type {@linkcode ExtData}
+ */
+export type ExtRecord<ExtType extends ExtensionType> = Record<
+  string,
+  ExtManifest<ExtType>
+>;
+
+export type DriverRecord = ExtRecord<DriverType>;
+export type PluginRecord = ExtRecord<PluginType>;
+
+export type ExtName<ExtType extends ExtensionType> = keyof ExtRecord<ExtType>;
+
+/**
+ * Represents an entire YAML manifest (`extensions.yaml`)
+ */
+export interface ManifestData {
+  drivers: DriverRecord;
+  plugins: PluginRecord;
+  schemaRev?: number;
+}

package/types/cli.d.ts

@@ -0,0 +1,134 @@
+import { DriverOpts } from '@appium/types';
+import {
+  DRIVER_TYPE as DRIVER_SUBCOMMAND,
+  EXT_SUBCOMMAND_INSTALL,
+  EXT_SUBCOMMAND_LIST,
+  EXT_SUBCOMMAND_RUN,
+  EXT_SUBCOMMAND_UNINSTALL,
+  EXT_SUBCOMMAND_UPDATE,
+  PLUGIN_TYPE as PLUGIN_SUBCOMMAND,
+  SERVER_SUBCOMMAND,
+} from '../lib/constants';
+
+/**
+ * Possible subcommands for the `appium` CLI.
+ */
+type CliSubcommand =
+  | typeof SERVER_SUBCOMMAND
+  | typeof DRIVER_SUBCOMMAND
+  | typeof PLUGIN_SUBCOMMAND;
+
+/**
+ * Possible subcommands of {@link DRIVER_SUBCOMMAND} or
+ * {@link PLUGIN_SUBCOMMAND}.
+ */
+export type CliExtensionSubcommand =
+  | typeof EXT_SUBCOMMAND_INSTALL
+  | typeof EXT_SUBCOMMAND_LIST
+  | typeof EXT_SUBCOMMAND_RUN
+  | typeof EXT_SUBCOMMAND_UPDATE
+  | typeof EXT_SUBCOMMAND_UNINSTALL;
+
+/**
+ * Random stuff that may appear in the parsed args which has no equivalent in a
+ * config file.
+ */
+interface MoreArgs {
+  /**
+   * Path to config file, if any. Does not make sense for this to be allowed in a config file!
+   */
+  configFile?: string;
+
+  /**
+   * If true, show the config and exit
+   */
+  showConfig?: boolean;
+
+  /**
+   * If true, open a REPL
+   */
+  shell?: boolean;
+}
+
+/**
+ * These arguments are _not_ supported by the CLI, but only via programmatic usage / tests.
+ */
+interface ProgrammaticArgs {
+  /**
+   * If `true`, throw on error instead of exit.
+   */
+  throwInsteadOfExit?: boolean;
+
+  /**
+   * Seems to only be used in tests or standalone driver calls
+   */
+  logHandler?: (...args: any[]) => void;
+
+  /**
+   * Alternate way to set `APPIUM_HOME` for tests. Since we don't want to muck about
+   * with the environment, we just set it here.
+   *
+   * Setting this means that any discovery of the proper `APPIUM_HOME` path is bypassed
+   * and is equivalent to setting `APPIUM_HOME` in the environment.
+   */
+  appiumHome?: string;
+
+  /**
+   * If true, show the {@link BuildInfo build info} and exit
+   */
+  showBuildInfo?: boolean;
+
+  /**
+   * If true, show config and exit
+   */
+  showConfig?: boolean;
+}
+
+/**
+ * These are args that Appium assigns while parsing the args.
+ */
+interface InternalArgs {
+  /**
+   * Subcommands of `driver` subcommand
+   */
+  driverCommand?: CliExtensionSubcommand;
+
+  /**
+   * Subcommands of `plugin` subcommand
+   */
+  pluginCommand?: CliExtensionSubcommand;
+
+  /**
+   * Possible subcommands
+   */
+  subcommand: CliSubcommand;
+}
+
+/**
+ * The same as {@link ParsedArgs} but with a nullable `subcommand`.
+ * This is _not_ the same as `Partial<ParsedArgs>`.
+ */
+export type PartialArgs = DriverOpts &
+  MoreArgs &
+  ProgrammaticArgs &
+  Partial<InternalArgs>;
+
+/**
+ * The Appium configuration as a flattened object, parsed via CLI args _and_ any
+ * CLI args unsupported by the config file.
+ * @todo Does not make any assumptions about property names derived from
+ * extensions.
+ */
+export type ParsedArgs = DriverOpts &
+  MoreArgs &
+  ProgrammaticArgs &
+  InternalArgs;
+
+/**
+ * Shown by `appium --build-info`
+ */
+export type BuildInfo = {
+  version: string;
+  'git-sha'?: string;
+  built?: string;
+};

package/types/extension.d.ts

@@ -0,0 +1,56 @@
+import { BaseDriverBase } from '@appium/base-driver/lib/basedriver/driver';
+import { Class, Driver, ExternalDriver } from '@appium/types';
+import { DriverType, ExtensionType, PluginType } from '.';
+
+export type DriverClass = BaseDriverBase<ExternalDriver, 
+  ExternalDriverStatic>;
+
+/**
+ * Additional static props for external driver classes
+ */
+interface ExternalDriverStatic {
+  driverName: string;
+}
+
+/**
+ * TODO: This should be derived from the base plugin.
+ */
+export type PluginClass = Class<PluginProto, ExternalPluginStatic>;
+
+/**
+ * Static props for plugin classes
+ */
+interface ExternalPluginStatic {
+  pluginName: string;
+}
+
+/**
+ * A plugin must have this shape.
+ * @todo Use base plugin instead of this
+ */
+interface PluginProto {
+  /**
+   * I'm not sure why `plugin.name` is required, but it is.
+   */
+  name: string;
+  /**
+   * Assigned by Appium; _not_ provided by implementor.
+   */
+  cliArgs?: Record<string, any>;
+  /**
+   * Don't know what this is, but it's also required.
+   */
+  onUnexpectedShutdown?: (
+    driver: Driver,
+    cause: Error | string,
+  ) => Promise<void>;
+}
+
+/**
+ * Generic to get at the class of an extension.
+ */
+export type ExtClass<ExtType extends ExtensionType> = ExtType extends DriverType
+  ? DriverClass
+  : ExtType extends PluginType
+  ? PluginClass
+  : never;

package/types/external-manifest.d.ts

@@ -0,0 +1,58 @@
+/**
+ * These types describe information about external extensions and the contents of their `package.json` files
+ */
+
+import { SchemaObject } from 'ajv';
+import { PackageJson, SetRequired } from 'type-fest';
+import { DriverType, ExtensionType, PluginType } from './index';
+
+/**
+ * This is what is allowed in the `appium.schema` prop of an extension's `package.json`.
+ */
+export type SchemaMetadata = string | (SchemaObject & {[key: number]: never});
+
+/**
+ * Manifest data shared by all extensions, as contained in `package.json`
+ */
+export interface CommonMetadata {
+  mainClass: string;
+  scripts?: Record<string, string>;
+  schema?: SchemaMetadata;
+}
+
+/**
+ * Driver-specific manifest data as contained in `package.json`
+ */
+export interface DriverMetadata {
+  automationName: string;
+  platformNames: string[];
+  driverName: string;
+}
+
+/**
+ * Plugin-specific manifest data as stored in `package.json`
+ */
+export interface PluginMetadata {
+  pluginName: string;
+}
+
+/**
+ * Generic type to refer to either {@linkcode DriverMetadata} or {@linkcode PluginMetadata}
+ * Corresponds to the `appium` prop in an extension's `package.json`.
+ */
+export type ExtMetadata<ExtType extends ExtensionType> =
+  (ExtType extends DriverType
+    ? DriverMetadata
+    : ExtType extends PluginType
+    ? PluginMetadata
+    : never) &
+    CommonMetadata;
+
+/**
+ * A `package.json` containing extension metadata.
+ * Required fields are `name`, `version`, and `appium`.
+ */
+export type ExtPackageJson<ExtType extends ExtensionType> = SetRequired<
+  PackageJson,
+  'name' | 'version'
+> & {appium: ExtMetadata<ExtType>};

package/types/index.d.ts

@@ -0,0 +1,7 @@
+export * from './appium-manifest';
+export * from './external-manifest';
+export * from './extension';
+export * from './cli';
+export type DriverType = 'driver';
+export type PluginType = 'plugin';
+export type ExtensionType = DriverType | PluginType;