appium-geckodriver 2.1.11 → 2.2.0

package/lib/commands/find.ts

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

package/lib/constants.ts

@@ -2,3 +2,13 @@ export const VERBOSITY = {
   DEBUG: 'debug',
   TRACE: 'trace',
 } as const;
+
+/**
+ * Insecure feature flag name which must be enabled on the Appium server
+ * in order to use the `geckodriverExecutable` capability.
+ *
+ * Note: when starting the Appium server, this feature must be referenced
+ * with the automation name prefix (for example
+ * `--allow-insecure gecko:custom_geckodriver_executable`).
+ */
+export const INSECURE_FEAT_CUSTOM_GECKODRIVER_EXECUTABLE = 'custom_geckodriver_executable' as const;

package/lib/desired-caps.ts

@@ -1,49 +1,51 @@
-import type { Constraints } from '@appium/types';
-import { VERBOSITY } from './constants';
+import type {Constraints} from '@appium/types';
+import {VERBOSITY} from './constants';
 
 const DESIRED_CAP_CONSTRAINTS = {
   browserName: {
-    isString: true
+    isString: true,
   },
   browserVersion: {
-    isString: true
+    isString: true,
   },
   acceptInsecureCerts: {
-    isBoolean: true
+    isBoolean: true,
   },
   pageLoadStrategy: {
-    isString: true
+    isString: true,
   },
   proxy: {
-    isObject: true
+    isObject: true,
   },
   setWindowRect: {
-    isBoolean: true
+    isBoolean: true,
   },
   timeouts: {
-    isObject: true
+    isObject: true,
   },
   unhandledPromptBehavior: {
-    isString: true
+    isString: true,
   },
   systemPort: {
-    isNumber: true
+    isNumber: true,
   },
   marionettePort: {
-    isNumber: true
+    isNumber: true,
+  },
+  geckodriverExecutable: {
+    isString: true,
   },
   verbosity: {
     isString: true,
-    inclusionCaseInsensitive: Object.values(VERBOSITY) as [string, ...string[]]
+    inclusionCaseInsensitive: Object.values(VERBOSITY) as [string, ...string[]],
   },
   androidStorage: {
     isString: true,
-    inclusionCaseInsensitive: ['auto', 'app', 'internal', 'sdcard']
+    inclusionCaseInsensitive: ['auto', 'app', 'internal', 'sdcard'],
   },
   'moz:firefoxOptions': {
-    isObject: true
-  }
+    isObject: true,
+  },
 } as const satisfies Constraints;
 
 export const desiredCapConstraints = DESIRED_CAP_CONSTRAINTS;
-

package/lib/doctor/optional-checks.ts

@@ -78,7 +78,9 @@ export class AndroidSdkCheck implements IDoctorCheck {
     const listOfTools = this.TOOL_NAMES.join(', ');
     const sdkRoot = getSdkRootFromEnv();
     if (!sdkRoot) {
-      return doctor.nokOptional(`${listOfTools} could not be found because ANDROID_HOME is NOT set!`);
+      return doctor.nokOptional(
+        `${listOfTools} could not be found because ANDROID_HOME is NOT set!`,
+      );
     }
 
     this.log.info(`   Checking ${listOfTools}`);
@@ -92,7 +94,9 @@ export class AndroidSdkCheck implements IDoctorCheck {
     }
 
     if (missingBinaries.length > 0) {
-      return doctor.nokOptional(`${missingBinaries.join(', ')} could NOT be found in '${sdkRoot}'!`);
+      return doctor.nokOptional(
+        `${missingBinaries.join(', ')} could NOT be found in '${sdkRoot}'!`,
+      );
     }
 
     return doctor.okOptional(`${listOfTools} exist in '${sdkRoot}'`);
@@ -115,4 +119,3 @@ export class AndroidSdkCheck implements IDoctorCheck {
   }
 }
 export const androidSdkCheck = new AndroidSdkCheck();
-

package/lib/doctor/required-checks.ts

@@ -33,4 +33,3 @@ export class GeckodriverCheck implements IDoctorCheck {
   }
 }
 export const geckodriverCheck = new GeckodriverCheck();
-

package/lib/doctor/utils.ts

@@ -12,4 +12,3 @@ export async function resolveExecutablePath(cmd: string): Promise<string | null>
   } catch {}
   return null;
 }
-

package/lib/driver.ts

@@ -7,11 +7,12 @@ import type {
   ExternalDriver,
   W3CDriverCaps,
 } from '@appium/types';
-import { BaseDriver } from 'appium/driver';
-import { GECKO_SERVER_HOST, GeckoDriverServer } from './gecko';
-import { desiredCapConstraints } from './desired-caps';
+import {BaseDriver, errors} from 'appium/driver';
+import {GECKO_SERVER_HOST, GeckoDriverServer} from './gecko';
+import {desiredCapConstraints} from './desired-caps';
+import {INSECURE_FEAT_CUSTOM_GECKODRIVER_EXECUTABLE} from './constants';
 import * as findCommands from './commands/find';
-import { formatCapsForServer } from './utils';
+import {formatCapsForServer} from './utils';
 
 const NO_PROXY: RouteMatcher[] = [
   ['GET', new RegExp('^/session/[^/]+/appium')],
@@ -31,7 +32,7 @@ export class GeckoDriver
   private _bidiProxyUrl: string | null = null;
   public proxyReqRes: (...args: any) => any;
 
-  constructor (opts: InitialOpts = {} as InitialOpts) {
+  constructor(opts: InitialOpts = {} as InitialOpts) {
     super(opts);
     this.desiredCapConstraints = _.cloneDeep(desiredCapConstraints);
     this.locatorStrategies = [
@@ -48,26 +49,45 @@ export class GeckoDriver
   }
 
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  override proxyActive (sessionId?: string): boolean {
+  override proxyActive(sessionId?: string): boolean {
     return this.isProxyActive;
   }
 
-  override getProxyAvoidList (): RouteMatcher[] {
+  override getProxyAvoidList(): RouteMatcher[] {
     return NO_PROXY;
   }
 
-  override canProxy (): boolean {
+  override canProxy(): boolean {
     return true;
   }
 
-  get gecko (): GeckoDriverServer {
+  get gecko(): GeckoDriverServer {
     if (!this._gecko) {
       throw new Error('Gecko driver is not initialized');
     }
     return this._gecko;
   }
 
-  override async createSession (
+  override validateDesiredCaps(caps: any): caps is any {
+    const isValid = super.validateDesiredCaps(caps);
+    if (!isValid) {
+      return false;
+    }
+
+    if (
+      caps.geckodriverExecutable &&
+      !this.isFeatureEnabled(INSECURE_FEAT_CUSTOM_GECKODRIVER_EXECUTABLE)
+    ) {
+      throw new errors.SessionNotCreatedError(
+        `The 'geckodriverExecutable' capability requires the ` +
+          `'${INSECURE_FEAT_CUSTOM_GECKODRIVER_EXECUTABLE}' insecure feature to be enabled ` +
+          `on the Appium server.`,
+      );
+    }
+    return true;
+  }
+
+  override async createSession(
     w3cCaps1: W3CDriverCaps<GeckoConstraints>,
     w3cCaps2?: W3CDriverCaps<GeckoConstraints>,
     ...args: any[]
@@ -96,7 +116,7 @@ export class GeckoDriver
     return this._bidiProxyUrl;
   }
 
-  override async deleteSession (): Promise<void> {
+  override async deleteSession(): Promise<void> {
     this.log.info('Ending Gecko Driver session');
     await this._gecko?.stop();
     this.resetState();
@@ -104,7 +124,7 @@ export class GeckoDriver
     await super.deleteSession();
   }
 
-  private resetState (): void {
+  private resetState(): void {
     this._gecko = null;
     this.proxyReqRes = null as any;
     this.isProxyActive = false;
@@ -131,4 +151,3 @@ export class GeckoDriver
 }
 
 export default GeckoDriver;
-

package/lib/gecko.ts

@@ -1,21 +1,21 @@
 import _ from 'lodash';
 import os from 'node:os';
 import path from 'node:path';
-import { JWProxy, errors } from 'appium/driver';
-import { fs, util, system } from 'appium/support';
-import { SubProcess } from 'teen_process';
-import { waitForCondition } from 'asyncbox';
-import { findAPortNotInUse } from 'portscanner';
-import { execSync } from 'node:child_process';
-import type { AppiumLogger, StringRecord, HTTPMethod, HTTPBody } from '@appium/types';
-import { VERBOSITY } from './constants';
+import {JWProxy, errors} from 'appium/driver';
+import {fs, util, system} from 'appium/support';
+import {SubProcess} from 'teen_process';
+import {waitForCondition} from 'asyncbox';
+import {findAPortNotInUse} from 'portscanner';
+import {execSync} from 'node:child_process';
+import type {AppiumLogger, StringRecord, HTTPMethod, HTTPBody} from '@appium/types';
+import {VERBOSITY} from './constants';
 
 const GD_BINARY = `geckodriver${system.isWindows() ? '.exe' : ''}`;
 const STARTUP_TIMEOUT_MS = 10000; // 10 seconds
 const GECKO_PORT_RANGE: [number, number] = [5200, 5300];
 const GECKO_SERVER_GUARD = util.getLockFileGuard(
   path.resolve(os.tmpdir(), 'gecko_server_guard.lock'),
-  {timeout: 5, tryRecovery: true}
+  {timeout: 5, tryRecovery: true},
 );
 const DEFAULT_MARIONETTE_PORT = 2828;
 export const GECKO_SERVER_HOST = '127.0.0.1';
@@ -27,11 +27,12 @@ export interface SessionOptions {
 export class GeckoProxy extends JWProxy {
   didProcessExit?: boolean;
 
-  override async proxyCommand (url: string, method: HTTPMethod, body: HTTPBody = null) {
+  override async proxyCommand(url: string, method: HTTPMethod, body: HTTPBody = null) {
     if (this.didProcessExit) {
       throw new errors.InvalidContextError(
         `'${method} ${url}' cannot be proxied to Gecko Driver server because ` +
-        'its process is not running (probably crashed). Check the Appium log for more details');
+          'its process is not running (probably crashed). Check the Appium log for more details',
+      );
     }
     return await super.proxyCommand(url, method, body);
   }
@@ -42,32 +43,34 @@ class GeckoDriverProcess {
   private readonly verbosity?: string;
   private readonly androidStorage?: string;
   private readonly marionettePort?: number;
+  private readonly geckodriverExecutable?: string;
   private _port?: number;
   private readonly log: AppiumLogger;
   private _proc: SubProcess | null = null;
 
-  constructor (log: AppiumLogger, opts: StringRecord = {}) {
+  constructor(log: AppiumLogger, opts: StringRecord = {}) {
     this.noReset = opts.noReset;
     this.verbosity = opts.verbosity;
     this.androidStorage = opts.androidStorage;
     this.marionettePort = opts.marionettePort;
+    this.geckodriverExecutable = opts.geckodriverExecutable;
     this._port = opts.systemPort;
     this.log = log;
   }
 
-  get isRunning (): boolean {
-    return !!(this._proc?.isRunning);
+  get isRunning(): boolean {
+    return !!this._proc?.isRunning;
   }
 
-  get port (): number | undefined {
+  get port(): number | undefined {
     return this._port;
   }
 
-  get proc (): SubProcess | null {
+  get proc(): SubProcess | null {
     return this._proc;
   }
 
-  async init (): Promise<void> {
+  async init(): Promise<void> {
     if (this.isRunning) {
       return;
     }
@@ -80,19 +83,14 @@ class GeckoDriverProcess {
         } catch {
           throw new Error(
             `Cannot find any free port in range ${startPort}..${endPort}. ` +
-            `Double check the processes that are locking ports within this range and terminate ` +
-            `these which are not needed anymore or set any free port number to the 'systemPort' capability`);
+              `Double check the processes that are locking ports within this range and terminate ` +
+              `these which are not needed anymore or set any free port number to the 'systemPort' capability`,
+          );
         }
       });
     }
 
-    let driverBin: string;
-    try {
-      driverBin = await fs.which(GD_BINARY);
-    } catch {
-      throw new Error(`${GD_BINARY} binary cannot be found in PATH. ` +
-        `Please make sure it is present on your system`);
-    }
+    const driverBin = await this.resolveGeckodriverBinary();
     const args: string[] = [];
     /* #region Options */
     switch (_.toLower(this.verbosity)) {
@@ -107,8 +105,12 @@ class GeckoDriverProcess {
       args.push('--connect-existing');
       // https://firefox-source-docs.mozilla.org/testing/geckodriver/Flags.html#code-connect-existing-code
       if (_.isNil(this.marionettePort)) {
-        this.log.info(`'marionettePort' capability value is not provided while 'noReset' is enabled`);
-        this.log.info(`Assigning 'marionettePort' to the default value (${DEFAULT_MARIONETTE_PORT})`);
+        this.log.info(
+          `'marionettePort' capability value is not provided while 'noReset' is enabled`,
+        );
+        this.log.info(
+          `Assigning 'marionettePort' to the default value (${DEFAULT_MARIONETTE_PORT})`,
+        );
       }
       args.push('--marionette-port', `${this.marionettePort ?? DEFAULT_MARIONETTE_PORT}`);
     } else if (!_.isNil(this.marionettePort)) {
@@ -134,19 +136,40 @@ class GeckoDriverProcess {
     await this._proc.start(0);
   }
 
-  async stop (): Promise<void> {
+  async stop(): Promise<void> {
     if (this.isRunning) {
       await this._proc?.stop('SIGTERM');
     }
   }
 
-  async kill (): Promise<void> {
+  async kill(): Promise<void> {
     if (this.isRunning) {
       try {
         await this._proc?.stop('SIGKILL');
       } catch {}
     }
   }
+
+  private async resolveGeckodriverBinary(): Promise<string> {
+    if (this.geckodriverExecutable) {
+      if (!(await fs.exists(this.geckodriverExecutable))) {
+        throw new Error(
+          `The custom geckodriver binary at '${this.geckodriverExecutable}' cannot be found. ` +
+            `Make sure the path is correct and accessible to the Appium server process`,
+        );
+      }
+      return this.geckodriverExecutable;
+    }
+
+    try {
+      return await fs.which(GD_BINARY);
+    } catch {
+      throw new Error(
+        `${GD_BINARY} binary cannot be found in PATH. ` +
+          `Please make sure it is present on your system`,
+      );
+    }
+  }
 }
 
 const RUNNING_PROCESS_IDS: (number | undefined)[] = [];
@@ -156,7 +179,10 @@ process.once('exit', () => {
   }
 
   const command = system.isWindows()
-    ? ('taskkill.exe ' + RUNNING_PROCESS_IDS.filter((pid): pid is number => pid !== undefined).map((pid) => `/PID ${pid}`).join(' '))
+    ? 'taskkill.exe ' +
+      RUNNING_PROCESS_IDS.filter((pid): pid is number => pid !== undefined)
+        .map((pid) => `/PID ${pid}`)
+        .join(' ')
     : `kill ${RUNNING_PROCESS_IDS.filter((pid): pid is number => pid !== undefined).join(' ')}`;
   try {
     execSync(command);
@@ -168,24 +194,24 @@ export class GeckoDriverServer {
   private readonly _process: GeckoDriverProcess;
   private readonly log: AppiumLogger;
 
-  constructor (log: AppiumLogger, caps: StringRecord) {
+  constructor(log: AppiumLogger, caps: StringRecord) {
     this._process = new GeckoDriverProcess(log, caps);
     this.log = log;
     this._proxy = null;
   }
 
-  get proxy (): GeckoProxy {
+  get proxy(): GeckoProxy {
     if (!this._proxy) {
       throw new Error('Gecko proxy is not initialized');
     }
     return this._proxy;
   }
 
-  get isRunning (): boolean {
-    return !!(this._process?.isRunning);
+  get isRunning(): boolean {
+    return !!this._process?.isRunning;
   }
 
-  async start (geckoCaps: StringRecord, opts: SessionOptions = {}): Promise<StringRecord> {
+  async start(geckoCaps: StringRecord, opts: SessionOptions = {}): Promise<StringRecord> {
     await this._process.init();
 
     const proxyOpts: any = {
@@ -207,28 +233,33 @@ export class GeckoDriverServer {
     });
 
     try {
-      await waitForCondition(async () => {
-        try {
-          await this._proxy?.command('/status', 'GET');
-          return true;
-        } catch (err: any) {
-          if (this._proxy?.didProcessExit) {
-            throw new Error(err.message);
+      await waitForCondition(
+        async () => {
+          try {
+            await this._proxy?.command('/status', 'GET');
+            return true;
+          } catch (err: any) {
+            if (this._proxy?.didProcessExit) {
+              throw new Error(err.message);
+            }
+            return false;
           }
-          return false;
-        }
-      }, {
-        waitMs: STARTUP_TIMEOUT_MS,
-        intervalMs: 1000,
-      });
+        },
+        {
+          waitMs: STARTUP_TIMEOUT_MS,
+          intervalMs: 1000,
+        },
+      );
     } catch (e: any) {
       if (this._process.isRunning) {
         // avoid "frozen" processes,
         await this._process.kill();
       }
       if (/Condition unmet/.test(e.message)) {
-        throw new Error(`Gecko Driver server is not listening within ${STARTUP_TIMEOUT_MS}ms timeout. ` +
-          `Make sure it could be started manually from a terminal`);
+        throw new Error(
+          `Gecko Driver server is not listening within ${STARTUP_TIMEOUT_MS}ms timeout. ` +
+            `Make sure it could be started manually from a terminal`,
+        );
       }
       throw e;
     }
@@ -238,15 +269,15 @@ export class GeckoDriverServer {
       this._process.proc?.on('exit', () => void _.pull(RUNNING_PROCESS_IDS, pid));
     }
 
-    return await this._proxy.command('/session', 'POST', {
+    return (await this._proxy.command('/session', 'POST', {
       capabilities: {
         firstMatch: [{}],
         alwaysMatch: geckoCaps,
-      }
-    }) as StringRecord;
+      },
+    })) as StringRecord;
   }
 
-  async stop (): Promise<void> {
+  async stop(): Promise<void> {
     if (!this.isRunning) {
       this.log.info(`Gecko Driver session cannot be stopped, because the server is not running`);
       return;
@@ -270,4 +301,3 @@ export class GeckoDriverServer {
 }
 
 export default GeckoDriverServer;
-

package/lib/index.ts

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

package/lib/logger.ts

@@ -1,6 +1,5 @@
-import { logger } from 'appium/support';
+import {logger} from 'appium/support';
 
 export const log = logger.getLogger('GeckoDriver');
 
 export default log;
-

package/lib/utils.ts

@@ -1,21 +1,24 @@
 import _ from 'lodash';
-import { fs, net, zip, tempDir } from 'appium/support';
+import {fs, net, zip, tempDir} from 'appium/support';
 import tar from 'tar-stream';
 import zlib from 'node:zlib';
 import B from 'bluebird';
 import path from 'node:path';
-import type { StringRecord } from '@appium/types';
-import { STANDARD_CAPS } from 'appium/driver';
+import type {StringRecord} from '@appium/types';
+import {STANDARD_CAPS} from 'appium/driver';
 
 const GECKO_CAP_PREFIXES = ['moz:'] as const;
 
 /**
  * Format capabilities for Gecko server
  */
-export function formatCapsForServer (caps: StringRecord): StringRecord {
+export function formatCapsForServer(caps: StringRecord): StringRecord {
   const result: StringRecord = {};
   for (const [name, value] of _.toPairs(caps)) {
-    if (GECKO_CAP_PREFIXES.some((prefix) => name.startsWith(prefix)) || STANDARD_CAPS.has(name as any)) {
+    if (
+      GECKO_CAP_PREFIXES.some((prefix) => name.startsWith(prefix)) ||
+      STANDARD_CAPS.has(name as any)
+    ) {
       result[name] = value;
     }
   }
@@ -46,7 +49,11 @@ export async function mkdirp(p: string): Promise<void> {
 /**
  * Extract a specific file from a tar.gz archive
  */
-export async function extractFileFromTarGz(srcAcrhive: string, fileToExtract: string, dstPath: string): Promise<void> {
+export async function extractFileFromTarGz(
+  srcAcrhive: string,
+  fileToExtract: string,
+  dstPath: string,
+): Promise<void> {
   const chunks: Buffer[] = [];
   const extract = tar.extract();
   const extractPromise = new B<void>((resolve, reject) => {
@@ -56,7 +63,7 @@ export async function extractFileFromTarGz(srcAcrhive: string, fileToExtract: st
           chunks.push(chunk);
         });
       }
-      stream.on('end', function() {
+      stream.on('end', function () {
         next();
       });
       stream.resume();
@@ -71,16 +78,16 @@ export async function extractFileFromTarGz(srcAcrhive: string, fileToExtract: st
         }
       } else {
         return reject(
-          new Error(`The file '${fileToExtract}' could not be found in the '${srcAcrhive}' archive`)
+          new Error(
+            `The file '${fileToExtract}' could not be found in the '${srcAcrhive}' archive`,
+          ),
         );
       }
       resolve();
     });
   });
 
-  fs.createReadStream(srcAcrhive)
-    .pipe(zlib.createGunzip())
-    .pipe(extract);
+  fs.createReadStream(srcAcrhive).pipe(zlib.createGunzip()).pipe(extract);
 
   await extractPromise;
 }
@@ -88,7 +95,11 @@ export async function extractFileFromTarGz(srcAcrhive: string, fileToExtract: st
 /**
  * Extract a specific file from a zip archive
  */
-export async function extractFileFromZip(srcAcrhive: string, fileToExtract: string, dstPath: string): Promise<void> {
+export async function extractFileFromZip(
+  srcAcrhive: string,
+  fileToExtract: string,
+  dstPath: string,
+): Promise<void> {
   let didFindEntry = false;
   await zip.readEntries(srcAcrhive, async ({entry, extractEntryTo}) => {
     if (didFindEntry || entry.fileName !== fileToExtract) {
@@ -105,7 +116,8 @@ export async function extractFileFromZip(srcAcrhive: string, fileToExtract: stri
     }
   });
   if (!didFindEntry) {
-    throw new Error(`The file '${fileToExtract}' could not be found in the '${srcAcrhive}' archive`);
+    throw new Error(
+      `The file '${fileToExtract}' could not be found in the '${srcAcrhive}' archive`,
+    );
   }
 }
-