appium 2.0.0-beta.30 → 2.0.0-beta.35

package/build/types/cli.d.ts

@@ -0,0 +1,112 @@
+import { ServerArgs } from '@appium/types';
+import type { 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';
+export declare type ServerSubcommand = typeof SERVER_SUBCOMMAND;
+export declare type DriverSubcommand = typeof DRIVER_SUBCOMMAND;
+export declare type PluginSubcommand = typeof PLUGIN_SUBCOMMAND;
+/**
+ * Possible subcommands for the `appium` CLI.
+ */
+export declare type CliSubcommand = ServerSubcommand | DriverSubcommand | PluginSubcommand;
+/**
+ * Possible subcommands of {@linkcode DriverSubcommand} or
+ * {@linkcode PluginSubcommand}.
+ */
+export declare 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.
+ */
+export interface MoreArgs {
+    /**
+     * Possible subcommands. If empty, defaults to {@linkcode ServerSubcommand}.
+     */
+    subcommand?: CliSubcommand;
+    /**
+     * 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.
+ */
+export 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 which the user will specify if using an extension command
+ */
+export interface ExtArgs extends WithExtSubcommand {
+    /**
+     * Subcommands of `driver` subcommand
+     */
+    driverCommand?: CliExtensionSubcommand;
+    /**
+     * Subcommands of `plugin` subcommand
+     */
+    pluginCommand?: CliExtensionSubcommand;
+}
+/**
+ * Args having the `server` subcommand
+ */
+export interface WithServerSubcommand {
+    subcommand?: ServerSubcommand;
+}
+/**
+ * Args having the `driver` or `plugin` subcommand
+ */
+export interface WithExtSubcommand {
+    subcommand: DriverSubcommand | PluginSubcommand;
+}
+/**
+ * Some generic bits of arguments; should not be used outside this declaration
+ */
+declare type CommonArgs<SArgs, T = WithServerSubcommand> = MoreArgs & ProgrammaticArgs & (T extends WithServerSubcommand ? SArgs : T extends WithExtSubcommand ? ExtArgs : never);
+/**
+ * Fully-parsed arguments, containing defaults, computed args, and config file values.
+ */
+export declare type ParsedArgs<T = WithServerSubcommand> = CommonArgs<ServerArgs, T>;
+/**
+ * Partial arguments, as supplied by a user. _May_ have defaults applied; _may_ contain config values; _may_ contain computed args.
+ */
+export declare type Args<T = WithServerSubcommand> = CommonArgs<Partial<ServerArgs>, T>;
+/**
+ * Shown by `appium --build-info`
+ */
+export declare type BuildInfo = {
+    version: string;
+    'git-sha'?: string;
+    built?: string;
+};
+export {};
+//# sourceMappingURL=cli.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../types/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,UAAU,EAAC,MAAM,eAAe,CAAC;AACzC,OAAO,KAAK,EACV,WAAW,IAAI,iBAAiB,EAChC,sBAAsB,EACtB,mBAAmB,EACnB,kBAAkB,EAClB,wBAAwB,EACxB,qBAAqB,EACrB,WAAW,IAAI,iBAAiB,EAChC,iBAAiB,EAClB,MAAM,kBAAkB,CAAC;AAE1B,oBAAY,gBAAgB,GAAG,OAAO,iBAAiB,CAAC;AACxD,oBAAY,gBAAgB,GAAG,OAAO,iBAAiB,CAAC;AACxD,oBAAY,gBAAgB,GAAG,OAAO,iBAAiB,CAAC;AAExD;;GAEG;AACH,oBAAY,aAAa,GACrB,gBAAgB,GAChB,gBAAgB,GAChB,gBAAgB,CAAC;AAErB;;;GAGG;AACH,oBAAY,sBAAsB,GAC9B,OAAO,sBAAsB,GAC7B,OAAO,mBAAmB,GAC1B,OAAO,kBAAkB,GACzB,OAAO,qBAAqB,GAC5B,OAAO,wBAAwB,CAAC;AAEpC;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB;;OAEG;IACH,UAAU,CAAC,EAAE,aAAa,CAAC;IAE3B;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;OAEG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAE7B;;OAEG;IACH,UAAU,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;IAEtC;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;OAEG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,OAAQ,SAAQ,iBAAiB;IAChD;;OAEG;IACH,aAAa,CAAC,EAAE,sBAAsB,CAAC;IAEvC;;OAEG;IACH,aAAa,CAAC,EAAE,sBAAsB,CAAC;CACxC;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,UAAU,CAAC,EAAE,gBAAgB,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,gBAAgB,GAAG,gBAAgB,CAAC;CACjD;AAED;;GAEG;AACH,aAAK,UAAU,CAAC,KAAK,EAAE,CAAC,GAAG,oBAAoB,IAAI,QAAQ,GACzD,gBAAgB,GAChB,CAAC,CAAC,SAAS,oBAAoB,GAC3B,KAAK,GACL,CAAC,SAAS,iBAAiB,GAC3B,OAAO,GACP,KAAK,CAAC,CAAC;AAEb;;GAEG;AACH,oBAAY,UAAU,CAAC,CAAC,GAAG,oBAAoB,IAAI,UAAU,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC;AAE7E;;GAEG;AACH,oBAAY,IAAI,CAAC,CAAC,GAAG,oBAAoB,IAAI,UAAU,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC;AAEhF;;GAEG;AACH,oBAAY,SAAS,GAAG;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC"}

package/build/types/extension.d.ts

@@ -0,0 +1,43 @@
+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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,47 @@
+/**
+ * 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';
+/**
+ * This is what is allowed in the `appium.schema` prop of an extension's `package.json`.
+ */
+export declare 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 declare 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 declare type ExtPackageJson<ExtType extends ExtensionType> = SetRequired<PackageJson, 'name' | 'version'> & {
+    appium: ExtMetadata<ExtType>;
+};
+//# sourceMappingURL=external-manifest.d.ts.map

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

@@ -0,0 +1 @@
+{"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"}

package/build/types/index.d.ts

@@ -0,0 +1,15 @@
+/// <reference types="node" />
+export * from './appium-manifest';
+export * from './external-manifest';
+export * from './extension';
+export * from './cli';
+export declare type DriverType = 'driver';
+export declare type PluginType = 'plugin';
+export declare type ExtensionType = DriverType | PluginType;
+/**
+ * Known environment variables concerning Appium
+ */
+export interface AppiumEnv extends NodeJS.ProcessEnv {
+    APPIUM_HOME?: string;
+}
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../types/index.ts"],"names":[],"mappings":";AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,aAAa,CAAC;AAC5B,cAAc,OAAO,CAAC;AACtB,oBAAY,UAAU,GAAG,QAAQ,CAAC;AAClC,oBAAY,UAAU,GAAG,QAAQ,CAAC;AAClC,oBAAY,aAAa,GAAG,UAAU,GAAG,UAAU,CAAC;AAEpD;;GAEG;AACH,MAAM,WAAW,SAAU,SAAQ,MAAM,CAAC,UAAU;IAClD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB"}

package/lib/appium.js

@@ -274,10 +274,14 @@ class AppiumDriver extends DriverCore {
       // the driver so that they cannot be mimicked by a malicious user sending in capabilities
       this.assignCliArgsToExtension('driver', driverName, driverInstance);
 
-
       // This assignment is required for correct web sockets functionality inside the driver
       // Drivers/plugins might also want to know where they are hosted
-      driverInstance.assignServer(this.server, this.args.address, this.args.port, this.args.basePath);
+
+      // XXX: temporary hack to work around #16747
+      driverInstance.server = this.server;
+      driverInstance.serverHost = this.args.address;
+      driverInstance.serverPort = this.args.port;
+      driverInstance.serverPath = this.args.basePath;
 
       try {
         runningDriversData = await this.curSessionDataForDriver(InnerDriver) ?? [];
@@ -737,7 +741,7 @@ export { AppiumDriver };
  * @typedef {import('@appium/types').ExternalDriver} ExternalDriver
  * @typedef {import('@appium/types').W3CCapabilities} W3CCapabilities
  * @typedef {import('@appium/types').DriverData} DriverData
- * @typedef {import('@appium/types').DriverOpts} DriverOpts
+ * @typedef {import('@appium/types').ServerArgs} DriverOpts
  * @typedef {import('@appium/types').Constraints} Constraints
  * @typedef {import('@appium/types').AppiumServer} AppiumServer
  * @typedef {import('../types').ExtensionType} ExtensionType

package/lib/cli/driver-command.js

@@ -1,14 +1,19 @@
 import _ from 'lodash';
 import ExtensionCommand from './extension-command';
-import { KNOWN_DRIVERS } from '../constants';
+import {KNOWN_DRIVERS} from '../constants';
 import '@colors/colors';
 
-const REQ_DRIVER_FIELDS = ['driverName', 'automationName', 'platformNames', 'mainClass'];
+const REQ_DRIVER_FIELDS = [
+  'driverName',
+  'automationName',
+  'platformNames',
+  'mainClass',
+];
+
 /**
- * @extends {ExtensionCommand<import('../extension/manifest').DriverType>}
+ * @extends {ExtensionCommand<DriverType>}
  */
 export default class DriverCommand extends ExtensionCommand {
-
   /**
    * @param {DriverCommandOptions} opts
    */
@@ -18,43 +23,63 @@ export default class DriverCommand extends ExtensionCommand {
   }
 
   async install ({driver, installType, packageName}) {
-    return await super._install({ext: driver, installType, packageName});
+    return await super._install({
+      installSpec: driver,
+      installType,
+      packageName,
+    });
   }
 
   async uninstall ({driver}) {
-    return await super._uninstall({ext: driver});
+    return await super._uninstall({installSpec: driver});
   }
 
   async update ({driver, unsafe}) {
-    return await super._update({ext: driver, unsafe});
+    return await super._update({installSpec: driver, unsafe});
   }
 
   async run ({driver, scriptName}) {
-    return await super._run({ext: driver, scriptName});
+    return await super._run({installSpec: driver, scriptName});
   }
 
   getPostInstallText ({extName, extData}) {
-    return `Driver ${extName}@${extData.version} successfully installed\n`.green +
-           `- automationName: ${extData.automationName.green}\n` +
-           `- platformNames: ${JSON.stringify(extData.platformNames).green}`;
+    return (
+      `Driver ${extName}@${extData.version} successfully installed\n`.green +
+      `- automationName: ${extData.automationName.green}\n` +
+      `- platformNames: ${JSON.stringify(extData.platformNames).green}`
+    );
   }
 
-  validateExtensionFields (appiumPkgData) {
-    const missingFields = REQ_DRIVER_FIELDS.reduce((acc, field) => (
-      appiumPkgData[field] ? acc : [...acc, field]
-    ), []);
+  /**
+   * Validates fields in `appium` field of `driverMetadata`
+   *
+   * For any `package.json` fields which a driver requires, validate the type of
+   * those fields on the `package.json` data, throwing an error if anything is
+   * amiss.
+   * @param {import('appium/types').ExtMetadata<DriverType>} driverMetadata
+   * @param {string} installSpec
+   */
+  validateExtensionFields (driverMetadata, installSpec) {
+    const missingFields = REQ_DRIVER_FIELDS.reduce(
+      (acc, field) => (driverMetadata[field] ? acc : [...acc, field]),
+      []
+    );
 
     if (!_.isEmpty(missingFields)) {
-      throw new Error(`Installed driver did not expose correct fields for compability ` +
-                      `with Appium. Missing fields: ${JSON.stringify(missingFields)}`);
+      throw new Error(
+        `Driver "${installSpec}" did not expose correct fields for compability ` +
+          `with Appium. Missing fields: ${JSON.stringify(missingFields)}`
+      );
     }
-
   }
-
 }
 
 /**
  * @typedef DriverCommandOptions
- * @property {import('../extension/extension-config').ExtensionConfig<import('../extension/manifest').DriverType>} config
+ * @property {import('../extension/extension-config').ExtensionConfig<DriverType>} config
  * @property {boolean} json
  */
+
+/**
+ * @typedef {import('appium/types').DriverType} DriverType
+ */