appium 2.0.0-beta.25 → 2.0.0-beta.28

package/lib/utils.js

@@ -1,10 +1,7 @@
-// @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';
@@ -36,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;
@@ -94,7 +94,7 @@ function parseCapsForInnerDriver (jsonwpCapabilities, w3cCapabilities, constrain
       }
     }
     if (hasJSONWPCaps) {
-      jsonwpCapabilities = Object.assign({}, removeAppiumPrefixes(defaultCapabilities), jsonwpCapabilities);
+      jsonwpCapabilities = {...removeAppiumPrefixes(defaultCapabilities), ...jsonwpCapabilities};
     }
   }
 
@@ -111,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`
@@ -127,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)
@@ -159,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;
@@ -215,36 +222,32 @@ function pullSettings (caps) {
   return result;
 }
 
-const rootDir = fs.findRoot(__dirname);
-
+export {
+  inspect, parseCapsForInnerDriver, insertAppiumPrefixes,
+  getPackageVersion, pullSettings, removeAppiumPrefixes
+};
 
 /**
- * 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>}
+ * @todo protocol is more specific
+ * @typedef ParsedDriverCaps
+ * @property {Capabilities} desiredCaps
+ * @property {string} protocol
+ * @property {any} [processedJsonwpCapabilities]
+ * @property {W3CCapabilities} [processedW3CCapabilities]
  */
-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 () {
-    return false;
-  }
-
-  clear () {
-    throw new Error(`Cannot clear ReadonlyMap`);
-  }
-}
+/**
+ * @todo protocol is more specific
+ * @typedef InvalidCaps
+ * @property {Error} error
+ * @property {string} protocol
+ * @property {Capabilities} [desiredCaps]
+ * @property {any} [processedJsonwpCapabilities]
+ * @property {W3CCapabilities} [processedW3CCapabilities]
+ */
 
-export {
-  inspect, parseCapsForInnerDriver, insertAppiumPrefixes, rootDir,
-  getPackageVersion, pullSettings, removeAppiumPrefixes, ReadonlyMap
-};
+/**
+ * @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.25",
+  "version": "2.0.0-beta.28",
   "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,49 @@
     "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 --out-dir=build/lib",
+    "dev": "npm run build -- --watch",
+    "fix": "npm run lint -- --fix",
+    "generate-docs": "node ./scripts/parse-yml-commands.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.4",
-    "@appium/base-plugin": "1.8.0",
-    "@appium/support": "^2.55.4",
-    "@babel/runtime": "7.16.3",
-    "@sidvind/better-ajv-errors": "0.9.2",
-    "ajv": "8.8.2",
+    "@appium/base-driver": "^8.4.0",
+    "@appium/base-plugin": "1.8.1",
+    "@appium/schema": "^0.0.1",
+    "@appium/support": "^2.57.0",
+    "@babel/runtime": "7.17.9",
+    "@sidvind/better-ajv-errors": "1.1.1",
+    "ajv": "8.11.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",
+    "lilconfig": "2.0.5",
     "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",
+    "semver": "7.3.6",
     "source-map-support": "0.5.21",
     "teen_process": "1.16.0",
-    "winston": "3.3.3",
+    "winston": "3.7.2",
     "word-wrap": "1.2.3",
     "yaml": "1.10.2"
   },
@@ -78,6 +84,6 @@
     "access": "public",
     "tag": "next"
   },
-  "homepage": "https://appium.io",
-  "gitHead": "42f4a2de2d763d57cf0bdb6fb6c9a3bc9c3d232f"
+  "types": "./build/lib/index.d.ts",
+  "gitHead": "3ec3a0efa590e22e264ffbd23316ee5714a12081"
 }

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})`);

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;

package/bin/ios-webkit-debug-proxy-launcher.js

@@ -1,71 +0,0 @@
-#!/usr/bin/env node
-
-/* eslint no-console:0 */
-
-/*
- * Small tool, launching and monitoring ios-web-kit-proxy, and relaunching
- * on predefined errors.
- *
- * Usage:
- *  ./bin/ios-webkit-debug-proxy-launcher.js [args]
- *  args: ios-webkit-debug-proxy args (they will be passed over)
- *
- * Example:
- *  ./bin/ios-webkit-debug-proxy-launcher.js -c <UDID>:27753 -d
- *
- *  Note:
- *   For iOS8.1 try this first:
- *     brew install --HEAD ideviceinstaller
- */
-
-'use strict';
-
-const spawn = require('child_process').spawn;
-const _ = require('lodash');
-
-const args = process.argv.slice(2);
-
-const RESTART_ON_MESSAGES = [
-  'Invalid message _rpc_applicationUpdated',
-  'Invalid message _rpc_applicationSentListing'];
-
-const PROXY_CMD = 'ios_webkit_debug_proxy';
-let proxy;
-
-const handleKillProcess = function (exitCode) {
-  console.log('\nKilling proxy process!');
-  proxy.kill('SIGTERM');
-  process.exit((exitCode || 0));
-};
-
-const startProxy = function () {
-  console.log(`RUNNING: ${PROXY_CMD} ${args.join(' ')}`);
-
-  proxy = spawn(PROXY_CMD, args);
-
-  proxy.stdout.on('data', function onStdout (data) {
-    console.log(`stdout: ${data}`);
-  });
-
-  proxy.stderr.on('data', function onStderr (data) {
-    console.log(`stderr: ${data}`);
-    const restartMessage = _(RESTART_ON_MESSAGES).find(function findMessage (message) {
-      return ('' + data).indexOf(message) >= 0;
-    });
-    if (restartMessage) {
-      console.log(`Detected error message: ${restartMessage}`);
-      console.log('Killing proxy!');
-      proxy.kill('SIGTERM');
-      process.nextTick(startProxy);
-    }
-  });
-
-  proxy.on('close', function onClose (code) {
-    console.log(`Child process exited with code ${code}`);
-  });
-};
-
-process.on('SIGINT', handleKillProcess);
-process.on('SIGTERM', handleKillProcess);
-
-startProxy();