@appium/types 0.2.3 → 0.3.0

package/build/plugin.d.ts

@@ -0,0 +1,79 @@
+import { MethodMap, UpdateServerCallback, Class, AppiumLogger } from '.';
+import { Driver, ExternalDriver } from './driver';
+/**
+ * The interface describing the constructor and static properties of a Plugin.
+ */
+export interface PluginStatic<T extends Plugin = Plugin> {
+    /**
+     * Allows a plugin to modify the Appium server instance.
+     */
+    updateServer?: UpdateServerCallback;
+    /**
+     * Plugins can define new methods for the Appium server to map to command names, of the same
+     * format as used in Appium's `routes.js`, for example, this would be a valid `newMethodMap`:
+     * @example
+     * {
+     *   '/session/:sessionId/new_method': {
+     *     GET: {command: 'getNewThing'},
+     *     POST: {command: 'setNewThing', payloadParams: {required: ['someParam']}}
+     *   }
+     * }
+     */
+    newMethodMap?: MethodMap<T>;
+}
+/**
+ * An instance of a "plugin" extension.
+ *
+ * Likewise, the `prototype` of a {@link PluginClass `Plugin` class}.
+ */
+export interface Plugin {
+    /**
+     * Name of the plugin.  Derived from the metadata.
+     */
+    name: string;
+    /**
+     * A logger with prefix identifying the plugin
+     */
+    logger: AppiumLogger;
+    /**
+     * CLI args for this plugin (if any are accepted and provided).
+     */
+    cliArgs: Record<string, any>;
+    /**
+     * Listener for unexpected server shutdown, which allows a plugin to do cleanup or take custom actions.
+     */
+    onUnexpectedShutdown?: (driver: Driver, cause: Error | string) => Promise<void>;
+    /**
+     * Handle an Appium command, optionally running and using or throwing away the value of the
+     * original Appium behavior (or the behavior of the next plugin in a plugin chain).
+     */
+    handle?: (next: NextPluginCallback, driver: Driver, cmdName: string, ...args: any[]) => Promise<void>;
+}
+/**
+ * A reference to an async function which encapsulates what would normally
+ * happen if this plugin were not handling a command. Used by {@link PluginInterface.handle}.
+ *
+ * Given `next()` is a `NextPluginCallback`: if this is the only plugin
+ * handling the command, `await next()` would therefore trigger the normal
+ * handling logic in the driver which is in use. If another plugin is
+ * registered, it would run *that* plugin's `handle` method and return the
+ * result for use here. Note that if this plugin does *not* call `await next()`,
+ * then the normal command logic will not be run, and this plugin is responsible
+ * for managing new command timeouts and command logging, for example:
+ * `driver.stopNewCommandTimeout()` -- before running plugin logic
+ * `driver.startNewCommandTimeout()` -- after running plugin logic
+ * `driver._eventHistory.commands.push({cmd: cmdName, startTime, endTime}) --
+ * after running plugin logic
+ */
+export declare type NextPluginCallback = () => Promise<void>;
+/**
+ * Implementation of a command within a plugin
+ */
+export declare type PluginCommand<TArgs = any> = (next: NextPluginCallback, driver: ExternalDriver, ...args: TArgs[]) => Promise<void>;
+/**
+ * Mainly for internal use.
+ *
+ * The third parameter is the possible constructor signatures for the plugin class.
+ */
+export declare type PluginClass = Class<Plugin, PluginStatic, [string, Record<string, unknown>]>;
+//# sourceMappingURL=plugin.d.ts.map

package/build/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../lib/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,SAAS,EAAE,oBAAoB,EAAE,KAAK,EAAE,YAAY,EAAC,MAAM,GAAG,CAAC;AACvE,OAAO,EAAC,MAAM,EAAE,cAAc,EAAC,MAAM,UAAU,CAAC;AAEhD;;GAEG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;IACrD;;OAEG;IACH,YAAY,CAAC,EAAE,oBAAoB,CAAC;IACpC;;;;;;;;;;OAUG;IACH,YAAY,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC;CAC7B;AAED;;;;GAIG;AACH,MAAM,WAAW,MAAM;IACrB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;OAEG;IACH,MAAM,EAAE,YAAY,CAAC;IACrB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC7B;;OAEG;IACH,oBAAoB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAChF;;;OAGG;IACH,MAAM,CAAC,EAAE,CACP,IAAI,EAAE,kBAAkB,EACxB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,GAAG,IAAI,EAAE,GAAG,EAAE,KACX,OAAO,CAAC,IAAI,CAAC,CAAC;CACpB;AAED;;;;;;;;;;;;;;;GAeG;AACH,oBAAY,kBAAkB,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;AAErD;;GAEG;AACH,oBAAY,aAAa,CAAC,KAAK,GAAG,GAAG,IAAI,CACvC,IAAI,EAAE,kBAAkB,EACxB,MAAM,EAAE,cAAc,EACtB,GAAG,IAAI,EAAE,KAAK,EAAE,KACb,OAAO,CAAC,IAAI,CAAC,CAAC;AAEnB;;;;GAIG;AACH,oBAAY,WAAW,GAAG,KAAK,CAAC,MAAM,EAAE,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC"}

package/lib/capabilities.ts

@@ -1,4 +1,4 @@
-import type { Capabilities as WdioCaps } from '@wdio/types';
+import type {Capabilities as WdioCaps} from '@wdio/types';
 
 /**
  * The mask of a W3C-style namespaced capability proped name.
@@ -19,31 +19,31 @@ type StringRecord = Record<string, any>;
  * All known capabilities derived from wdio's {@linkcode WdioCaps.Capabilities Capabilities} type, accepting additional optional caps.
  * All properties are optional.
  */
-type BaseCapabilities<OptionalCaps extends StringRecord = StringRecord> =
-  Partial<WdioCaps.Capabilities & OptionalCaps>;
+type BaseCapabilities<OptionalCaps extends StringRecord = StringRecord> = Partial<
+  WdioCaps.Capabilities & OptionalCaps
+>;
 
 /**
  * All known capabilities derived from wdio's {@linkcode WdioCaps.Capabilities Capabilities} type and wdio's {@linkcode WdioCaps.AppiumCapabilities} type, accepting additional optional caps.
- * 
+ *
  * In practice, the properties `platformName` and `automationName` are required by Appium.
  */
-export type Capabilities<OptionalCaps extends StringRecord = StringRecord> =
-  BaseCapabilities<WdioCaps.AppiumCapabilities & OptionalCaps>;
+export type Capabilities<OptionalCaps extends StringRecord = StringRecord> = BaseCapabilities<
+  WdioCaps.AppiumCapabilities & OptionalCaps
+>;
 
 /**
  * All known capabilities derived from wdio's {@linkcode WdioCaps.Capabilities Capabilities} type and wdio's {@linkcode WdioCaps.AppiumW3CCapabilities} type, accepting additional optional _namespaced_ caps.
  */
 export type AppiumW3CCapabilities<
-  OptionalNamespacedCaps extends NamespacedRecord = NamespacedRecord,
+  OptionalNamespacedCaps extends NamespacedRecord = NamespacedRecord
 > = BaseCapabilities<WdioCaps.AppiumW3CCapabilities & OptionalNamespacedCaps>;
 
 /**
  * All known capabilities derived from wdio's {@linkcode WdioCaps.Capabilities Capabilities} type and wdio's {@linkcode WdioCaps.AppiumW3Capabilities} type, accepting additional optional _namespaced_ caps, in W3C-compatible format (`alwaysMatch`/`firstMatch`).
  * In practice, the properties `appium:platformName` and `appium:automationName` are required by Appium _somewhere_ in this object; this cannot be expressed in TypeScript.
  */
-export type W3CCapabilities<
-  OptionalNamespacedCaps extends NamespacedRecord = NamespacedRecord,
-> = {
+export type W3CCapabilities<OptionalNamespacedCaps extends NamespacedRecord = NamespacedRecord> = {
   alwaysMatch: AppiumW3CCapabilities<OptionalNamespacedCaps>;
   firstMatch: AppiumW3CCapabilities<OptionalNamespacedCaps>[];
 };
@@ -55,6 +55,5 @@ export type AppiumAndroidCapabilities = WdioCaps.AppiumAndroidCapabilities;
 export type AppiumIOSCapabilities = WdioCaps.AppiumIOSCapabilities;
 export type AppiumXCUICommandTimeouts = WdioCaps.AppiumXCUICommandTimeouts;
 export type AppiumXCUIProcessArguments = WdioCaps.AppiumXCUIProcessArguments;
-export type AppiumXCUISafariGlobalPreferences =
-  WdioCaps.AppiumXCUISafariGlobalPreferences;
+export type AppiumXCUISafariGlobalPreferences = WdioCaps.AppiumXCUISafariGlobalPreferences;
 export type AppiumXCUITestCapabilities = WdioCaps.AppiumXCUITestCapabilities;

package/lib/config.ts

@@ -1,5 +1,5 @@
-import type { AppiumConfigJsonSchema } from '@appium/schema';
-import { AppiumConfiguration, ServerConfig } from './appium-config';
+import type {AppiumConfigJsonSchema} from '@appium/schema';
+import {AppiumConfiguration, ServerConfig} from './appium-config';
 
 /**
  * The Appium configuration as it would be in a user-provided configuration file.
@@ -9,8 +9,7 @@ export type AppiumConfig = Partial<AppiumConfiguration>;
 /**
  * Derive the "constant" type of the server properties from the schema.
  */
- type AppiumServerJsonSchema =
- typeof AppiumConfigJsonSchema['properties']['server']['properties'];
+type AppiumServerJsonSchema = typeof AppiumConfigJsonSchema['properties']['server']['properties'];
 
 /**
  * This type associates the types generated from the schema ({@linkcode AppiumConfiguration})
@@ -67,35 +66,34 @@ export type ServerArgs = {
 /**
  * Converts a kebab-cased string into a camel-cased string.
  */
- type KebabToCamel<S extends string> =
- S extends `${infer P1}-${infer P2}${infer P3}`
-   ? `${Lowercase<P1>}${Uppercase<P2>}${KebabToCamel<P3>}`
-   : Lowercase<S>;
+type KebabToCamel<S extends string> = S extends `${infer P1}-${infer P2}${infer P3}`
+  ? `${Lowercase<P1>}${Uppercase<P2>}${KebabToCamel<P3>}`
+  : Lowercase<S>;
 
 /**
-* Converts an object with kebab-cased keys into camel-cased keys.
-*/
+ * Converts an object with kebab-cased keys into camel-cased keys.
+ */
 type ObjectToCamel<T> = {
- [K in keyof T as KebabToCamel<string & K>]: T[K] extends Record<string, any>
-   ? KeysToCamelCase<T[K]>
-   : T[K];
+  [K in keyof T as KebabToCamel<string & K>]: T[K] extends Record<string, any>
+    ? KeysToCamelCase<T[K]>
+    : T[K];
 };
 
 /**
-* Converts an object or array to have camel-cased keys.
-*/
+ * Converts an object or array to have camel-cased keys.
+ */
 type KeysToCamelCase<T> = {
- [K in keyof T as KebabToCamel<string & K>]: T[K] extends Array<any>
-   ? KeysToCamelCase<T[K][number]>[]
-   : ObjectToCamel<T[K]>;
+  [K in keyof T as KebabToCamel<string & K>]: T[K] extends Array<any>
+    ? KeysToCamelCase<T[K][number]>[]
+    : ObjectToCamel<T[K]>;
 };
 
 /**
- * Object `B` has all the keys as object `A` (even if those keys in `A` are otherwise optional). 
+ * Object `B` has all the keys as object `A` (even if those keys in `A` are otherwise optional).
  */
-type Associated<A extends object, B extends { [key in keyof Required<A>]: unknown }> = {
+type Associated<A extends object, B extends {[key in keyof Required<A>]: unknown}> = {
   [Prop in keyof Required<A>]: B[Prop];
-}
+};
 
 // end utils
 
@@ -109,7 +107,7 @@ type Associated<A extends object, B extends { [key in keyof Required<A>]: unknow
  *
  * See `appium/lib/schema/keywords` for definition of `appiumCliDest`.
  */
- interface WithDest {
+interface WithDest {
   appiumCliDest: string;
 }
 
@@ -125,4 +123,3 @@ interface WithDefault<T = any> {
 }
 
 // end conditionals
-