appium 3.2.2 → 3.3.1

package/build/lib/appium.js

@@ -36,19 +36,18 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AppiumDriver = exports.NoDriverProxyCommandError = void 0;
+exports.NoDriverProxyCommandError = exports.AppiumDriver = void 0;
 const lodash_1 = __importDefault(require("lodash"));
-const config_1 = require("./config");
 const base_driver_1 = require("@appium/base-driver");
-const async_lock_1 = __importDefault(require("async-lock"));
-const utils_1 = require("./utils");
+const build_1 = require("./helpers/build");
+const capability_1 = require("./helpers/capability");
 const support_1 = require("@appium/support");
 const schema_1 = require("./schema");
 const constants_1 = require("./constants");
 const bidiCommands = __importStar(require("./bidi-commands"));
 const insecureFeatures = __importStar(require("./insecure-features"));
 const inspectorCommands = __importStar(require("./inspector-commands"));
-const desiredCapabilityConstraints = /** @type {const} */ ({
+const desiredCapabilityConstraints = {
     automationName: {
         presence: true,
         isString: true,
@@ -57,65 +56,41 @@ const desiredCapabilityConstraints = /** @type {const} */ ({
         presence: true,
         isString: true,
     },
-});
-const sessionsListGuard = new async_lock_1.default();
-const pendingDriversGuard = new async_lock_1.default();
+};
 /**
- * @extends {DriverCore<AppiumDriverConstraints>}
+ * Umbrella driver: owns the session table, loads platform drivers and plugins, and routes
+ * commands to the right session driver or plugin chain.
  */
 class AppiumDriver extends base_driver_1.DriverCore {
+    sessions = {};
+    pendingDrivers = {};
     /**
-     * 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;
-    /**
-     * 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;
-    /**
-     * Note that {@linkcode AppiumDriver} has no `newCommandTimeout` method.
-     * `AppiumDriver` does not set and observe its own timeouts; individual
-     * sessions (managed drivers) do instead.
+     * The umbrella driver does not observe its own command timeout; inner session drivers do.
      */
-    newCommandTimeoutMs;
-    /**
-     * List of active plugins
-     * @type {Map<PluginClass,string>}
-     */
-    pluginClasses;
-    /**
-     * map of sessions to actual plugin instances per session
-     * @type {Record<string,InstanceType<PluginClass>[]>}
-     */
-    sessionPlugins;
-    /**
-     * some commands are sessionless, so we need a set of plugins for them
-     * @type {InstanceType<PluginClass>[]}
-     */
-    sessionlessPlugins;
-    /** @type {DriverConfig} */
+    newCommandTimeoutMs = 0;
+    /** Filled during server bootstrap; keep this map instance (do not reassign). */
+    pluginClasses = new Map();
+    sessionPlugins = {};
+    sessionlessPlugins = [];
+    /** Set during server init before listen; tests may assign a mock after construction. */
     driverConfig;
-    /** @type {AppiumServer} */
+    /** Set when the HTTP server is created in server bootstrap. */
     server;
-    /** @type {Record<string, import('ws').WebSocket[]>} */
-    bidiSockets;
-    /** @type {Record<string, import('ws').WebSocket>} */
-    bidiProxyClients;
-    /**
-     * @type {AppiumDriverConstraints}
-     * @readonly
-     */
-    desiredCapConstraints;
-    /** @type {import('@appium/types').DriverOpts<AppiumDriverConstraints>} */
+    bidiSockets = {};
+    bidiProxyClients = {};
+    desiredCapConstraints = desiredCapabilityConstraints;
     args;
+    onBidiConnection = bidiCommands.onBidiConnection;
+    onBidiMessage = bidiCommands.onBidiMessage;
+    onBidiServerError = bidiCommands.onBidiServerError;
+    cleanupBidiSockets = bidiCommands.cleanupBidiSockets;
+    configureGlobalFeatures = insecureFeatures.configureGlobalFeatures;
+    configureDriverFeatures = insecureFeatures.configureDriverFeatures;
+    listCommands = inspectorCommands.listCommands;
+    listExtensions = inspectorCommands.listExtensions;
+    _isShuttingDown = false;
     /**
-     * @param {import('@appium/types').DriverOpts<AppiumDriverConstraints>} opts
+     * @param opts - CLI/server options (address, port, security, default capabilities, etc.)
      */
     constructor(opts) {
         // It is necessary to set `--tmp` here since it should be set to
@@ -127,42 +102,36 @@ class AppiumDriver extends base_driver_1.DriverCore {
         }
         super(opts);
         this.args = { ...opts };
-        this.sessions = {};
-        this.pendingDrivers = {};
-        this.newCommandTimeoutMs = 0;
-        this.pluginClasses = new Map();
-        this.sessionPlugins = {};
-        this.sessionlessPlugins = [];
-        this.bidiSockets = {};
-        this.bidiProxyClients = {};
-        this.desiredCapConstraints = desiredCapabilityConstraints;
-        this._isShuttingDown = false;
         // allow this to happen in the background, so no `await`
-        (async () => {
+        void (async () => {
             try {
-                await (0, config_1.updateBuildInfo)();
+                await (0, build_1.updateBuildInfo)();
             }
             catch (e) {
                 // make sure we catch any possible errors to avoid unhandled rejections
-                this.log.debug(`Cannot fetch Appium build info: ${e.message}`);
+                const msg = e instanceof Error ? e.message : String(e);
+                this.log.debug(`Cannot fetch Appium build info: ${msg}`);
             }
         })();
     }
-    /**
-     * Cancel commands queueing for the umbrella Appium driver
-     */
+    /** The umbrella driver does not queue commands; inner session drivers may. */
     get isCommandsQueueEnabled() {
         return false;
     }
+    /** Whether a non-null session id is registered on this server. */
     sessionExists(sessionId) {
         const dstSession = this.sessions[sessionId];
-        return dstSession && dstSession.sessionId !== null;
+        return Boolean(dstSession && dstSession.sessionId !== null);
     }
+    /** Active automation driver for the session, or `null` if unknown. */
     driverForSession(sessionId) {
-        return this.sessions[sessionId];
+        return this.sessions[sessionId] ?? null;
     }
+    /**
+     * WebDriver status payload (readiness message and build metadata).
+     * @see https://www.w3.org/TR/webdriver/#dfn-status
+     */
     async getStatus() {
-        // https://www.w3.org/TR/webdriver/#dfn-status
         const statusObj = this._isShuttingDown
             ? {
                 ready: false,
@@ -174,36 +143,34 @@ class AppiumDriver extends base_driver_1.DriverCore {
             };
         return {
             ...statusObj,
-            build: lodash_1.default.clone((0, config_1.getBuildInfo)()),
+            build: lodash_1.default.clone((0, build_1.getBuildInfo)()),
         };
     }
-    /**
-     * @param {string|null} reason An optional shutdown reason
-     */
+    /** Marks the server as shutting down and ends all sessions (forced unexpected shutdown). */
     async shutdown(reason = null) {
         this._isShuttingDown = true;
         await this.deleteAllSessions({
             force: true,
-            reason,
+            reason: reason ?? undefined,
         });
     }
     /**
      * Retrieve information about all active sessions.
      * Results are returned only if the `session_discovery` insecure feature is enabled.
-     * @returns {Promise<import('@appium/types').TimestampedMultiSessionData[]>}
      */
     async getAppiumSessions() {
         this.assertFeatureEnabled(constants_1.SESSION_DISCOVERY_FEATURE);
         return lodash_1.default.toPairs(this.sessions).map(([id, driver]) => ({
             id,
             created: driver.sessionCreationTimestampMs,
-            capabilities: /** @type {import('@appium/types').DriverCaps<any>} */ (driver.caps),
+            capabilities: driver.caps,
         }));
     }
+    /** Logs BaseDriver version lines when starting a new inner-driver session. */
     printNewSessionAnnouncement(driverName, driverVersion, driverBaseVersion) {
         this.log.info(driverVersion
-            ? `Appium v${config_1.APPIUM_VER} creating new ${driverName} (v${driverVersion}) session`
-            : `Appium v${config_1.APPIUM_VER} creating new ${driverName} session`);
+            ? `Appium v${build_1.APPIUM_VER} creating new ${driverName} (v${driverVersion}) session`
+            : `Appium v${build_1.APPIUM_VER} creating new ${driverName} session`);
         this.log.info(`Checking BaseDriver versions for Appium and ${driverName}`);
         this.log.info(AppiumDriver.baseVersion
             ? `Appium's BaseDriver version is ${AppiumDriver.baseVersion}`
@@ -213,82 +180,64 @@ class AppiumDriver extends base_driver_1.DriverCore {
             : `Could not determine ${driverName}'s BaseDriver version`);
     }
     /**
-     * Retrieves all CLI arguments for a specific plugin.
-     * @param {string} extName - Plugin name
-     * @returns {StringRecord} Arguments object. If none, an empty object.
+     * CLI arguments object for a plugin (from server config). Empty object if none were passed.
      */
     getCliArgsForPlugin(extName) {
-        return /** @type {StringRecord} */ (this.args.plugin?.[extName] ?? {});
+        return (this.args.plugin?.[extName] ?? {});
     }
     /**
-     * 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 {StringRecord|undefined} Arguments object. If none, `undefined`
+     * CLI arguments for a driver, omitting keys that match schema defaults (unlike
+     * {@link AppiumDriver.getCliArgsForPlugin}, which returns defaults explicitly). `undefined` if
+     * there is nothing to pass after omitting defaults.
      */
     getCliArgsForDriver(extName) {
-        const allCliArgsForExt = /** @type {StringRecord|undefined} */ (this.args.driver?.[extName]);
-        if (!lodash_1.default.isEmpty(allCliArgsForExt)) {
-            const defaults = (0, schema_1.getDefaultsForExtension)(constants_1.DRIVER_TYPE, extName);
-            const cliArgs = lodash_1.default.isEmpty(defaults)
-                ? allCliArgsForExt
-                : lodash_1.default.omitBy(allCliArgsForExt, (value, key) => lodash_1.default.isEqual(defaults[key], value));
-            if (!lodash_1.default.isEmpty(cliArgs)) {
-                return cliArgs;
-            }
+        const allCliArgsForExt = this.args.driver?.[extName];
+        if (lodash_1.default.isEmpty(allCliArgsForExt)) {
+            return undefined;
         }
+        const defaults = (0, schema_1.getDefaultsForExtension)(constants_1.DRIVER_TYPE, extName);
+        const cliArgs = lodash_1.default.isEmpty(defaults)
+            ? allCliArgsForExt
+            : lodash_1.default.omitBy(allCliArgsForExt, (value, key) => lodash_1.default.isEqual(defaults[key], value));
+        return lodash_1.default.isEmpty(cliArgs) ? undefined : cliArgs;
     }
     /**
-     * Create a new session
-     *
-     * @param {W3CAppiumDriverCaps} w3cCapabilities1 W3C capabilities
-     * @param {W3CAppiumDriverCaps} [w3cCapabilities2] W3C capabilities (legacy)
-     * @param {W3CAppiumDriverCaps} [w3cCapabilities3] W3C capabilities (legacy)
-     * @returns {Promise<SessionHandlerCreateResult>}
+     * Creates a session: picks an inner driver from caps, runs plugin hooks, and returns a protocol
+     * envelope with either `[sessionId, caps, protocol]` or an error. Legacy call sites may pass the
+     * same W3C caps in up to three positions; the first W3C-shaped value wins.
      */
     async createSession(w3cCapabilities1, w3cCapabilities2, w3cCapabilities3) {
         const defaultCapabilities = lodash_1.default.cloneDeep(this.args.defaultCapabilities);
-        const defaultSettings = (0, utils_1.pullSettings)(defaultCapabilities);
+        const defaultSettings = (0, capability_1.pullSettings)((defaultCapabilities ?? {}));
         const w3cCapabilities = lodash_1.default.cloneDeep([w3cCapabilities3, w3cCapabilities2, w3cCapabilities1].find(base_driver_1.isW3cCaps));
         if (!w3cCapabilities) {
-            throw (0, utils_1.makeNonW3cCapsError)();
+            throw (0, capability_1.makeNonW3cCapsError)();
         }
         const w3cSettings = {
             ...defaultSettings,
-            ...(0, utils_1.pullSettings)(w3cCapabilities.alwaysMatch ?? {}),
+            ...(0, capability_1.pullSettings)(w3cCapabilities.alwaysMatch ?? {}),
         };
         for (const firstMatchEntry of w3cCapabilities.firstMatch ?? []) {
-            Object.assign(w3cSettings, (0, utils_1.pullSettings)(firstMatchEntry));
+            Object.assign(w3cSettings, (0, capability_1.pullSettings)(firstMatchEntry));
         }
         const protocol = base_driver_1.PROTOCOLS.W3C;
-        let innerSessionId, dCaps;
+        let innerSessionId;
+        let dCaps;
         try {
             // Parse the caps into a format that the InnerDriver will accept
-            const parsedCaps = (0, utils_1.parseCapsForInnerDriver)((0, base_driver_1.promoteAppiumOptions)(/** @type {W3CAppiumDriverCaps} */ (w3cCapabilities)), this.desiredCapConstraints, defaultCapabilities ? (0, base_driver_1.promoteAppiumOptionsForObject)(defaultCapabilities) : undefined);
-            const { desiredCaps, processedW3CCapabilities } = 
-            /** @type {import('./utils').ParsedDriverCaps<AppiumDriverConstraints>} */ (parsedCaps);
-            const error = /** @type {import('./utils').InvalidCaps<AppiumDriverConstraints>} */ (parsedCaps).error;
-            // If the parsing of the caps produced an error, throw it in here
-            if (error) {
-                throw error;
+            const parsedCaps = (0, capability_1.parseCapsForInnerDriver)((0, base_driver_1.promoteAppiumOptions)(w3cCapabilities), this.desiredCapConstraints, defaultCapabilities ? (0, base_driver_1.promoteAppiumOptionsForObject)(defaultCapabilities) : undefined);
+            if ('error' in parsedCaps && parsedCaps.error) {
+                throw parsedCaps.error;
             }
+            const { desiredCaps, processedW3CCapabilities } = parsedCaps;
             const { driver: InnerDriver, version: driverVersion, driverName, } = await this.driverConfig.findMatchingDriver(desiredCaps);
             this.printNewSessionAnnouncement(InnerDriver.name, driverVersion, InnerDriver.baseVersion);
             if (this.args.sessionOverride) {
                 await this.deleteAllSessions();
             }
-            /**
-             * @type {DriverData[]}
-             */
             let runningDriversData = [];
-            /**
-             * @type {DriverData[]}
-             */
             let otherPendingDriversData = [];
-            const driverInstance = /** @type {ExternalDriver} */ (new InnerDriver(this.args, true));
+            const driverInstance = new InnerDriver(this.args, true);
             this.configureDriverFeatures(driverInstance, driverName);
             // We also want to assign any new Bidi Commands that the driver has specified, including all
             // the standard bidi commands. But add a method existence guard since some old driver class
@@ -313,22 +262,18 @@ class AppiumDriver extends base_driver_1.DriverCore {
                 runningDriversData = (await this.curSessionDataForDriver(InnerDriver)) ?? [];
             }
             catch (e) {
-                throw new base_driver_1.errors.SessionNotCreatedError(e.message);
+                const msg = e instanceof Error ? e.message : String(e);
+                throw new base_driver_1.errors.SessionNotCreatedError(msg);
             }
-            await pendingDriversGuard.acquire(AppiumDriver.name, () => {
-                this.pendingDrivers[InnerDriver.name] = this.pendingDrivers[InnerDriver.name] || [];
-                otherPendingDriversData = lodash_1.default.compact(this.pendingDrivers[InnerDriver.name].map((drv) => drv.driverData));
-                this.pendingDrivers[InnerDriver.name].push(driverInstance);
-            });
+            this.pendingDrivers[InnerDriver.name] = this.pendingDrivers[InnerDriver.name] || [];
+            otherPendingDriversData = lodash_1.default.compact(this.pendingDrivers[InnerDriver.name].map((drv) => drv.driverData));
+            this.pendingDrivers[InnerDriver.name].push(driverInstance);
             try {
-                [innerSessionId, dCaps] = await driverInstance.createSession(
-                /** @type {any} */ (processedW3CCapabilities), processedW3CCapabilities, processedW3CCapabilities, [...runningDriversData, ...otherPendingDriversData]);
+                [innerSessionId, dCaps] = (await driverInstance.createSession(processedW3CCapabilities, processedW3CCapabilities, processedW3CCapabilities, [...runningDriversData, ...otherPendingDriversData]));
                 this.sessions[innerSessionId] = driverInstance;
             }
             finally {
-                await pendingDriversGuard.acquire(AppiumDriver.name, () => {
-                    lodash_1.default.pull(this.pendingDrivers[InnerDriver.name], driverInstance);
-                });
+                lodash_1.default.pull(this.pendingDrivers[InnerDriver.name], driverInstance);
             }
             this.attachUnexpectedShutdownHandler(driverInstance, innerSessionId);
             this.log.info(`New ${InnerDriver.name} session created successfully, session ` +
@@ -360,7 +305,7 @@ class AppiumDriver extends base_driver_1.DriverCore {
         catch (error) {
             return {
                 protocol,
-                error,
+                error: error instanceof Error ? error : new Error(String(error)),
             };
         }
         return {
@@ -369,19 +314,18 @@ class AppiumDriver extends base_driver_1.DriverCore {
         };
     }
     /**
-     *
-     * @param {ExternalDriver} driver
-     * @param {string} innerSessionId
+     * Subscribes to the inner driver’s unexpected-shutdown hook so Appium can drop the session and
+     * notify plugins.
      */
     attachUnexpectedShutdownHandler(driver, innerSessionId) {
-        const onShutdown = (cause = new Error('Unknown error')) => {
+        const onShutdown = async (cause = new Error('Unknown error')) => {
             this.log.warn(`Ending session, cause was '${cause.message}'`);
             if (this.sessionPlugins[innerSessionId]) {
                 for (const plugin of this.sessionPlugins[innerSessionId]) {
                     if (lodash_1.default.isFunction(plugin.onUnexpectedShutdown)) {
                         this.log.debug(`Plugin ${plugin.name} defines an unexpected shutdown handler; calling it now`);
                         try {
-                            plugin.onUnexpectedShutdown(driver, cause);
+                            await plugin.onUnexpectedShutdown(driver, cause);
                         }
                         catch (e) {
                             this.log.warn(`Got an error when running plugin ${plugin.name} shutdown handler: ${e}`);
@@ -405,11 +349,9 @@ class AppiumDriver extends base_driver_1.DriverCore {
         }
     }
     /**
-     *
-     * @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.
+     * Collects `driverData` for every active session whose driver class matches `InnerDriver.name`
+     * (used when creating another session of the same driver type).
+     * @remarks `InnerDriver` is expected to be the driver class; only `.name` is read.
      */
     async curSessionDataForDriver(InnerDriver) {
         const data = lodash_1.default.compact(lodash_1.default.values(this.sessions)
@@ -424,21 +366,20 @@ class AppiumDriver extends base_driver_1.DriverCore {
         return data;
     }
     /**
-     * @param {string} sessionId
+     * Ends one session: removes it from the master list immediately, then delegates to the inner
+     * driver’s `deleteSession` with sibling-session metadata.
      */
     async deleteSession(sessionId) {
         let protocol;
         try {
             let otherSessionsData;
-            const dstSession = await sessionsListGuard.acquire(AppiumDriver.name, () => {
-                if (!this.sessions[sessionId]) {
-                    return;
-                }
+            let dstSession;
+            if (this.sessions[sessionId]) {
                 const curConstructorName = this.sessions[sessionId].constructor.name;
                 otherSessionsData = lodash_1.default.toPairs(this.sessions)
                     .filter(([key, value]) => value.constructor.name === curConstructorName && key !== sessionId)
                     .map(([, value]) => value.driverData);
-                const dstSession = this.sessions[sessionId];
+                dstSession = this.sessions[sessionId];
                 protocol = dstSession.protocol;
                 this.log.info(`Removing session ${sessionId} from our master session list`);
                 // regardless of whether the deleteSession completes successfully or not
@@ -447,8 +388,7 @@ class AppiumDriver extends base_driver_1.DriverCore {
                 delete this.sessions[sessionId];
                 delete this.sessionPlugins[sessionId];
                 this.cleanupBidiSockets(sessionId);
-                return dstSession;
-            });
+            }
             // this may not be correct, but if `dstSession` was falsy, the call to `deleteSession()` would
             // throw anyway.
             if (!dstSession) {
@@ -460,13 +400,18 @@ class AppiumDriver extends base_driver_1.DriverCore {
             };
         }
         catch (e) {
-            this.log.error(`Had trouble ending session ${sessionId}: ${e.message}`);
+            const msg = e instanceof Error ? e.message : String(e);
+            this.log.error(`Had trouble ending session ${sessionId}: ${msg}`);
             return {
                 protocol,
-                error: e,
+                error: e instanceof Error ? e : new Error(msg),
             };
         }
     }
+    /**
+     * Ends every active session, either by normal `deleteSession` or by `startUnexpectedShutdown`
+     * when `force` is true.
+     */
     async deleteAllSessions(opts = {}) {
         const sessionsCount = lodash_1.default.size(this.sessions);
         if (0 === sessionsCount) {
@@ -476,7 +421,7 @@ class AppiumDriver extends base_driver_1.DriverCore {
         const { force = false, reason } = opts;
         this.log.debug(`Cleaning up ${support_1.util.pluralize('active session', sessionsCount, true)}`);
         const cleanupPromises = force
-            ? lodash_1.default.values(this.sessions).map((drv) => drv.startUnexpectedShutdown(reason && new Error(reason)))
+            ? lodash_1.default.values(this.sessions).map((drv) => drv.startUnexpectedShutdown(reason ? new Error(reason) : undefined))
             : lodash_1.default.keys(this.sessions).map((id) => this.deleteSession(id));
         for (const cleanupPromise of cleanupPromises) {
             try {
@@ -488,16 +433,20 @@ class AppiumDriver extends base_driver_1.DriverCore {
         }
     }
     /**
-     * Get the appropriate plugins for a session (or sessionless plugins)
-     *
-     * @param {string|null} [sessionId=null] - the sessionId (or null) to use to find plugins
-     * @returns {Array<import('@appium/types').Plugin>} - array of plugin instances
+     * Plugin instances for a session id, or the shared sessionless list when `sessionId` is null.
+     * Lazily builds sessionless instances on first use.
      */
     pluginsForSession(sessionId = null) {
         if (sessionId) {
+            const existingPlugins = this.sessionPlugins[sessionId];
+            if (existingPlugins) {
+                return existingPlugins;
+            }
             const driver = this.sessions[sessionId];
-            return this.sessionPlugins[sessionId]
-                ?? (driver ? this.createPluginInstances((0, base_driver_1.generateDriverLogPrefix)(driver)) : []);
+            if (!driver) {
+                return [];
+            }
+            return (this.sessionPlugins[sessionId] = this.createPluginInstances((0, base_driver_1.generateDriverLogPrefix)(driver)));
         }
         if (lodash_1.default.isEmpty(this.sessionlessPlugins)) {
             this.sessionlessPlugins = this.createPluginInstances();
@@ -505,14 +454,8 @@ class AppiumDriver extends base_driver_1.DriverCore {
         return this.sessionlessPlugins;
     }
     /**
-     * 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
+     * Plugins that declare a method named `cmd` or a generic `handle` method, scoped to the given
+     * session (or sessionless when `sessionId` is null).
      */
     pluginsToHandleCmd(cmd, sessionId = null) {
         // to handle a given command, a plugin should either implement that command as a plugin
@@ -520,29 +463,25 @@ class AppiumDriver extends base_driver_1.DriverCore {
         return this.pluginsForSession(sessionId).filter((p) => lodash_1.default.isFunction(p[cmd]) || lodash_1.default.isFunction(p.handle));
     }
     /**
-     * Creates instances of all of the enabled Plugin classes
-     * @param {string|null} [driverId=null] - ID to use for linking a driver to a plugin in logs
-     * @returns {Plugin[]}
+     * One instance per registered plugin class. `driverId` becomes the plugin log prefix segment
+     * when tied to a session driver; use `null` for sessionless plugins.
      */
     createPluginInstances(driverId = null) {
-        /** @type {Plugin[]} */
         const pluginInstances = [];
         for (const [PluginClass, name] of this.pluginClasses.entries()) {
             const cliArgs = this.getCliArgsForPlugin(name);
             const plugin = new PluginClass(name, cliArgs, driverId);
-            if (lodash_1.default.isFunction(/** @type {Plugin & ExtensionCore} */ (plugin).updateBidiCommands)) {
-                // some old plugin classes don't have `updateBidiCommands`
-                /** @type {Plugin & ExtensionCore} */ (plugin).updateBidiCommands(PluginClass.newBidiCommands ?? {});
+            const extPlugin = plugin;
+            if (lodash_1.default.isFunction(extPlugin.updateBidiCommands)) {
+                extPlugin.updateBidiCommands(PluginClass.newBidiCommands ?? {});
             }
             pluginInstances.push(plugin);
         }
         return pluginInstances;
     }
     /**
-     *
-     * @param {string} cmd
-     * @param  {...any} args
-     * @returns {Promise<{value: any, error?: Error, protocol: string} | import('type-fest').AsyncReturnType<ExternalDriver['executeCommand']>>}
+     * Dispatches a WebDriver/Appium command: may run on this driver, a session’s inner driver, or
+     * through a plugin chain, and normalizes the return value into a protocol-shaped result.
      */
     async executeCommand(cmd, ...args) {
         // We have basically three cases for how to handle commands:
@@ -568,12 +507,11 @@ class AppiumDriver extends base_driver_1.DriverCore {
         let sessionId = null;
         let dstSession = null;
         let protocol = null;
-        /** @type {this | ExternalDriver} */
         // eslint-disable-next-line @typescript-eslint/no-this-alias
         let driver = this;
         if (isSessionCmd) {
             sessionId = lodash_1.default.last(args);
-            dstSession = this.sessions[sessionId];
+            dstSession = this.sessions[sessionId] ?? null;
             if (!dstSession) {
                 throw new Error(`The session with id '${sessionId}' does not exist`);
             }
@@ -630,8 +568,10 @@ class AppiumDriver extends base_driver_1.DriverCore {
                 // not the platform driver
                 return await base_driver_1.BaseDriver.prototype.executeCommand.call(this, cmd, ...args);
             }
-            // here we know that we are executing a session command, and have a valid session driver
-            return await /** @type {any} */ (dstSession).executeCommand(cmd, ...args);
+            if (!dstSession) {
+                throw new Error('Internal error: session command without a session driver');
+            }
+            return await dstSession.executeCommand(cmd, ...args);
         };
         // now take our default behavior, wrap it with any number of plugin behaviors, and run it
         const wrappedCmd = this.wrapCommandWithPlugins({
@@ -661,21 +601,22 @@ class AppiumDriver extends base_driver_1.DriverCore {
         // previously sessionless to use the new sessionId, so that plugins can share state between
         // their createSession method and other instance methods
         if (cmd === base_driver_1.CREATE_SESSION_COMMAND && this.sessionlessPlugins.length && !res.error) {
-            const sessionId = lodash_1.default.first(res.value);
+            const newSessionId = lodash_1.default.first(res.value);
             this.log.info(`Promoting ${this.sessionlessPlugins.length} sessionless plugins to be attached ` +
-                `to session ID ${sessionId}`);
-            this.sessionPlugins[sessionId] = this.sessionlessPlugins;
-            for (const p of /** @type {(Plugin & ExtensionCore)[]} */ (this.sessionPlugins[sessionId])) {
+                `to session ID ${newSessionId}`);
+            this.sessionPlugins[newSessionId] = this.sessionlessPlugins;
+            const promoted = this.sessionPlugins[newSessionId];
+            for (const p of promoted) {
                 if (lodash_1.default.isFunction(p.updateLogPrefix)) {
-                    // some old plugin classes don't have `updateLogPrefix` yet
-                    p.updateLogPrefix(`${(0, base_driver_1.generateDriverLogPrefix)(p)} <${(0, base_driver_1.generateDriverLogPrefix)(this.sessions[sessionId])}>`);
+                    p.updateLogPrefix(`${(0, base_driver_1.generateDriverLogPrefix)(p)} <${(0, base_driver_1.generateDriverLogPrefix)(this.sessions[newSessionId])}>`);
                 }
             }
             this.sessionlessPlugins = [];
         }
         return res;
     }
-    wrapCommandWithPlugins({ driver, cmd, args, next, cmdHandledBy, plugins }) {
+    /** Builds an async chain: each plugin wraps `next` until the default driver behavior runs. */
+    wrapCommandWithPlugins({ driver, cmd, args, next, cmdHandledBy, plugins, }) {
         if (plugins.length) {
             this.log.info(`Plugins which can handle cmd '${cmd}': ${plugins.map((p) => p.name)}`);
         }
@@ -690,15 +631,20 @@ class AppiumDriver extends base_driver_1.DriverCore {
                 this.log.info(`Plugin ${plugin.name} is now handling cmd '${cmd}'`);
                 cmdHandledBy[plugin.name] = true; // if we make it here, this plugin has attempted to handle cmd
                 // first attempt to handle the command via a command-specific handler on the plugin
-                if (plugin[cmd]) {
-                    return await plugin[cmd](_next, driver, ...args);
+                const cmdHandler = plugin[cmd];
+                if (lodash_1.default.isFunction(cmdHandler)) {
+                    // Command methods must run with plugin as `this` (detached property access drops binding).
+                    return await cmdHandler.call(plugin, _next, driver, ...args);
+                }
+                if (!lodash_1.default.isFunction(plugin.handle)) {
+                    throw new Error(`Plugin ${plugin.name} cannot handle command '${cmd}'`);
                 }
-                // otherwise, call the generic 'handle' method
                 return await plugin.handle(_next, driver, cmd, ...args);
             })(next);
         }
         return next;
     }
+    /** After a command with plugins, logs which handlers ran vs. were skipped (debugging aid). */
     logPluginHandlerReport(plugins, { cmd, cmdHandledBy }) {
         if (!plugins.length) {
             return;
@@ -717,8 +663,11 @@ class AppiumDriver extends base_driver_1.DriverCore {
                 `command *was* handled by these: ${JSON.stringify(didHandle)}.`);
         }
     }
-    async executeWrappedCommand({ wrappedCmd, protocol }) {
-        let cmdRes, cmdErr, res = {};
+    /** Runs the wrapped plugin chain and merges the result into a `SessionHandlerResult` shape. */
+    async executeWrappedCommand({ wrappedCmd, protocol, }) {
+        let cmdRes;
+        let cmdErr;
+        const res = {};
         try {
             // At this point, `wrappedCmd` defines a whole sequence of plugin handlers, culminating in
             // our default handler. Whatever it returns is what we're going to want to send back to the
@@ -732,64 +681,37 @@ class AppiumDriver extends base_driver_1.DriverCore {
         // object, or a protocol-aware object with protocol and error/value keys. So we need to sniff
         // it and make sure we don't double-wrap it if it's the latter kind.
         if (lodash_1.default.isPlainObject(cmdRes) && lodash_1.default.has(cmdRes, 'protocol')) {
-            res = cmdRes;
+            Object.assign(res, cmdRes);
         }
         else {
             res.value = cmdRes;
-            res.error = cmdErr;
-            res.protocol = protocol;
+            res.error = cmdErr instanceof Error ? cmdErr : undefined;
+            res.protocol = protocol ?? undefined;
         }
         return res;
     }
+    /** Whether the inner session driver is actively proxying for this session id. */
     proxyActive(sessionId) {
         const dstSession = this.sessions[sessionId];
-        return dstSession && lodash_1.default.isFunction(dstSession.proxyActive) && dstSession.proxyActive(sessionId);
+        return lodash_1.default.isFunction(dstSession?.proxyActive) && dstSession.proxyActive(sessionId);
     }
-    /**
-     *
-     * @param {string} sessionId
-     * @returns {import('@appium/types').RouteMatcher[]}
-     */
+    /** URL patterns the session driver does not want proxied; empty if no session or no list. */
     getProxyAvoidList(sessionId) {
         const dstSession = this.sessions[sessionId];
-        return dstSession ? dstSession.getProxyAvoidList() : [];
+        return lodash_1.default.isFunction(dstSession?.getProxyAvoidList) ? dstSession.getProxyAvoidList() : [];
     }
+    /** Whether the session driver supports proxying for this session. */
     canProxy(sessionId) {
         const dstSession = this.sessions[sessionId];
-        return dstSession && dstSession.canProxy(sessionId);
+        return lodash_1.default.isFunction(dstSession?.canProxy) && dstSession.canProxy(sessionId);
     }
-    onBidiConnection = bidiCommands.onBidiConnection;
-    onBidiMessage = bidiCommands.onBidiMessage;
-    onBidiServerError = bidiCommands.onBidiServerError;
-    cleanupBidiSockets = bidiCommands.cleanupBidiSockets;
-    configureGlobalFeatures = insecureFeatures.configureGlobalFeatures;
-    configureDriverFeatures = insecureFeatures.configureDriverFeatures;
-    listCommands = inspectorCommands.listCommands;
-    listExtensions = inspectorCommands.listExtensions;
 }
 exports.AppiumDriver = AppiumDriver;
-/**
- * Help decide which commands should be proxied to sub-drivers and which
- * should be handled by this, our umbrella driver
- * @param {string} cmd
- * @returns {boolean}
- */
-function isAppiumDriverCommand(cmd) {
-    return !(0, base_driver_1.isSessionCommand)(cmd)
-        || lodash_1.default.includes([
-            base_driver_1.DELETE_SESSION_COMMAND,
-            base_driver_1.LIST_DRIVER_COMMANDS_COMMAND,
-            base_driver_1.LIST_DRIVER_EXTENSIONS_COMMAND,
-        ], cmd);
-}
 /**
  * Thrown when Appium tried to proxy a command using a driver's `proxyCommand` method but the
  * method did not exist
  */
 class NoDriverProxyCommandError extends Error {
-    /**
-     * @type {Readonly<string>}
-     */
     code = 'APPIUMERR_NO_DRIVER_PROXYCOMMAND';
     constructor() {
         super(`The default behavior for this command was to proxy, but the driver ` +
@@ -799,48 +721,13 @@ class NoDriverProxyCommandError extends Error {
     }
 }
 exports.NoDriverProxyCommandError = NoDriverProxyCommandError;
-/**
- * @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').PluginType} PluginType
- * @typedef {import('@appium/types').DriverType} DriverType
- * @typedef {import('@appium/types').StringRecord} StringRecord
- * @typedef {import('@appium/types').ExternalDriver} ExternalDriver
- * @typedef {import('@appium/types').PluginClass} PluginClass
- * @typedef {import('@appium/types').Plugin} Plugin
- * @typedef {import('@appium/base-driver').ExtensionCore} ExtensionCore
- * @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
- */
-/**
- * Used by {@linkcode AppiumDriver.createSession} and {@linkcode AppiumDriver.deleteSession} to describe
- * result.
- * @template V
- * @typedef SessionHandlerResult
- * @property {V} [value]
- * @property {Error} [error]
- * @property {string} [protocol]
- */
-/**
- * @typedef {typeof desiredCapabilityConstraints} AppiumDriverConstraints
- * @typedef {import('@appium/types').W3CDriverCaps<AppiumDriverConstraints>} W3CAppiumDriverCaps
- */
+/** True if `cmd` should run on the umbrella driver instead of only on the session’s inner driver. */
+function isAppiumDriverCommand(cmd) {
+    return !(0, base_driver_1.isSessionCommand)(cmd)
+        || lodash_1.default.includes([
+            base_driver_1.DELETE_SESSION_COMMAND,
+            base_driver_1.LIST_DRIVER_COMMANDS_COMMAND,
+            base_driver_1.LIST_DRIVER_EXTENSIONS_COMMAND,
+        ], cmd);
+}
 //# sourceMappingURL=appium.js.map