appium 2.0.0-beta.4 → 2.0.0-beta.42

package/README.md

@@ -1,15 +1,14 @@
 ## Appium
 
 [![NPM version](https://badge.fury.io/js/appium.svg)](https://npmjs.org/package/appium)
-[![Dependency Status](https://david-dm.org/appium/appium.svg)](https://david-dm.org/appium/appium)
-[![devDependency Status](https://david-dm.org/appium/appium/dev-status.svg)](https://david-dm.org/appium/appium#info=devDependencies)
+[![Node.js CI](https://github.com/appium/appium/actions/workflows/node.js.yml/badge.svg?branch=2.0)](https://github.com/appium/appium/actions/workflows/node.js.yml)
 
 [![Monthly Downloads](https://img.shields.io/npm/dm/appium.svg)](https://npmjs.org/package/appium)
 
 [![FOSSA Status](https://app.fossa.io/api/projects/git%2Bhttps%3A%2F%2Fgithub.com%2Fappium%2Fappium.svg?type=shield)](https://app.fossa.io/projects/git%2Bhttps%3A%2F%2Fgithub.com%2Fappium%2Fappium?ref=badge_shield)
 
-Appium is an open source, cross-platform test automation tool for native,
-hybrid and mobile web and desktop apps. We support simulators (iOS), emulators
+Appium is an open-source, cross-platform test automation tool for native,
+hybrid, and mobile web and desktop apps. We support simulators (iOS), emulators
 (Android), and real devices (iOS, Android, Windows, Mac).
 
 Want to skip straight to the action? Check out our [getting
@@ -35,7 +34,7 @@ specific information about how that driver works and how to set it up:
 ### Why Appium?
 
 1. You don't have to recompile your app or modify it in any way, due
-   to use of standard automation APIs on all platforms.
+   to the use of standard automation APIs on all platforms.
 2. You can write tests with your favorite dev tools using any
    [WebDriver](https://w3c.github.io/webdriver/webdriver-spec.html)-compatible
    language such as Java, Objective-C, JavaScript (Node), PHP, Python, Ruby,
@@ -43,22 +42,22 @@ specific information about how that driver works and how to set it up:
    client libraries](/docs/en/about-appium/appium-clients.md).
 3. You can use any testing framework.
 4. Appium has built-in mobile web and hybrid app support. Within the same
-   script you can switch seamlessly between native app automation and webview
+   script, you can switch seamlessly between native app automation and webview
    automation, all using the WebDriver model that's already the standard for
    web automation.
 
 Investing in the
 [WebDriver](https://w3c.github.io/webdriver/webdriver-spec.html) protocol means
-you are betting on a single, free and open protocol for testing that has become
+you are betting on a single, free, and open protocol for testing that has become
 a web standard. Don't lock yourself into a proprietary stack.
 
 For example, if you use Apple's XCUITest library without Appium you can only
 write tests using Obj-C/Swift, and you can only run tests through Xcode.
-Similarly, with Google's UiAutomator or Espresso you can only write tests in
+Similarly, with Google's UiAutomator or Espresso, you can only write tests in
 Java/Kotlin. Appium opens up the possibility of true cross-platform native app
 automation, for mobile and beyond. Finally!
 
-If you're new to Appium, or want a more comprehensive description of what this is all
+If you're new to Appium or want a more comprehensive description of what this is all
 about, please read our [Introduction to Appium
 Concepts](/docs/en/about-appium/intro.md).
 
@@ -74,7 +73,7 @@ Node.js 10+.
 Check out our [Getting Started](/docs/en/about-appium/getting-started.md) guide
 to get going with Appium.
 
-There is also sample code that contains [many examples of tests in a variety
+There is also a sample code that contains [many examples of tests in a variety
 of different languages](https://github.com/appium/appium/tree/master/sample-code)!
 
 ### Documentation
@@ -92,7 +91,7 @@ Once the PR has been merged, the latest documentation will be in [appium.io](htt
 ### Contributing
 
 Please take a look at our [contribution documentation](CONTRIBUTING.md)
-for instructions on how to build, test and run Appium from source.
+for instructions on how to build, test, and run Appium from the source.
 
 ### Roadmap
 

package/build/lib/appium.d.ts

@@ -0,0 +1,204 @@
+/**
+ * Thrown when Appium tried to proxy a command using a driver's `proxyCommand` method but the
+ * method did not exist
+ */
+export class NoDriverProxyCommandError extends Error {
+    constructor();
+    /**
+     * @type {Readonly<string>}
+     */
+    code: Readonly<string>;
+}
+export type ExternalDriver = import('@appium/types').ExternalDriver;
+export type Driver = import('@appium/types').Driver;
+export type DriverClass = import('@appium/types').DriverClass;
+export type W3CCapabilities = import('@appium/types').W3CCapabilities;
+export type DriverData = import('@appium/types').DriverData;
+export type DriverOpts = import('@appium/types').ServerArgs;
+export type Constraints = import('@appium/types').Constraints;
+export type AppiumServer = import('@appium/types').AppiumServer;
+export type ExtensionType = import('@appium/types').ExtensionType;
+export type DriverConfig = import('./extension/driver-config').DriverConfig;
+export type Plugin = import('@appium/types').Plugin;
+export type PluginClass = import('@appium/types').PluginClass;
+export type PluginType = import('@appium/types').PluginType;
+export type DriverType = import('@appium/types').DriverType;
+export type SessionHandler = import('@appium/types').SessionHandler<SessionHandlerResult<any[]>, SessionHandlerResult<void>>;
+/**
+ * Used by {@linkcode AppiumDriver.createSession } and {@linkcode AppiumDriver.deleteSession } to describe
+ * result.
+ */
+export type SessionHandlerResult<V> = {
+    value?: V | undefined;
+    error?: Error | undefined;
+    protocol?: string | undefined;
+};
+/**
+ * @implements {SessionHandler}
+ */
+export class AppiumDriver extends DriverCore implements SessionHandler {
+    /**
+     * @param {DriverOpts} opts
+     */
+    constructor(opts: DriverOpts);
+    /**
+     * Access to sessions list must be guarded with a Semaphore, because
+     * it might be changed by other async calls at any time
+     * It is not recommended to access this property directly from the outside
+     * @type {Record<string,ExternalDriver>}
+     */
+    sessions: Record<string, ExternalDriver>;
+    /**
+     * Access to pending drivers list must be guarded with a Semaphore, because
+     * it might be changed by other async calls at any time
+     * It is not recommended to access this property directly from the outside
+     * @type {Record<string,ExternalDriver[]>}
+     */
+    pendingDrivers: Record<string, ExternalDriver[]>;
+    /**
+     * List of active plugins
+     * @type {Map<PluginClass,string>}
+     */
+    pluginClasses: Map<PluginClass, string>;
+    /**
+     * map of sessions to actual plugin instances per session
+     * @type {Record<string,InstanceType<PluginClass>[]>}
+     */
+    sessionPlugins: Record<string, InstanceType<PluginClass>[]>;
+    /**
+     * some commands are sessionless, so we need a set of plugins for them
+     * @type {InstanceType<PluginClass>[]}
+     */
+    sessionlessPlugins: InstanceType<PluginClass>[];
+    /** @type {DriverConfig} */
+    driverConfig: DriverConfig;
+    /** @type {AppiumServer} */
+    server: AppiumServer;
+    desiredCapConstraints: Readonly<import("@appium/types").Constraints>;
+    /** @type {DriverOpts} */
+    args: DriverOpts;
+    sessionExists(sessionId: any): boolean;
+    driverForSession(sessionId: any): import("@appium/types").ExternalDriver;
+    getStatus(): Promise<{
+        build: import("../types").BuildInfo;
+    }>;
+    getSessions(): Promise<{
+        id: string;
+        capabilities: Partial<import("@wdio/types/build/Capabilities").Capabilities & import("@wdio/types/build/Capabilities").AppiumCapabilities & {
+            [x: string]: any;
+        }> | undefined;
+    }[]>;
+    printNewSessionAnnouncement(driverName: any, driverVersion: any, driverBaseVersion: any): void;
+    /**
+     * Retrieves all CLI arguments for a specific plugin.
+     * @param {string} extName - Plugin name
+     * @returns {Record<string,unknown>} Arguments object. If none, an empty object.
+     */
+    getCliArgsForPlugin(extName: string): Record<string, unknown>;
+    /**
+     * Retrieves CLI args for a specific driver.
+     *
+     * _Any arg which is equal to its default value will not be present in the returned object._
+     *
+     * _Note that this behavior currently (May 18 2022) differs from how plugins are handled_ (see {@linkcode AppiumDriver.getCliArgsForPlugin}).
+     * @param {string} extName - Driver name
+     * @returns {Record<string,unknown>|undefined} Arguments object. If none, `undefined`
+     */
+    getCliArgsForDriver(extName: string): Record<string, unknown> | undefined;
+    /**
+     * Create a new session
+     * @param {W3CCapabilities} jsonwpCaps JSONWP formatted desired capabilities
+     * @param {W3CCapabilities} reqCaps Required capabilities (JSONWP standard)
+     * @param {W3CCapabilities} w3cCapabilities W3C capabilities
+     * @param {DriverData[]} [driverData]
+     */
+    createSession(jsonwpCaps: W3CCapabilities, reqCaps: W3CCapabilities, w3cCapabilities: W3CCapabilities, driverData?: import("@appium/types").DriverData[] | undefined): Promise<{
+        protocol: string | undefined;
+        error: any;
+        value?: undefined;
+    } | {
+        protocol: string | undefined;
+        value: any[];
+        error?: undefined;
+    }>;
+    /**
+     *
+     * @param {Driver} driver
+     * @param {string} innerSessionId
+     */
+    attachUnexpectedShutdownHandler(driver: Driver, innerSessionId: string): void;
+    /**
+     *
+     * @param {DriverClass} InnerDriver
+     * @returns {Promise<DriverData[]>}}
+     */
+    curSessionDataForDriver(InnerDriver: DriverClass): Promise<DriverData[]>;
+    /**
+     * @param {string} sessionId
+     */
+    deleteSession(sessionId: string): Promise<{
+        protocol: undefined;
+        value: void;
+        error?: undefined;
+    } | {
+        protocol: undefined;
+        error: any;
+        value?: undefined;
+    }>;
+    deleteAllSessions(opts?: {}): Promise<void>;
+    /**
+     * Get the appropriate plugins for a session (or sessionless plugins)
+     *
+     * @param {?string} sessionId - the sessionId (or null) to use to find plugins
+     * @returns {Array} - array of plugin instances
+     */
+    pluginsForSession(sessionId?: string | null): any[];
+    /**
+     * To get plugins for a command, we either get the plugin instances associated with the
+     * particular command's session, or in the case of sessionless plugins, pull from the set of
+     * plugin instances reserved for sessionless commands (and we lazily create plugin instances on
+     * first use)
+     *
+     * @param {string} cmd - the name of the command to find a plugin to handle
+     * @param {?string} sessionId - the particular session for which to find a plugin, or null if
+     * sessionless
+     */
+    pluginsToHandleCmd(cmd: string, sessionId?: string | null): any[];
+    /**
+     * Creates instances of all of the enabled Plugin classes
+     * @returns {Plugin[]}
+     */
+    createPluginInstances(): Plugin[];
+    /**
+     *
+     * @param {string} cmd
+     * @param  {...any} args
+     * @returns {Promise<{value: any, error?: Error, protocol: string} | import('type-fest').AsyncReturnType<Driver['executeCommand']>>}
+     */
+    executeCommand(cmd: string, ...args: any[]): Promise<any>;
+    wrapCommandWithPlugins({ driver, cmd, args, next, cmdHandledBy, plugins }: {
+        driver: any;
+        cmd: any;
+        args: any;
+        next: any;
+        cmdHandledBy: any;
+        plugins: any;
+    }): any;
+    logPluginHandlerReport(plugins: any, { cmd, cmdHandledBy }: {
+        cmd: any;
+        cmdHandledBy: any;
+    }): void;
+    executeWrappedCommand({ wrappedCmd, protocol }: {
+        wrappedCmd: any;
+        protocol: any;
+    }): Promise<{
+        value: any;
+        error: any;
+        protocol: any;
+    }>;
+    proxyActive(sessionId: any): boolean;
+    getProxyAvoidList(sessionId: any): [string, RegExp][];
+    canProxy(sessionId: any): boolean;
+}
+import { DriverCore } from "@appium/base-driver";
+//# sourceMappingURL=appium.d.ts.map

package/build/lib/appium.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"appium.d.ts","sourceRoot":"","sources":["../../lib/appium.js"],"names":[],"mappings":"AAkyBA;;;GAGG;AACH;IAME,cAOC;IAZD;;OAEG;IACH,MAFU,SAAS,MAAM,CAAC,CAEgB;CAU3C;6BAKY,OAAO,eAAe,EAAE,cAAc;qBACtC,OAAO,eAAe,EAAE,MAAM;0BAC9B,OAAO,eAAe,EAAE,WAAW;8BACnC,OAAO,eAAe,EAAE,eAAe;yBACvC,OAAO,eAAe,EAAE,UAAU;yBAClC,OAAO,eAAe,EAAE,UAAU;0BAClC,OAAO,eAAe,EAAE,WAAW;2BACnC,OAAO,eAAe,EAAE,YAAY;4BACpC,OAAO,eAAe,EAAE,aAAa;2BACrC,OAAO,2BAA2B,EAAE,YAAY;qBAChD,OAAO,eAAe,EAAE,MAAM;0BAC9B,OAAO,eAAe,EAAE,WAAW;yBACnC,OAAO,eAAe,EAAE,UAAU;yBAClC,OAAO,eAAe,EAAE,UAAU;6BAClC,OAAO,eAAe,EAAE,cAAc,CAAC,qBAAqB,GAAG,EAAE,CAAC,EAAC,qBAAqB,IAAI,CAAC,CAAC;;;;;;;;;;AAnyB3G;;GAEG;AACH;IAqDE;;OAEG;IACH,kBAFW,UAAU,EAwBpB;IA7ED;;;;;OAKG;IACH,UAFU,OAAO,MAAM,EAAC,cAAc,CAAC,CAEzB;IAEd;;;;;OAKG;IACH,gBAFU,OAAO,MAAM,EAAC,cAAc,EAAE,CAAC,CAErB;IASpB;;;OAGG;IACH,eAFU,IAAI,WAAW,EAAC,MAAM,CAAC,CAEnB;IAEd;;;OAGG;IACH,gBAFU,OAAO,MAAM,EAAC,aAAa,WAAW,CAAC,EAAE,CAAC,CAEhC;IAEpB;;;OAGG;IACH,oBAFU,aAAa,WAAW,CAAC,EAAE,CAEb;IAExB,2BAA2B;IAC3B,cADW,YAAY,CACV;IAEb,2BAA2B;IAC3B,QADW,YAAY,CAChB;IAEP,qEAAqD;IAErD,yBAAyB;IACzB,MADW,UAAU,CAChB;IA+CL,uCAGC;IAED,yEAEC;IAGD;;OAIC;IAGD;;;;;SAKC;IAED,+FAiBC;IAED;;;;OAIG;IACH,6BAHW,MAAM,GACJ,OAAO,MAAM,EAAC,OAAO,CAAC,CAIlC;IAED;;;;;;;;OAQG;IACH,6BAHW,MAAM,GACJ,OAAO,MAAM,EAAC,OAAO,CAAC,GAAC,SAAS,CAgB5C;IAED;;;;;;OAMG;IACH,0BALW,eAAe,WACf,eAAe,mBACf,eAAe;;;;;;;;OAuKzB;IAED;;;;OAIG;IACH,wCAHW,MAAM,kBACN,MAAM,QAsChB;IAED;;;;OAIG;IAEH,qCAJW,WAAW,GACT,QAAQ,UAAU,EAAE,CAAC,CAkBjC;IAED;;OAEG;IACH,yBAFW,MAAM;;;;;;;;OA0ChB;IAED,4CAqBC;IAED;;;;;OAKG;IACH,8BAHY,MAAM,gBAejB;IAED;;;;;;;;;OASG;IACH,wBAJW,MAAM,cACL,MAAM,gBASjB;IAED;;;OAGG;IACH,yBAFa,MAAM,EAAE,CAWpB;IAED;;;;;OAKG;IACH,oBAJW,MAAM,WACF,GAAG,kBA+HjB;IAED;;;;;;;YAwBC;IAED;;;aAoBC;IAED;;;;;;;OAwBC;IAED,qCAGC;IAED,sDAGC;IAED,kCAGC;CACF"}