CHANGELOG.md

@@ -1,3 +1,9 @@
+## [1.4.2](https://github.com/appium/appium-geckodriver/compare/v1.4.1...v1.4.2) (2025-02-02)
+
+### Miscellaneous Chores
+
+* Improve typing ([#128](https://github.com/appium/appium-geckodriver/issues/128)) ([cbf8a7e](https://github.com/appium/appium-geckodriver/commit/cbf8a7e36bdb4206d553662e9494b3545e4d2da1))
+
 ## [1.4.1](https://github.com/appium/appium-geckodriver/compare/v1.4.0...v1.4.1) (2025-01-03)
 
 ### Miscellaneous Chores

index.js

@@ -1,4 +1,4 @@
-import GeckoDriver from './lib/driver';
+import { GeckoDriver } from './lib/driver';
 
 export default GeckoDriver;
 export { GeckoDriver };

lib/commands/find.js

@@ -1,19 +1,23 @@
 import { util } from 'appium/support';
 
-
-const commands = {};
-
 // This is needed to make lookup by image working
-commands.findElOrEls = async function findElOrEls (strategy, selector, mult, context) {
-  context = util.unwrapElement(context);
-  const endpoint = `/element${context ? `/${context}/element` : ''}${mult ? 's' : ''}`;
-
+/**
+ *
+ * @this {GeckoDriver}
+ * @param {string} strategy
+ * @param {string} selector
+ * @param {boolean} mult
+ * @param {string} [context]
+ * @returns {Promise<any>}
+ */
+export async function findElOrEls (strategy, selector, mult, context) {
+  const endpoint = `/element${context ? `/${util.unwrapElement(context)}/element` : ''}${mult ? 's' : ''}`;
   return await this.gecko.proxy.command(endpoint, 'POST', {
     using: strategy,
     value: selector,
   });
-};
-
+}
 
-export { commands };
-export default commands;
+/**
+ * @typedef {import('../driver').GeckoDriver} GeckoDriver
+ */

lib/desired-caps.js

@@ -1,6 +1,6 @@
 import { VERBOSITY } from './constants';
 
-const desiredCapConstraints = {
+export const desiredCapConstraints = {
   browserName: {
     isString: true
   },
@@ -43,5 +43,3 @@ const desiredCapConstraints = {
     isObject: true
   }
 };
-
-export { desiredCapConstraints };

lib/driver.js

@@ -1,8 +1,8 @@
 import _ from 'lodash';
 import { BaseDriver } from 'appium/driver';
-import GeckoDriverServer from './gecko';
+import { GECKO_SERVER_HOST, GeckoDriverServer } from './gecko';
 import { desiredCapConstraints } from './desired-caps';
-import { commands } from './commands/index';
+import * as findCommands from './commands/find';
 import { formatCapsForServer } from './utils';
 
 /** @type {import('@appium/types').RouteMatcher[]} */
@@ -13,10 +13,16 @@ const NO_PROXY = [
   ['POST', new RegExp('^/session/[^/]+/elements?$')],
 ];
 
-class GeckoDriver extends BaseDriver {
+export class GeckoDriver extends BaseDriver {
   /** @type {boolean} */
   isProxyActive;
 
+  /** @type {GeckoDriverServer} */
+  gecko;
+
+  /** @type {string | null} */
+  _bidiProxyUrl;
+
   constructor (opts = {}) {
     // @ts-ignore TODO: make args typed
     super(opts);
@@ -32,16 +38,14 @@ class GeckoDriver extends BaseDriver {
       'name',
     ];
     this.resetState();
-
-    for (const [cmd, fn] of _.toPairs(commands)) {
-      GeckoDriver.prototype[cmd] = fn;
-    }
   }
 
   resetState () {
+    // @ts-ignore It's ok
     this.gecko = null;
     this.proxyReqRes = null;
     this.isProxyActive = false;
+    this._bidiProxyUrl = null;
   }
 
   proxyActive () {
@@ -61,24 +65,56 @@ class GeckoDriver extends BaseDriver {
     // @ts-ignore TODO: make args typed
     const [sessionId, caps] = await super.createSession(...args);
     this.gecko = new GeckoDriverServer(this.log, caps);
+    /** @type {import('@appium/types').StringRecord | null} */
+    let response = null;
     try {
-      await this.gecko.start(formatCapsForServer(caps));
+      response = await this.gecko.start(formatCapsForServer(caps));
     } catch (e) {
       await this.deleteSession();
       throw e;
     }
-    this.proxyReqRes = this.gecko.proxy?.proxyReqRes.bind(this.gecko.proxy);
+    this.proxyReqRes = this.gecko.proxy.proxyReqRes.bind(this.gecko.proxy);
+    this._bidiProxyUrl = this._processCreateSessionResponse(response);
+    if (this._bidiProxyUrl) {
+      this.log.info(`Set proxy BiDi URL to ${this._bidiProxyUrl}`);
+    }
     this.isProxyActive = true;
     return [sessionId, caps];
   }
 
+  /**
+   * @override
+   * @returns {string | null}
+   */
+  get bidiProxyUrl() {
+    return this._bidiProxyUrl;
+  }
+
   async deleteSession () {
     this.log.info('Ending Gecko Driver session');
     await this.gecko?.stop();
     this.resetState();
 
     await super.deleteSession();
   }
+
+  /**
+   *
+   * @param {import('@appium/types').StringRecord} response
+   * @returns {string | null}
+   */
+  _processCreateSessionResponse(response) {
+    const webSocketUrl = response?.capabilities?.webSocketUrl;
+    if (_.isEmpty(webSocketUrl) || !_.isString(webSocketUrl)) {
+      return null;
+    }
+    const asUrl = new URL(webSocketUrl);
+    return asUrl.hostname !== GECKO_SERVER_HOST
+      ? webSocketUrl.replace(asUrl.host, GECKO_SERVER_HOST)
+      : webSocketUrl;
+  }
+
+  findElOrEls = findCommands.findElOrEls;
 }
 
-export default GeckoDriver;
+export default GeckoDriver;

lib/gecko.js

@@ -24,9 +24,10 @@ const PROCESS_SPECIFIC_OPTION_NAMES_MAP = Object.freeze({
   marionettePort: 'marionettePort',
   systemPort: 'port',
 });
+export const GECKO_SERVER_HOST = '127.0.0.1';
 
 
-class GeckoProxy extends JWProxy {
+export class GeckoProxy extends JWProxy {
   /** @type {boolean|undefined} */
   didProcessExit;
 
@@ -56,6 +57,11 @@ class GeckoDriverProcess {
   /** @type {number|undefined} */
   port;
 
+  /**
+   *
+   * @param {import('@appium/types').AppiumLogger} log
+   * @param {import('@appium/types').StringRecord} opts
+   */
   constructor (log, opts = {}) {
     for (const [optName, propName] of _.toPairs(PROCESS_SPECIFIC_OPTION_NAMES_MAP)) {
       this[propName] = opts[optName];
@@ -165,22 +171,36 @@ process.once('exit', () => {
   } catch {}
 });
 
-class GeckoDriverServer {
+export class GeckoDriverServer {
+  /** @type {GeckoProxy} */
+  proxy;
+
+  /**
+   *
+   * @param {import('@appium/types').AppiumLogger} log
+   * @param {import('@appium/types').StringRecord} caps
+   */
   constructor (log, caps) {
     this.process = new GeckoDriverProcess(log, caps);
     this.log = log;
+    // @ts-ignore That's ok
     this.proxy = null;
   }
 
   get isRunning () {
     return !!(this.process?.isRunning);
   }
 
+  /**
+   *
+   * @param {import('@appium/types').StringRecord} geckoCaps
+   * @returns {Promise<import('@appium/types').StringRecord>}
+   */
   async start (geckoCaps) {
     await this.process.init();
 
     this.proxy = new GeckoProxy({
-      server: '127.0.0.1',
+      server: GECKO_SERVER_HOST,
       port: this.process.port,
       log: this.log,
       base: '',
@@ -223,13 +243,14 @@ class GeckoDriverServer {
     RUNNING_PROCESS_IDS.push(pid);
     this.process.proc?.on('exit', () => void _.pull(RUNNING_PROCESS_IDS, pid));
 
-    // @ts-ignore The body is ok
-    await this.proxy.command('/session', 'POST', {
-      capabilities: {
-        firstMatch: [{}],
-        alwaysMatch: geckoCaps,
-      }
-    });
+    return /** @type {import('@appium/types').StringRecord} */ (
+      await this.proxy.command('/session', 'POST', {
+        capabilities: {
+          firstMatch: [{}],
+          alwaysMatch: geckoCaps,
+        }
+      })
+    );
   }
 
   async stop () {

lib/utils.js

@@ -16,8 +16,14 @@ const STANDARD_CAPS = [
   'setWindowRect',
   'timeouts',
   'unhandledPromptBehavior',
+  'webSocketUrl',
 ];
 
+/**
+ *
+ * @param {import('@appium/types').StringRecord} caps
+ * @returns {import('@appium/types').StringRecord}
+ */
 export function formatCapsForServer (caps) {
   const result = {};
   if (caps.browserName) {

package.json

@@ -7,7 +7,7 @@
     "seamonkey",
     "firefox"
   ],
-  "version": "1.4.1",
+  "version": "1.4.2",
   "author": "Appium Contributors",
   "license": "Apache-2.0",
   "repository": {

test/unit/driver-specs.js

@@ -1,4 +1,4 @@
-import GeckoDriver from '../../lib/driver';
+import { GeckoDriver } from '../../lib/driver';
 
 describe('GeckoDriver', function () {
   let chai;