appium 2.0.0-beta.34 → 2.0.0-beta.38

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appium",
-  "version": "2.0.0-beta.34",
+  "version": "2.0.0-beta.38",
   "description": "Automation for Apps.",
   "keywords": [
     "automation",
@@ -23,6 +23,7 @@
   },
   "license": "Apache-2.0",
   "author": "https://github.com/appium",
+  "types": "./build/lib/main.d.ts",
   "bin": {
     "appium": "index.js"
   },
@@ -33,33 +34,39 @@
     "lib",
     "build",
     "index.js",
-    "scripts/postinstall.js",
+    "driver.*",
+    "support.*",
+    "plugin.*",
+    "test.*",
+    "scripts/autoinstall-extensions.js",
     "types"
   ],
   "scripts": {
     "build": "babel lib --root-mode=upward --out-dir=build/lib",
-    "dev": "npm run build -- --watch",
-    "fix": "npm run lint -- --fix",
     "build:docs": "node docs/scripts/build-docs.js",
     "build:docs:assets": "node docs/scripts/copy-assets.js",
+    "dev": "npm run build -- --watch",
     "dev:docs": "npm run build:docs:assets && npm run dev:docs:en",
     "dev:docs:en": "mkdocs serve -f ./docs/mkdocs-en.yml",
     "dev:docs:ja": "mkdocs serve -f ./docs/mkdocs-ja.yml",
-    "publish:docs": "APPIUM_DOCS_PUBLISH=1 npm run build:docs",
-    "postinstall": "node ./scripts/postinstall.js",
+    "fix": "npm run lint -- --fix",
+    "postinstall": "node ./scripts/autoinstall-extensions.js",
     "lint": "eslint -c ../../.eslintrc --ignore-path ../../.eslintignore .",
+    "prepare": "npm run build",
+    "publish:docs": "APPIUM_DOCS_PUBLISH=1 npm run build:docs",
     "test": "npm run test:unit",
-    "test:e2e": "mocha --timeout 30s --slow 15s \"./test/e2e/**/*.spec.js\"",
+    "test:e2e": "mocha --timeout 75s --slow 30s \"./test/e2e/**/*.spec.js\"",
     "test:unit": "mocha \"./test/unit/**/*.spec.js\""
   },
   "dependencies": {
-    "@appium/base-driver": "^8.5.3",
-    "@appium/base-plugin": "^1.8.5",
-    "@appium/docutils": "^0.0.4",
-    "@appium/schema": "^0.0.5",
-    "@appium/support": "^2.58.0",
-    "@babel/runtime": "7.17.9",
-    "@sidvind/better-ajv-errors": "1.1.1",
+    "@appium/base-driver": "^8.5.5",
+    "@appium/base-plugin": "^1.9.1",
+    "@appium/docutils": "^0.0.6",
+    "@appium/schema": "^0.0.7",
+    "@appium/support": "^2.59.1",
+    "@appium/test-support": "^1.3.21",
+    "@babel/runtime": "7.18.3",
+    "@sidvind/better-ajv-errors": "2.0.0",
     "ajv": "8.11.0",
     "ajv-formats": "2.1.1",
     "argparse": "2.0.1",
@@ -77,19 +84,19 @@
     "resolve-from": "5.0.0",
     "semver": "7.3.7",
     "source-map-support": "0.5.21",
+    "supports-color": "8.1.1",
     "teen_process": "1.16.0",
     "winston": "3.7.2",
     "word-wrap": "1.2.3",
-    "yaml": "2.0.1"
+    "yaml": "2.1.1"
   },
   "engines": {
-    "node": ">=12",
+    "node": ">=14",
     "npm": ">=6"
   },
   "publishConfig": {
     "access": "public",
     "tag": "next"
   },
-  "types": "./build/lib/main.d.ts",
-  "gitHead": "5482c921bc187ed8807922c00bd2355585f4971a"
+  "gitHead": "ed2002d90de0b103c35b2feeeeef97f060141a86"
 }

package/plugin.d.ts

@@ -0,0 +1 @@
+export * from '@appium/base-plugin';

package/plugin.js

@@ -0,0 +1,13 @@
+'use strict';
+
+// @ts-check
+
+/**
+ * This module is here to re-export `@appium/base-plugin` for Appium extensions.
+ *
+ * @see https://npm.im/@appium/base-plugin
+ * @example
+ * const { BasePlugin } = require('appium/plugin');
+ */
+
+module.exports = require('@appium/base-plugin');

package/scripts/autoinstall-extensions.js

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+
+/* eslint-disable no-console, promise/prefer-await-to-then */
+
+/**
+ * This script is intended to be run as a `postinstall` lifecycle script,
+ * and will automatically install extensions if requested by the user.
+ *
+ * If the current working directory is within a project which has `appium`
+ * as a dependency, this script does nothing; extensions must be managed
+ * via `npm` or another package manager.
+ *
+ * If `CI=1` is in the environment, this script will exit with a non-zero
+ * code upon failure (which will typically break a build).  Otherwise, it
+ * will always exit with code 0, even if errors occur.
+ *
+ * @example
+ * `npm install -g appium --drivers=uiautomator2,xcuitest --plugins=images`
+ */
+
+/** @type {import('../lib/cli/extension').runExtensionCommand} */
+let runExtensionCommand;
+/** @type {import('../lib/constants').DRIVER_TYPE} */
+let DRIVER_TYPE;
+/** @type {import('../lib/constants').PLUGIN_TYPE} */
+let PLUGIN_TYPE;
+/** @type {import('../lib/extension').loadExtensions} */
+let loadExtensions;
+
+const {env, util, logger} = require('@appium/support');
+
+const ora = require('ora');
+
+const log = (message) => {
+  console.error(`[Appium] ${message}`);
+};
+
+const spinner = ora({
+  text: 'Checking Appium installation...',
+  prefixText: '[Appium]',
+}).start();
+
+try {
+  ({runExtensionCommand} = require('../build/lib/cli/extension'));
+  ({DRIVER_TYPE, PLUGIN_TYPE} = require('../build/lib/constants'));
+  ({loadExtensions} = require('../build/lib/extension'));
+  spinner.succeed('Appium installation OK');
+  // suppress logs from Appium, which mess up the script output
+  logger.getLogger('Appium').level = 'error';
+} catch (e) {
+  spinner.fail(`Could not load required module(s); has Appium been built? (${e.message})`);
+  if (process.env.CI) {
+    console.error('Detected CI environment, exiting with code 1');
+    process.exitCode = 1;
+  } else {
+    process.exitCode = 0;
+  }
+  process.exit();
+}
+
+async function main() {
+  if (await env.hasAppiumDependency()) {
+    log(`Found local Appium installation; skipping automatic installation of extensions.`);
+    return;
+  }
+
+  const driverEnv = process.env.npm_config_drivers;
+  const pluginEnv = process.env.npm_config_plugins;
+
+  const spinner = ora({
+    text: 'Looking for extensions to automatically install...',
+    prefixText: '[Appium]',
+  }).start();
+
+  if (!driverEnv && !pluginEnv) {
+    spinner.succeed(
+      'No drivers or plugins to automatically install. If desired, provide arguments with comma-separated values "--drivers=<known_driver>[,known_driver...]" and/or "--plugins=<known_plugin>[,known_plugin...]" to the "npm install appium" command. The specified extensions will be installed automatically with Appium.  Note: to see the list of known extensions, run "appium <driver|plugin> list".'
+    );
+    return;
+  }
+
+  const specs = [
+    [DRIVER_TYPE, driverEnv],
+    [PLUGIN_TYPE, pluginEnv],
+  ];
+
+  spinner.start('Resolving Appium home directory...');
+  const appiumHome = await env.resolveAppiumHome();
+  spinner.succeed(`Found Appium home: ${appiumHome}`);
+
+  spinner.start(`Loading extension data...`);
+  const {driverConfig, pluginConfig} = await loadExtensions(appiumHome);
+  spinner.succeed(`Loaded extension data.`);
+
+  const installedStats = {[DRIVER_TYPE]: 0, [PLUGIN_TYPE]: 0};
+  for (const [type, extEnv] of specs) {
+    if (extEnv) {
+      for await (let ext of extEnv.split(',')) {
+        ext = ext.trim();
+        try {
+          await checkAndInstallExtension({
+            runExtensionCommand,
+            appiumHome,
+            type,
+            ext,
+            driverConfig,
+            pluginConfig,
+            spinner,
+          });
+          installedStats[type]++;
+        } catch (e) {
+          spinner.fail(`Could not install ${type} "${ext}": ${e.message}`);
+          if (process.env.CI) {
+            process.exitCode = 1;
+          }
+          return;
+        }
+      }
+    }
+  }
+  spinner.succeed(
+    `Done. ${installedStats[DRIVER_TYPE]} ${util.pluralize(
+      'driver',
+      installedStats[DRIVER_TYPE]
+    )} and ${installedStats[PLUGIN_TYPE]} ${util.pluralize(
+      'plugin',
+      installedStats[PLUGIN_TYPE]
+    )} are installed.`
+  );
+}
+
+async function checkAndInstallExtension({
+  runExtensionCommand,
+  appiumHome,
+  type,
+  ext,
+  driverConfig,
+  pluginConfig,
+  spinner,
+}) {
+  const extList = await runExtensionCommand(
+    {
+      appiumHome,
+      [`${type}Command`]: 'list',
+      showInstalled: true,
+      suppressOutput: true,
+    },
+    type === DRIVER_TYPE ? driverConfig : pluginConfig
+  );
+  if (extList[ext]) {
+    spinner.info(`The ${type} "${ext}" is already installed.`);
+    return;
+  }
+  spinner.start(`Installing ${type} "${ext}"...`);
+  await runExtensionCommand(
+    {
+      appiumHome,
+      [`${type}Command`]: 'install',
+      suppressOutput: true,
+      [type]: ext,
+    },
+    type === DRIVER_TYPE ? driverConfig : pluginConfig
+  );
+  spinner.succeed(`Installed ${type} "${ext}".`);
+}
+
+if (require.main === module) {
+  main().catch((e) => {
+    log(e);
+    if (process.env.CI) {
+      log('Detected CI environment, exiting with code 1');
+      process.exitCode = 1;
+    }
+  });
+}
+
+module.exports = main;

package/support.d.ts

@@ -0,0 +1 @@
+export * from '@appium/support';

package/support.js

@@ -0,0 +1,13 @@
+'use strict';
+
+// @ts-check
+
+/**
+ * This module is here to re-export `@appium/support` for Appium extensions.
+ *
+ * @see https://npm.im/@appium/support
+ * @example
+ * const { fs, npm } = require('appium/support');
+ */
+
+module.exports = require('@appium/support');

package/types/appium-manifest.ts

@@ -1,16 +1,35 @@
-import { CommonMetadata, ExtMetadata, SchemaMetadata } from './external-manifest';
-import { ExtensionType, DriverType, PluginType } from '.';
+import {CommonExtMetadata, ExtMetadata, ExtSchemaMetadata} from './extension-manifest';
+import {ExtensionType, DriverType, PluginType} from '@appium/types';
 
 export type InstallType = 'npm' | 'git' | 'local' | 'github';
 
 export interface InternalMetadata {
+  /**
+   * Package name of extension
+   *
+   * `name` from its `package.json`
+   */
   pkgName: string;
+  /**
+   * Version of extension
+   *
+   * `version` from its `package.json`
+   */
   version: string;
+  /**
+   * The method in which the user installed the extension (the `source` CLI arg)
+   */
   installType: InstallType;
   /**
    * Whatever the user typed as the extension to install. May be derived from `package.json`
    */
   installSpec: string;
+  /**
+   * Maximum version of Appium that this extension is compatible with.
+   *
+   * If `undefined`, we'll try anyway.
+   */
+  appiumVersion?: string;
 }
 
 /**
@@ -19,32 +38,25 @@ export interface InternalMetadata {
  */
 export type ExtManifest<ExtType extends ExtensionType> = Omit<
   ExtMetadata<ExtType>,
-  ExtType extends DriverType
-    ? 'driverName'
-    : ExtType extends PluginType
-    ? 'pluginName'
-    : never
+  ExtType extends DriverType ? 'driverName' : ExtType extends PluginType ? 'pluginName' : never
 > &
   InternalMetadata &
-  CommonMetadata; // XXX: ExtMetadata should be a union with CommonMetadata. why is this needed?
+  CommonExtMetadata; // XXX: ExtMetadata should be a union with CommonMetadata. why is this needed?
 
 export type WithSchemaManifest = {
-  schema: SchemaMetadata;
+  schema: ExtSchemaMetadata;
 };
 
 /**
  * This is just a {@linkcode ExtManifest} except it _for sure_ has a `schema` prop.
  */
-export type ExtManifestWithSchema<ExtType extends ExtensionType> =
-  ExtManifest<ExtType> & WithSchemaManifest;
+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 ExtRecord<ExtType extends ExtensionType> = Record<string, ExtManifest<ExtType>>;
 
 export type DriverRecord = ExtRecord<DriverType>;
 export type PluginRecord = ExtRecord<PluginType>;

package/types/cli.ts

@@ -17,10 +17,7 @@ export type PluginSubcommand = typeof PLUGIN_SUBCOMMAND;
 /**
  * Possible subcommands for the `appium` CLI.
  */
-export type CliSubcommand =
-  | ServerSubcommand
-  | DriverSubcommand
-  | PluginSubcommand;
+export type CliSubcommand = ServerSubcommand | DriverSubcommand | PluginSubcommand;
 
 /**
  * Possible subcommands of {@linkcode DriverSubcommand} or
@@ -127,11 +124,7 @@ export interface WithExtSubcommand {
  */
 type CommonArgs<SArgs, T = WithServerSubcommand> = MoreArgs &
   ProgrammaticArgs &
-  (T extends WithServerSubcommand
-    ? SArgs
-    : T extends WithExtSubcommand
-    ? ExtArgs
-    : never);
+  (T extends WithServerSubcommand ? SArgs : T extends WithExtSubcommand ? ExtArgs : never);
 
 /**
  * Fully-parsed arguments, containing defaults, computed args, and config file values.

package/types/{external-manifest.ts → extension-manifest.ts}

@@ -2,22 +2,22 @@
  * These types describe information about external extensions and the contents of their `package.json` files
  */
 
-import type { SchemaObject } from 'ajv';
-import type { PackageJson, SetRequired } from 'type-fest';
-import { DriverType, ExtensionType, PluginType } from './index';
+import type {SchemaObject} from 'ajv';
+import type {PackageJson, SetRequired} from 'type-fest';
+import {DriverType, ExtensionType, PluginType} from '@appium/types';
 
 /**
  * This is what is allowed in the `appium.schema` prop of an extension's `package.json`.
  */
-export type SchemaMetadata = string | (SchemaObject & {[key: number]: never});
+export type ExtSchemaMetadata = string | (SchemaObject & {[key: number]: never});
 
 /**
  * Manifest data shared by all extensions, as contained in `package.json`
  */
-export interface CommonMetadata {
+export interface CommonExtMetadata {
   mainClass: string;
   scripts?: Record<string, string>;
-  schema?: SchemaMetadata;
+  schema?: ExtSchemaMetadata;
 }
 
 /**
@@ -40,19 +40,25 @@ export interface PluginMetadata {
  * 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;
+export type ExtMetadata<ExtType extends ExtensionType> = (ExtType extends DriverType
+  ? DriverMetadata
+  : ExtType extends PluginType
+  ? PluginMetadata
+  : never) &
+  CommonExtMetadata;
 
 /**
  * A `package.json` containing extension metadata.
- * Required fields are `name`, `version`, and `appium`.
+ * Must have the following properties:
+ * - `name`: the name of the extension
+ * - `version`: the version of the extension
+ * - `appium`: the metadata for the extension
+ * - `peerDependencies.appium`: the maximum compatible version of Appium
  */
 export type ExtPackageJson<ExtType extends ExtensionType> = SetRequired<
   PackageJson,
   'name' | 'version'
-> & {appium: ExtMetadata<ExtType>};
+> & {
+  appium: ExtMetadata<ExtType>;
+  peerDependencies: {appium: string; [key: string]: string};
+};

package/types/index.ts

@@ -1,10 +1,8 @@
+import {ExtensionType, DriverType, DriverClass, PluginType, PluginClass} from '@appium/types';
+
 export * from './appium-manifest';
-export * from './external-manifest';
-export * from './extension';
+export * from './extension-manifest';
 export * from './cli';
-export type DriverType = 'driver';
-export type PluginType = 'plugin';
-export type ExtensionType = DriverType | PluginType;
 
 /**
  * Known environment variables concerning Appium
@@ -12,3 +10,12 @@ export type ExtensionType = DriverType | PluginType;
 export interface AppiumEnv extends NodeJS.ProcessEnv {
   APPIUM_HOME?: string;
 }
+
+/**
+ * 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/build/types/extension.d.ts

@@ -1,43 +0,0 @@
-import type { BaseDriverBase } from '@appium/base-driver/lib/basedriver/driver';
-import { Class, Driver, ExternalDriver } from '@appium/types';
-import { DriverType, ExtensionType, PluginType } from '.';
-export declare type DriverClass = BaseDriverBase<ExternalDriver, ExternalDriverStatic>;
-/**
- * Additional static props for external driver classes
- */
-export interface ExternalDriverStatic {
-    driverName: string;
-}
-/**
- * TODO: This should be derived from the base plugin.
- */
-export declare type PluginClass = Class<PluginProto, ExternalPluginStatic>;
-/**
- * Static props for plugin classes
- */
-export interface ExternalPluginStatic {
-    pluginName: string;
-}
-/**
- * A plugin must have this shape.
- * @todo Use base plugin instead of this
- */
-export 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 declare type ExtClass<ExtType extends ExtensionType> = ExtType extends DriverType ? DriverClass : ExtType extends PluginType ? PluginClass : never;
-//# sourceMappingURL=extension.d.ts.map

package/build/types/extension.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"extension.d.ts","sourceRoot":"","sources":["../../types/extension.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2CAA2C,CAAC;AAChF,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC9D,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,GAAG,CAAC;AAE1D,oBAAY,WAAW,GAAG,cAAc,CAAC,cAAc,EACrD,oBAAoB,CAAC,CAAC;AAExB;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,oBAAY,WAAW,GAAG,KAAK,CAAC,WAAW,EAAE,oBAAoB,CAAC,CAAC;AAEnE;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC9B;;OAEG;IACH,oBAAoB,CAAC,EAAE,CACrB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,KAAK,GAAG,MAAM,KAClB,OAAO,CAAC,IAAI,CAAC,CAAC;CACpB;AAED;;GAEG;AACH,oBAAY,QAAQ,CAAC,OAAO,SAAS,aAAa,IAAI,OAAO,SAAS,UAAU,GAC5E,WAAW,GACX,OAAO,SAAS,UAAU,GAC1B,WAAW,GACX,KAAK,CAAC"}

package/build/types/external-manifest.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"external-manifest.d.ts","sourceRoot":"","sources":["../../types/external-manifest.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,KAAK,CAAC;AACxC,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC1D,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAEhE;;GAEG;AACH,oBAAY,cAAc,GAAG,MAAM,GAAG,CAAC,YAAY,GAAG;IAAC,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAA;CAAC,CAAC,CAAC;AAE9E;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,MAAM,CAAC,EAAE,cAAc,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,oBAAY,WAAW,CAAC,OAAO,SAAS,aAAa,IACnD,CAAC,OAAO,SAAS,UAAU,GACvB,cAAc,GACd,OAAO,SAAS,UAAU,GAC1B,cAAc,GACd,KAAK,CAAC,GACR,cAAc,CAAC;AAEnB;;;GAGG;AACH,oBAAY,cAAc,CAAC,OAAO,SAAS,aAAa,IAAI,WAAW,CACrE,WAAW,EACX,MAAM,GAAG,SAAS,CACnB,GAAG;IAAC,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,CAAA;CAAC,CAAC"}