appium 2.0.0-beta.57 → 2.0.0-beta.58

package/build/types/manifest/v4.d.ts

@@ -0,0 +1,139 @@
+import { DriverType, ExtensionType, PluginType } from '@appium/types';
+import { SchemaObject } from 'ajv';
+import { PackageJson, SetRequired } from 'type-fest';
+/**
+ * One of the possible extension installation stratgies
+ */
+export type InstallType = 'npm' | 'git' | 'local' | 'github' | 'dev';
+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;
+    /**
+     * Path to the extension's root directory
+     */
+    installPath: string;
+}
+/**
+ * Shape of the `appium.schema` property in an extension's `package.json` (if it exists)
+ */
+export type ExtSchemaMetadata = string | (SchemaObject & {
+    [key: number]: never;
+});
+/**
+ * Manifest data shared by all extensions, as contained in `package.json`
+ */
+export interface CommonExtMetadata {
+    /**
+     * The main class of the extension.
+     *
+     * The extension must export this class by name.
+     */
+    mainClass: string;
+    /**
+     * Lookup table of scripts to run via `appium <driver|plugin> run <script>` keyed by name.
+     */
+    scripts?: Record<string, string>;
+    /**
+     * Schema describing configuration options (and CLI args) for the extension.
+     *
+     * Can also just be a path (relative to the extension root) to an external JSON schema file.
+     */
+    schema?: ExtSchemaMetadata;
+}
+/**
+ * Driver-specific manifest data as stored in a driver's `package.json`
+ */
+export interface DriverMetadata {
+    /**
+     * Automation name of the driver
+     */
+    automationName: string;
+    /**
+     * Platforms the driver supports
+     */
+    platformNames: string[];
+    /**
+     * Short name of the driver (displayed in `appium list`, etc.)
+     */
+    driverName: string;
+}
+/**
+ * Plugin-specific manifest data as stored in a plugin's `package.json`
+ */
+export interface PluginMetadata {
+    /**
+     * Short name of the plugin (displayed in `appium list`, etc.)
+     */
+    pluginName: string;
+}
+/**
+ * Generic extension metadata as stored in the `appium` prop of an extension's `package.json`.
+ */
+export type ExtMetadata<ExtType extends ExtensionType> = (ExtType extends DriverType ? DriverMetadata : ExtType extends PluginType ? PluginMetadata : never) & CommonExtMetadata;
+/**
+ * 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>, 'driverName' | 'pluginName'> & InternalMetadata;
+/**
+ * Lookup of extension name to {@linkcode ExtManifest}.
+ * @see {ManifestData}
+ */
+export type ExtRecord<ExtType extends ExtensionType> = Record<string, ExtManifest<ExtType>>;
+/**
+ * The shape of the `extensions.yaml` file
+ */
+export interface ManifestData {
+    drivers: ExtRecord<DriverType>;
+    plugins: ExtRecord<PluginType>;
+    schemaRev: number;
+}
+/**
+ * The name of an installed extension, as it appears in `extensions.yaml`
+ * (as a property name under `drivers` or `plugins`)
+ */
+export type ExtName<ExtType extends ExtensionType> = keyof ExtRecord<ExtType>;
+/**
+ * A `package.json` containing extension metadata.
+ * 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>;
+    peerDependencies: {
+        appium: string;
+        [key: string]: string;
+    };
+};
+/**
+ * A transient format between installation and insertion of extension metadata into the manifest.
+ */
+export type ExtInstallReceipt<ExtType extends ExtensionType> = ExtMetadata<ExtType> & InternalMetadata;
+//# sourceMappingURL=v4.d.ts.map

package/build/types/manifest/v4.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"v4.d.ts","sourceRoot":"","sources":["../../../types/manifest/v4.ts"],"names":[],"mappings":"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"}

package/build/types/manifest/v4.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=v4.js.map

package/build/types/manifest/v4.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"v4.js","sourceRoot":"","sources":["../../../types/manifest/v4.ts"],"names":[],"mappings":""}

package/lib/appium.js

@@ -28,15 +28,12 @@ const desiredCapabilityConstraints = /** @type {const} */ ({
     isString: true,
   },
 });
-/**
- * @typedef {typeof desiredCapabilityConstraints} AppiumDriverConstraints
- */
 
 const sessionsListGuard = new AsyncLock();
 const pendingDriversGuard = new AsyncLock();
 
 /**
- * @implements {SessionHandler}
+ * @extends {DriverCore<AppiumDriverConstraints>}
  */
 class AppiumDriver extends DriverCore {
   /**
@@ -92,11 +89,11 @@ class AppiumDriver extends DriverCore {
    */
   desiredCapConstraints;
 
-  /** @type {DriverOpts} */
+  /** @type {import('@appium/types').DriverOpts<AppiumDriverConstraints>} */
   args;
 
   /**
-   * @param {DriverOpts} opts
+   * @param {import('@appium/types').DriverOpts<AppiumDriverConstraints>} opts
    */
   constructor(opts) {
     // It is necessary to set `--tmp` here since it should be set to
@@ -163,11 +160,10 @@ class AppiumDriver extends DriverCore {
     };
   }
 
-  // eslint-disable-next-line require-await
   async getSessions() {
     return _.toPairs(this.sessions).map(([id, driver]) => ({
       id,
-      capabilities: driver.caps,
+      capabilities: /** @type {import('@appium/types').DriverCaps} */ (driver.caps),
     }));
   }
 
@@ -224,12 +220,12 @@ class AppiumDriver extends DriverCore {
 
   /**
    * Create a new session
-   * @param {W3CCapabilities<AppiumDriverConstraints>} jsonwpCaps JSONWP formatted desired capabilities
-   * @param {W3CCapabilities<AppiumDriverConstraints>} reqCaps Required capabilities (JSONWP standard)
-   * @param {W3CCapabilities<AppiumDriverConstraints>} w3cCapabilities W3C capabilities
-   * @param {DriverData[]} [driverData]
+   * @param {W3CAppiumDriverCaps} jsonwpCaps JSONWP formatted desired capabilities
+   * @param {W3CAppiumDriverCaps} [reqCaps] Required capabilities (JSONWP standard)
+   * @param {W3CAppiumDriverCaps} [w3cCapabilities] W3C capabilities
+   * @returns {Promise<SessionHandlerCreateResult>}
    */
-  async createSession(jsonwpCaps, reqCaps, w3cCapabilities, driverData) {
+  async createSession(jsonwpCaps, reqCaps, w3cCapabilities) {
     const defaultCapabilities = _.cloneDeep(this.args.defaultCapabilities);
     const defaultSettings = pullSettings(defaultCapabilities);
     jsonwpCaps = _.cloneDeep(jsonwpCaps);
@@ -247,13 +243,14 @@ class AppiumDriver extends DriverCore {
       Object.assign(w3cSettings, pullSettings(firstMatchEntry));
     }
 
+    /** @type {string|undefined} */
     let protocol;
     let innerSessionId, dCaps;
     try {
       // Parse the caps into a format that the InnerDriver will accept
       const parsedCaps = parseCapsForInnerDriver(
         jsonwpCaps,
-        promoteAppiumOptions(w3cCapabilities),
+        promoteAppiumOptions(/** @type {W3CAppiumDriverCaps} */ (w3cCapabilities)),
         this.desiredCapConstraints,
         defaultCapabilities ? promoteAppiumOptionsForObject(defaultCapabilities) : undefined
       );
@@ -399,7 +396,7 @@ class AppiumDriver extends DriverCore {
 
   /**
    *
-   * @param {Driver} driver
+   * @param {ExternalDriver} driver
    * @param {string} innerSessionId
    */
   attachUnexpectedShutdownHandler(driver, innerSessionId) {
@@ -442,10 +439,11 @@ class AppiumDriver extends DriverCore {
 
   /**
    *
-   * @param {DriverClass} InnerDriver
+   * @param {((...args: any[]) => any)|(new(...args: any[]) => any)} InnerDriver
    * @returns {Promise<DriverData[]>}}
+   * @privateRemarks The _intent_ is that `InnerDriver` is the class of a driver, but it only really
+   * needs to be a function or constructor.
    */
-  // eslint-disable-next-line require-await
   async curSessionDataForDriver(InnerDriver) {
     const data = _.compact(
       _.values(this.sessions)
@@ -588,7 +586,7 @@ class AppiumDriver extends DriverCore {
    *
    * @param {string} cmd
    * @param  {...any} args
-   * @returns {Promise<{value: any, error?: Error, protocol: string} | import('type-fest').AsyncReturnType<Driver['executeCommand']>>}
+   * @returns {Promise<{value: any, error?: Error, protocol: string} | import('type-fest').AsyncReturnType<ExternalDriver['executeCommand']>>}
    */
   async executeCommand(cmd, ...args) {
     // We have basically three cases for how to handle commands:
@@ -618,6 +616,7 @@ class AppiumDriver extends DriverCore {
     let dstSession = null;
     let protocol = null;
     /** @type {this | ExternalDriver} */
+    // eslint-disable-next-line @typescript-eslint/no-this-alias
     let driver = this;
     if (isSessionCmd) {
       sessionId = _.last(args);
@@ -840,21 +839,38 @@ export class NoDriverProxyCommandError extends Error {
 export {AppiumDriver};
 
 /**
- * @typedef {import('@appium/types').ExternalDriver} ExternalDriver
- * @typedef {import('@appium/types').Driver} Driver
- * @typedef {import('@appium/types').DriverClass} DriverClass
  * @typedef {import('@appium/types').DriverData} DriverData
  * @typedef {import('@appium/types').ServerArgs} DriverOpts
  * @typedef {import('@appium/types').Constraints} Constraints
  * @typedef {import('@appium/types').AppiumServer} AppiumServer
  * @typedef {import('@appium/types').ExtensionType} ExtensionType
  * @typedef {import('./extension/driver-config').DriverConfig} DriverConfig
- * @typedef {import('@appium/types').Plugin} Plugin
- * @typedef {import('@appium/types').PluginClass} PluginClass
  * @typedef {import('@appium/types').PluginType} PluginType
  * @typedef {import('@appium/types').DriverType} DriverType
  * @typedef {import('@appium/types').StringRecord} StringRecord
- * @typedef {import('@appium/types').SessionHandler<SessionHandlerResult<any[]>,SessionHandlerResult<void>>} SessionHandler
+ * @typedef {import('@appium/types').ExternalDriver} ExternalDriver
+ * @typedef {import('@appium/types').PluginClass} PluginClass
+ * @typedef {import('@appium/types').Plugin} Plugin
+ * @typedef {import('@appium/types').DriverClass<import('@appium/types').Driver>} DriverClass
+ */
+
+/**
+ * @typedef {import('@appium/types').ISessionHandler<AppiumDriverConstraints,
+ * SessionHandlerCreateResult, SessionHandlerDeleteResult>} AppiumSessionHandler
+ */
+
+/**
+ * @typedef {SessionHandlerResult<[innerSessionId: string, caps:
+ * import('@appium/types').DriverCaps<Constraints>, protocol: string|undefined]>} SessionHandlerCreateResult
+ */
+
+/**
+ * @template {Constraints} C
+ * @typedef {import('@appium/types').Core<C>} Core
+ */
+
+/**
+ * @typedef {SessionHandlerResult<void>} SessionHandlerDeleteResult
  */
 
 /**
@@ -868,11 +884,6 @@ export {AppiumDriver};
  */
 
 /**
- * @template {Constraints} C
- * @typedef {import('@appium/types').W3CCapabilities<C>} W3CCapabilities
- */
-
-/**
- * @template {Constraints} C
- * @typedef {import('@appium/types').Capabilities<C>} Capabilities
+ * @typedef {typeof desiredCapabilityConstraints} AppiumDriverConstraints
+ * @typedef {import('@appium/types').W3CDriverCaps<AppiumDriverConstraints>} W3CAppiumDriverCaps
  */

package/lib/cli/args.js

@@ -84,6 +84,16 @@ function makeListArgs(type) {
         dest: 'showUpdates',
       },
     ],
+    [
+      ['--verbose'],
+      {
+        required: false,
+        default: false,
+        action: 'store_true',
+        help: 'Show more information about each extension',
+        dest: 'verbose',
+      },
+    ],
   ]);
 }
 

package/lib/cli/driver-command.js

@@ -1,15 +1,15 @@
 import _ from 'lodash';
-import ExtensionCommand from './extension-command';
+import ExtensionCliCommand from './extension-command';
 import {KNOWN_DRIVERS} from '../constants';
 import '@colors/colors';
 
 const REQ_DRIVER_FIELDS = ['driverName', 'automationName', 'platformNames', 'mainClass'];
 
 /**
- * @extends {ExtensionCommand<DriverType>}
+ * @extends {ExtensionCliCommand<DriverType>}
  */
 
-export default class DriverCommand extends ExtensionCommand {
+export default class DriverCliCommand extends ExtensionCliCommand {
   /**
    * @param {import('./extension-command').ExtensionCommandOptions<DriverType>} opts
    */
@@ -120,7 +120,7 @@ export default class DriverCommand extends ExtensionCommand {
  */
 
 /**
- * Options for {@linkcode DriverCommand.install}
+ * Options for {@linkcode DriverCliCommand.install}
  * @typedef DriverInstallOpts
  * @property {string} driver - the name or spec of a driver to install
  * @property {InstallType} installType - how to install this driver. One of the INSTALL_TYPES
@@ -132,20 +132,20 @@ export default class DriverCommand extends ExtensionCommand {
  */
 
 /**
- * Options for {@linkcode DriverCommand.uninstall}
+ * Options for {@linkcode DriverCliCommand.uninstall}
  * @typedef DriverUninstallOpts
  * @property {string} driver - the name or spec of a driver to uninstall
  */
 
 /**
- * Options for {@linkcode DriverCommand.update}
+ * Options for {@linkcode DriverCliCommand.update}
  * @typedef DriverUpdateOpts
  * @property {string} driver - the name of the driver to update
  * @property {boolean} unsafe - if true, will perform unsafe updates past major revision boundaries
  */
 
 /**
- * Options for {@linkcode DriverCommand.run}.
+ * Options for {@linkcode DriverCliCommand.run}.
  * @typedef DriverRunOptions
  * @property {string} driver - name of the driver to run a script from
  * @property {string} scriptName - name of the script to run