@appium/base-driver 10.2.2 → 10.4.0

package/lib/basedriver/commands/execute.ts

@@ -8,9 +8,9 @@ import type {
   IExecuteCommands,
   StringRecord,
 } from '@appium/types';
+import {rankLevenshteinCandidates} from '../../helpers/levenshtein-match';
 import {mixin} from './mixin';
 import type {BaseDriver} from '../driver';
-import {distance} from 'fastest-levenshtein';
 
 declare module '../driver' {
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
@@ -34,30 +34,19 @@ const ExecuteCommands: IExecuteCommands = {
           `The current driver version does not define any execute methods.`
         );
       }
-      const matchesMap: StringRecord<string[]> = availableScripts
-        .map((name) => [distance(script, name), name])
-        .reduce((acc, [key, value]) => {
-          if (key in acc) {
-            acc[key].push(value);
-          } else {
-            acc[key] = [value];
-          }
-          return acc;
-        }, {});
-      const sortedMatches = _.flatten(
-        _.keys(matchesMap)
-          .sort((a, b) => parseInt(a, 10) - parseInt(b, 10))
-          .map((x) => matchesMap[x])
-      );
+      const {sorted: sortedMatches, suggestion} = rankLevenshteinCandidates(script, availableScripts);
       throw new errors.UnsupportedOperationError(
-        `Unsupported execute method '${script}', did you mean '${sortedMatches[0]}'? ` +
+        (suggestion
+          ? `Unsupported execute method '${script}', did you mean '${suggestion}'? `
+          : `Unsupported execute method '${script}'. `) +
         `Make sure the installed ${Driver.name} is up-to-date. ` +
         `Execute methods available in the current driver version are: ` +
         sortedMatches.join(', ')
       );
     }
     const args = validateExecuteMethodParams(protoArgs as any[], commandMetadata.params);
-    const command = this[commandMetadata.command] as DriverCommand;
+    const commandName = commandMetadata.command as keyof BaseDriver<C>;
+    const command = this[commandName] as DriverCommand;
     return await command.call(this, ...args);
   },
 };

package/lib/basedriver/core.ts

@@ -77,19 +77,10 @@ export class DriverCore<const C extends Constraints, Settings extends StringReco
 
   noCommandTimer: NodeJS.Timeout | null;
 
-  protected _eventHistory: EventHistory;
-
-  /**
-   * TODO: remove this._log and use this.log instead
-   */
-  protected _log: AppiumLogger;
-
   shutdownUnexpectedly: boolean;
 
   shouldValidateCaps: boolean;
 
-  protected commandsQueueGuard: AsyncLock;
-
   /**
    * settings should be instantiated by drivers which extend BaseDriver, but
    * we set it to an empty DeviceSettings instance here to make sure that the
@@ -100,6 +91,15 @@ export class DriverCore<const C extends Constraints, Settings extends StringReco
 
   protocol?: Protocol;
 
+  protected _eventHistory: EventHistory;
+
+  /**
+   * TODO: remove this._log and use this.log instead
+   */
+  protected _log: AppiumLogger;
+
+  protected commandsQueueGuard: AsyncLock;
+
   constructor(opts: InitialOpts = <InitialOpts>{}, shouldValidateCaps = true) {
     super();
     this._log = this.log; // TODO: remove references to this._log and use this.log instead
@@ -136,19 +136,6 @@ export class DriverCore<const C extends Constraints, Settings extends StringReco
     this.settings = new DeviceSettings();
   }
 
-  /**
-   * Set a callback handler if needed to execute a custom piece of code
-   * when the driver is shut down unexpectedly. Multiple calls to this method
-   * will cause the handler to be executed multiple times
-   *
-   * @param handler The code to be executed on unexpected shutdown.
-   * The function may accept one argument, which is the actual error instance, which
-   * caused the driver to shut down.
-   */
-  onUnexpectedShutdown(handler: (...args: any[]) => void) {
-    this.eventEmitter.on(ON_UNEXPECTED_SHUTDOWN_EVENT, handler);
-  }
-
   /**
    * This property is used by AppiumDriver to store the data of the
    * specific driver sessions. This data can be later used to adjust
@@ -182,6 +169,31 @@ export class DriverCore<const C extends Constraints, Settings extends StringReco
     return _.cloneDeep(this._eventHistory);
   }
 
+  /**
+   * If this driver has requested proxying of bidi connections to an upstream bidi endpoint, this
+   * method should be overridden to return the URL of that websocket, to indicate that bidi
+   * proxying is enabled. Otherwise, a null return will indicate that bidi proxying should not be
+   * active and bidi commands will be handled by this driver.
+   *
+   * @returns {string | null}
+   */
+  get bidiProxyUrl(): string | null {
+    return null;
+  }
+
+  /**
+   * Set a callback handler if needed to execute a custom piece of code
+   * when the driver is shut down unexpectedly. Multiple calls to this method
+   * will cause the handler to be executed multiple times
+   *
+   * @param handler The code to be executed on unexpected shutdown.
+   * The function may accept one argument, which is the actual error instance, which
+   * caused the driver to shut down.
+   */
+  onUnexpectedShutdown(handler: (...args: any[]) => void) {
+    this.eventEmitter.on(ON_UNEXPECTED_SHUTDOWN_EVENT, handler);
+  }
+
   /**
    * API method for driver developers to log timings for important events
    */
@@ -327,18 +339,6 @@ export class DriverCore<const C extends Constraints, Settings extends StringReco
     }
   }
 
-  /**
-   * If this driver has requested proxying of bidi connections to an upstream bidi endpoint, this
-   * method should be overridden to return the URL of that websocket, to indicate that bidi
-   * proxying is enabled. Otherwise, a null return will indicate that bidi proxying should not be
-   * active and bidi commands will be handled by this driver.
-   *
-   * @returns {string | null}
-   */
-  get bidiProxyUrl(): string | null {
-    return null;
-  }
-
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
   proxyActive(sessionId: string): boolean {
     return false;

package/lib/basedriver/driver.ts

@@ -20,6 +20,7 @@ import {
 import B from 'bluebird';
 import _ from 'lodash';
 import {fixCaps, isW3cCaps} from '../helpers/capabilities';
+import {getLevenshteinSuggestion} from '../helpers/levenshtein-match';
 import {calcSignature} from '../helpers/session';
 import {DELETE_SESSION_COMMAND, determineProtocol, errors} from '../protocol';
 import {processCapabilities, validateCaps} from './capabilities';
@@ -396,11 +397,17 @@ export class BaseDriver<
   }
 
   logExtraCaps(caps: Capabilities<C>) {
-    const extraCaps = _.difference(_.keys(caps), _.keys(this._desiredCapConstraints));
+    const knownCaps = _.keys(this._desiredCapConstraints);
+    const extraCaps = _.difference(_.keys(caps), knownCaps);
     if (extraCaps.length) {
       this.log.warn(`The following provided capabilities were not recognized by this driver:`);
       for (const cap of extraCaps) {
-        this.log.warn(`  ${cap}`);
+        const suggestion = getLevenshteinSuggestion(cap, knownCaps);
+        this.log.warn(
+          suggestion
+            ? `  ${cap} (did you mean '${suggestion}'?)`
+            : `  ${cap}`,
+        );
       }
     }
   }

package/lib/basedriver/extension-core.ts

@@ -18,9 +18,9 @@ export class ExtensionCore {
   bidiEventSubs: Record<string, string[]>;
   bidiCommands: BidiModuleMap = BIDI_COMMANDS as BidiModuleMap;
   _logPrefix?: string;
-  protected _log: AppiumLogger;
   // used to handle driver events
   readonly eventEmitter: NodeJS.EventEmitter;
+  protected _log: AppiumLogger;
 
 
   constructor(logPrefix?: string) {

package/lib/basedriver/helpers.ts

@@ -36,7 +36,7 @@ const APPLICATIONS_CACHE = new LRUCache<string, CachedAppInfoEntry>({
         `expired after ${CACHED_APPS_MAX_AGE_MS}ms`
     );
     if (fullPath) {
-      fs.rimraf(fullPath);
+      void fs.rimraf(fullPath);
     }
   },
   noDisposeOnSet: true,
@@ -67,6 +67,25 @@ process.on('exit', () => {
   }
 });
 
+interface RemoteAppProps {
+  lastModified: Date | null;
+  immutable: boolean;
+  maxAge: number | null;
+  etag: string | null;
+}
+
+interface RemoteAppData {
+  status: number;
+  stream: Readable;
+  headers: AxiosResponseHeaders | RawAxiosRequestHeaders;
+}
+
+/** Cache value we store (extends CachedAppInfo with optional packageHash) */
+interface CachedAppInfoEntry extends Omit<CachedAppInfo, 'packageHash'> {
+  packageHash?: string | null;
+  fullPath?: string;
+}
+
 /**
  * Performs initial application package configuration so the app is ready for driver use.
  * Resolves local paths, downloads remote apps (http/https) with optional caching, and
@@ -361,19 +380,7 @@ export function generateDriverLogPrefix(obj: object | null, _sessionId?: string
   return `${obj.constructor.name}@${node.getObjectId(obj).substring(0, 4)}`;
 }
 
-// #region Private types and helpers
-interface RemoteAppProps {
-  lastModified: Date | null;
-  immutable: boolean;
-  maxAge: number | null;
-  etag: string | null;
-}
-
-interface RemoteAppData {
-  status: number;
-  stream: Readable;
-  headers: AxiosResponseHeaders | RawAxiosRequestHeaders;
-}
+// #region Private helpers
 
 function parseAppLink(appLink: string): URL | {protocol?: string; pathname?: string; href?: string; search?: string} {
   try {
@@ -562,13 +569,6 @@ function toNaturalNumber(defaultValue: number, envVarName?: string): number {
   return num > 0 ? num : defaultValue;
 }
 
-/** Cache value we store (extends CachedAppInfo with optional packageHash) */
-interface CachedAppInfoEntry extends Omit<CachedAppInfo, 'packageHash'> {
-  packageHash?: string | null;
-  fullPath?: string;
-}
-// #endregion
-
 export default {
   configureApp,
   isPackageOrBundle,

package/lib/helpers/levenshtein-match.ts

@@ -0,0 +1,74 @@
+import type {StringRecord} from '@appium/types';
+import {distance} from 'fastest-levenshtein';
+import _ from 'lodash';
+
+/**
+ * Inclusive maximum Levenshtein edit distance for offering a "did you mean" hint.
+ * Matches with distance greater than this value are treated as unrelated.
+ */
+export const LEVENSHTEIN_SUGGESTION_MAX_EDIT_DISTANCE = 2;
+
+export interface LevenshteinRankResult {
+  /** Candidates sorted by ascending edit distance from `target`, then alphabetically within ties. */
+  sorted: string[];
+  /** Closest name only if its edit distance is at most `maxEditDistance` (inclusive). */
+  suggestion: string | undefined;
+}
+
+/**
+ * Sorts candidates by Levenshtein distance from `target` and optionally picks a suggestion
+ * when the closest match is within `maxEditDistance` edits (single pass over candidates).
+ */
+export function rankLevenshteinCandidates(
+  target: string,
+  candidates: readonly string[],
+  maxEditDistance: number = LEVENSHTEIN_SUGGESTION_MAX_EDIT_DISTANCE,
+): LevenshteinRankResult {
+  if (!candidates.length) {
+    return {sorted: [], suggestion: undefined};
+  }
+
+  const matchesMap: StringRecord<string[]> = candidates
+    .map((name) => [distance(target, name), name] as const)
+    .reduce((acc, [dist, name]) => {
+      const key = String(dist);
+      if (key in acc) {
+        acc[key].push(name);
+      } else {
+        acc[key] = [name];
+      }
+      return acc;
+    }, {});
+  const sortedDistanceKeys = _.keys(matchesMap).sort((a, b) => parseInt(a, 10) - parseInt(b, 10));
+  const sorted = _.flatten(
+    sortedDistanceKeys.map((k) => (matchesMap[k] ?? []).sort()),
+  );
+
+  const best = sorted[0];
+  const firstDistanceKey = sortedDistanceKeys[0];
+  const minDist = firstDistanceKey !== undefined ? parseInt(firstDistanceKey, 10) : NaN;
+  const suggestion = maxEditDistance >= 0 && best !== undefined && !Number.isNaN(minDist) && minDist <= maxEditDistance
+      ? best
+      : undefined;
+  return {sorted, suggestion};
+}
+
+/**
+ * Sorts strings by ascending Levenshtein distance from `target`.
+ * Strings with the same distance are sorted alphabetically.
+ */
+export function sortByLevenshteinDistance(target: string, candidates: readonly string[]): string[] {
+  return rankLevenshteinCandidates(target, candidates, Number.POSITIVE_INFINITY).sorted;
+}
+
+/**
+ * Returns the closest string in `candidates` by Levenshtein distance only if that
+ * distance is at most `maxEditDistance` (inclusive).
+ */
+export function getLevenshteinSuggestion(
+  target: string,
+  candidates: readonly string[],
+  maxEditDistance: number = LEVENSHTEIN_SUGGESTION_MAX_EDIT_DISTANCE,
+): string | undefined {
+  return rankLevenshteinCandidates(target, candidates, maxEditDistance).suggestion;
+}

package/lib/jsonwp-proxy/protocol-converter.ts

@@ -69,14 +69,14 @@ export class ProtocolConverter {
     return this._log ?? DEFAULT_LOG;
   }
 
-  set downstreamProtocol(value: string | null | undefined) {
-    this._downstreamProtocol = value;
-  }
-
   get downstreamProtocol(): string | null | undefined {
     return this._downstreamProtocol;
   }
 
+  set downstreamProtocol(value: string | null | undefined) {
+    this._downstreamProtocol = value;
+  }
+
   /**
    * Handle "crossing" endpoints for the case when upstream and downstream
    * drivers operate different protocols.