@appium/base-driver 10.6.0 → 10.7.0

package/lib/helpers/capabilities.ts

@@ -34,16 +34,17 @@ export function isW3cCaps(caps: unknown): caps is W3CCapabilities<Constraints> {
 export function fixCaps<C extends Constraints>(
   oldCaps: Record<string, unknown>,
   desiredCapConstraints: C,
-  log: AppiumLogger
+  log: AppiumLogger,
 ): Capabilities<C> {
   const caps = {...oldCaps} as Record<string, unknown>;
 
-  const logCastWarning = (prefix: string) => log.warn(`${prefix}. This may cause unexpected behavior`);
+  const logCastWarning = (prefix: string) =>
+    log.warn(`${prefix}. This may cause unexpected behavior`);
 
   // boolean capabilities can be passed in as strings 'false' and 'true'
   // which we want to translate into boolean values
   const booleanCaps = Object.keys(desiredCapConstraints).filter(
-    (key) => desiredCapConstraints[key as keyof C]?.isBoolean === true
+    (key) => desiredCapConstraints[key as keyof C]?.isBoolean === true,
   );
   for (const cap of booleanCaps) {
     const value = oldCaps[cap];
@@ -62,7 +63,7 @@ export function fixCaps<C extends Constraints>(
 
   // int capabilities are often sent in as strings by frameworks
   const intCaps = Object.keys(desiredCapConstraints).filter(
-    (key) => desiredCapConstraints[key as keyof C]?.isNumber === true
+    (key) => desiredCapConstraints[key as keyof C]?.isNumber === true,
   );
   for (const cap of intCaps) {
     const value = oldCaps[cap];

package/lib/helpers/extension-command-name.ts

@@ -11,7 +11,7 @@ import type {BaseDriver} from '../basedriver/driver';
  */
 export function resolveExecuteExtensionName<C extends Constraints>(
   this: BaseDriver<C>,
-  commandName: string
+  commandName: string,
 ): string {
   const Driver = this.constructor as DriverClass<Driver<C>>;
   const methodMap = Driver.executeMethodMap;

package/lib/helpers/levenshtein-match.ts

@@ -29,22 +29,31 @@ export function rankLevenshteinCandidates(
 
   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 = Object.keys(matchesMap).sort((a, b) => parseInt(a, 10) - parseInt(b, 10));
+    .reduce(
+      (acc, [dist, name]) => {
+        const key = String(dist);
+        if (key in acc) {
+          acc[key].push(name);
+        } else {
+          acc[key] = [name];
+        }
+        return acc;
+      },
+      {} as StringRecord<string[]>,
+    );
+  const sortedDistanceKeys = Object.keys(matchesMap).sort(
+    (a, b) => parseInt(a, 10) - parseInt(b, 10),
+  );
   const sorted = sortedDistanceKeys.flatMap((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
+  const suggestion =
+    maxEditDistance >= 0 &&
+    best !== undefined &&
+    !Number.isNaN(minDist) &&
+    minDist <= maxEditDistance
       ? best
       : undefined;
   return {sorted, suggestion};

package/lib/index.js

@@ -14,7 +14,8 @@ export * from './protocol';
 export {errorFromMJSONWPStatusCode as errorFromCode} from './protocol';
 
 // Express exports
-export {STATIC_DIR} from './express/static';
+/** @deprecated Removed in Appium 4. Use hard-copied test fixtures in driver CI instead. */
+export {TEST_FIXTURES_DIR as STATIC_DIR} from './test-pages';
 export {server, normalizeBasePath} from './express/server';
 
 // jsonwp-proxy exports

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

@@ -6,7 +6,7 @@ import {MJSONWP_ELEMENT_KEY, W3C_ELEMENT_KEY, PROTOCOLS} from '../constants';
 export type ProxyFunction = (
   url: string,
   method: string,
-  body?: HTTPBody
+  body?: HTTPBody,
 ) => Promise<[ProxyResponse, HTTPBody]>;
 
 export const COMMAND_URLS_CONFLICTS = [
@@ -19,7 +19,8 @@ export const COMMAND_URLS_CONFLICTS = [
   },
   {
     commandNames: ['getElementScreenshot'],
-    jsonwpConverter: (url: string) => url.replace(/\/element\/([^/]+)\/screenshot$/, '/screenshot/$1'),
+    jsonwpConverter: (url: string) =>
+      url.replace(/\/element\/([^/]+)\/screenshot$/, '/screenshot/$1'),
     w3cConverter: (url: string) => url.replace(/\/screenshot\/([^/]+)/, '/element/$1/screenshot'),
   },
   {
@@ -59,7 +60,7 @@ export class ProtocolConverter {
    */
   constructor(
     public proxyFunc: ProxyFunction,
-    log: AppiumLogger | null = null
+    log: AppiumLogger | null = null,
   ) {
     this._log = log;
   }
@@ -84,7 +85,7 @@ export class ProtocolConverter {
     commandName: string,
     url: string,
     method: string,
-    body?: HTTPBody
+    body?: HTTPBody,
   ): Promise<[ProxyResponse, HTTPBody]> {
     if (!this.downstreamProtocol) {
       return await this.proxyFunc(url, method, body);
@@ -117,12 +118,12 @@ export class ProtocolConverter {
         this.downstreamProtocol === MJSONWP ? jsonwpConverter(url) : w3cConverter(url);
       if (rewrittenUrl === url) {
         this.log.debug(
-          `Did not know how to rewrite the original URL '${url}' for ${this.downstreamProtocol} protocol`
+          `Did not know how to rewrite the original URL '${url}' for ${this.downstreamProtocol} protocol`,
         );
         break;
       }
       this.log.info(
-        `Rewrote the original URL '${url}' to '${rewrittenUrl}' for ${this.downstreamProtocol} protocol`
+        `Rewrote the original URL '${url}' to '${rewrittenUrl}' for ${this.downstreamProtocol} protocol`,
       );
       return await this.proxyFunc(rewrittenUrl, method, body);
     }
@@ -142,7 +143,11 @@ export class ProtocolConverter {
     }
 
     const bodyObj = (util.safeJsonParse(body) as Record<string, unknown>) ?? {};
-    if (this.downstreamProtocol === W3C && Object.hasOwn(bodyObj, 'ms') && Object.hasOwn(bodyObj, 'type')) {
+    if (
+      this.downstreamProtocol === W3C &&
+      Object.hasOwn(bodyObj, 'ms') &&
+      Object.hasOwn(bodyObj, 'type')
+    ) {
       const typeToW3C = (x: string) => (x === 'page load' ? 'pageLoad' : x);
       return [
         {
@@ -151,15 +156,20 @@ export class ProtocolConverter {
       ];
     }
 
-    if (this.downstreamProtocol === MJSONWP && (!Object.hasOwn(bodyObj, 'ms') || !Object.hasOwn(bodyObj, 'type'))) {
+    if (
+      this.downstreamProtocol === MJSONWP &&
+      (!Object.hasOwn(bodyObj, 'ms') || !Object.hasOwn(bodyObj, 'type'))
+    ) {
       const typeToJSONWP = (x: string) => (x === 'pageLoad' ? 'page load' : x);
-      return Object.entries(bodyObj)
-        // Only transform the entry if ms value is a valid positive float number
-        .filter((pair) => /^\d+(?:[.,]\d*?)?$/.test(`${pair[1]}`))
-        .map((pair) => ({
-          type: typeToJSONWP(pair[0]),
-          ms: pair[1],
-        }));
+      return (
+        Object.entries(bodyObj)
+          // Only transform the entry if ms value is a valid positive float number
+          .filter((pair) => /^\d+(?:[.,]\d*?)?$/.test(`${pair[1]}`))
+          .map((pair) => ({
+            type: typeToJSONWP(pair[0]),
+            ms: pair[1],
+          }))
+      );
     }
 
     return [bodyObj];
@@ -171,14 +181,14 @@ export class ProtocolConverter {
   private async proxySetTimeouts(
     url: string,
     method: string,
-    body?: HTTPBody
+    body?: HTTPBody,
   ): Promise<[ProxyResponse, HTTPBody]> {
     const timeoutRequestObjects = this.getTimeoutRequestObjects(body);
     if (timeoutRequestObjects.length === 0) {
       return await this.proxyFunc(url, method, body);
     }
     this.log.debug(
-      `Will send the following request bodies to /timeouts: ${JSON.stringify(timeoutRequestObjects)}`
+      `Will send the following request bodies to /timeouts: ${JSON.stringify(timeoutRequestObjects)}`,
     );
 
     let response!: ProxyResponse;
@@ -202,12 +212,16 @@ export class ProtocolConverter {
   private async proxySetWindow(
     url: string,
     method: string,
-    body: HTTPBody
+    body: HTTPBody,
   ): Promise<[ProxyResponse, HTTPBody]> {
     const bodyObj = util.safeJsonParse(body);
     if (util.isPlainObject(bodyObj)) {
       const obj = bodyObj as Record<string, unknown>;
-      if (this.downstreamProtocol === W3C && Object.hasOwn(bodyObj, 'name') && !Object.hasOwn(bodyObj, 'handle')) {
+      if (
+        this.downstreamProtocol === W3C &&
+        Object.hasOwn(bodyObj, 'name') &&
+        !Object.hasOwn(bodyObj, 'handle')
+      ) {
         this.log.debug(`Copied 'name' value '${obj.name}' to 'handle' as per W3C spec`);
         return await this.proxyFunc(url, method, {...obj, handle: obj.name});
       }
@@ -226,10 +240,13 @@ export class ProtocolConverter {
   private async proxySetValue(
     url: string,
     method: string,
-    body: HTTPBody
+    body: HTTPBody,
   ): Promise<[ProxyResponse, HTTPBody]> {
     const bodyObj = util.safeJsonParse(body) as Record<string, unknown> | undefined;
-    if (util.isPlainObject(bodyObj) && (util.hasValue(bodyObj?.text) || util.hasValue(bodyObj?.value))) {
+    if (
+      util.isPlainObject(bodyObj) &&
+      (util.hasValue(bodyObj?.text) || util.hasValue(bodyObj?.value))
+    ) {
       let {text, value} = bodyObj;
       if (util.hasValue(text) && !util.hasValue(value)) {
         value = typeof text === 'string' ? [...text] : Array.isArray(text) ? text : [];
@@ -246,13 +263,20 @@ export class ProtocolConverter {
   private async proxySetFrame(
     url: string,
     method: string,
-    body: HTTPBody
+    body: HTTPBody,
   ): Promise<[ProxyResponse, HTTPBody]> {
     const bodyObj = util.safeJsonParse(body);
-    if (Object.hasOwn(bodyObj ?? {}, 'id') && util.isPlainObject((bodyObj as Record<string, unknown>).id)) {
+    if (
+      Object.hasOwn(bodyObj ?? {}, 'id') &&
+      util.isPlainObject((bodyObj as Record<string, unknown>).id)
+    ) {
       return await this.proxyFunc(url, method, {
         ...(bodyObj as object),
-        id: duplicateKeys((bodyObj as Record<string, unknown>).id as object, MJSONWP_ELEMENT_KEY, W3C_ELEMENT_KEY),
+        id: duplicateKeys(
+          (bodyObj as Record<string, unknown>).id as object,
+          MJSONWP_ELEMENT_KEY,
+          W3C_ELEMENT_KEY,
+        ),
       });
     }
     return await this.proxyFunc(url, method, body);
@@ -261,14 +285,14 @@ export class ProtocolConverter {
   private async proxyPerformActions(
     url: string,
     method: string,
-    body: HTTPBody
+    body: HTTPBody,
   ): Promise<[ProxyResponse, HTTPBody]> {
     const bodyObj = util.safeJsonParse(body);
     if (util.isPlainObject(bodyObj)) {
       return await this.proxyFunc(
         url,
         method,
-        duplicateKeys(bodyObj as object, MJSONWP_ELEMENT_KEY, W3C_ELEMENT_KEY)
+        duplicateKeys(bodyObj as object, MJSONWP_ELEMENT_KEY, W3C_ELEMENT_KEY),
       );
     }
     return await this.proxyFunc(url, method, body);
@@ -276,7 +300,7 @@ export class ProtocolConverter {
 
   private async proxyReleaseActions(
     url: string,
-    method: string
+    method: string,
   ): Promise<[ProxyResponse, HTTPBody]> {
     return await this.proxyFunc(url, method);
   }

package/lib/jsonwp-proxy/proxy.ts

@@ -31,7 +31,7 @@ import type {AxiosError, AxiosResponse, RawAxiosRequestConfig} from 'axios';
 const DEFAULT_LOG = logger.getLogger('WD Proxy');
 const DEFAULT_REQUEST_TIMEOUT = 240000;
 const COMMAND_WITH_SESSION_ID_MATCHER = pathToRegexMatch(
-  '{/*prefix}/session/:sessionId{/*command}'
+  '{/*prefix}/session/:sessionId{/*command}',
 );
 
 const {MJSONWP, W3C} = PROTOCOLS;
@@ -71,7 +71,7 @@ export class JWProxy {
   constructor(opts: ProxyOptions = {}) {
     const filteredOptsWithoutLog = omit(
       pick(opts as Record<string, unknown>, ALLOWED_OPTS),
-      'log'
+      'log',
     ) as Omit<ProxyOptions, 'log'>;
     const options = {
       scheme: 'http',
@@ -92,7 +92,14 @@ export class JWProxy {
       timeout: number;
     };
     options.scheme = options.scheme.toLowerCase();
-    Object.assign(this, options);
+    this.scheme = options.scheme;
+    this.server = options.server;
+    this.port = options.port;
+    this.base = options.base;
+    this.reqBasePath = options.reqBasePath;
+    this.sessionId = options.sessionId;
+    this.timeout = options.timeout;
+    this.headers = options.headers;
 
     this._activeRequests = [];
     this._downstreamProtocol = null;
@@ -151,11 +158,8 @@ export class JWProxy {
   getUrlForProxy(url: string, method?: HTTPMethod): string {
     const parsedUrl = this._parseUrl(url);
     const normalizedPathname = this._toNormalizedPathname(parsedUrl);
-    const commandName = normalizedPathname
-      ? routeToCommandName(normalizedPathname, method)
-      : '';
-    const requiresSessionId =
-      !commandName || (commandName && isSessionCommand(commandName));
+    const commandName = normalizedPathname ? routeToCommandName(normalizedPathname, method) : '';
+    const requiresSessionId = !commandName || (commandName && isSessionCommand(commandName));
     const proxyPrefix = `${this.scheme}://${this.server}:${this.port}${this.base}`;
     let proxySuffix = normalizedPathname ? `/${normalizedPathname.replace(/^\/+/, '')}` : '';
     if (parsedUrl.search) {
@@ -165,9 +169,7 @@ export class JWProxy {
       return `${proxyPrefix}${proxySuffix}`;
     }
     if (!this.sessionId) {
-      throw new ReferenceError(
-        `Session ID is not set, but saw a URL that requires it (${url})`
-      );
+      throw new ReferenceError(`Session ID is not set, but saw a URL that requires it (${url})`);
     }
     return `${proxyPrefix}/session/${this.sessionId}${proxySuffix}`;
   }
@@ -178,7 +180,7 @@ export class JWProxy {
   async proxy(
     url: string,
     method: string,
-    body: HTTPBody = null
+    body: HTTPBody = null,
   ): Promise<[ProxyResponse, HTTPBody]> {
     method = method.toUpperCase();
     const newUrl = this.getUrlForProxy(url, method as HTTPMethod);
@@ -210,11 +212,11 @@ export class JWProxy {
           this.log.warn(
             'Invalid body payload (%s): %s',
             (error as Error).message,
-            logger.markSensitive(truncateBody(body))
+            logger.markSensitive(truncateBody(body)),
           );
           throw new Error(
             'Cannot interpret the request body as valid JSON. Check the server log for more details.',
-            {cause: error}
+            {cause: error},
           );
         }
       } else {
@@ -228,7 +230,7 @@ export class JWProxy {
       url || '/',
       method,
       newUrl,
-      reqOpts.data ? logger.markSensitive(truncateBody(reqOpts.data)) : 'no'
+      reqOpts.data ? logger.markSensitive(truncateBody(reqOpts.data)) : 'no',
     );
 
     const throwProxyError = (error: unknown): never => {
@@ -258,8 +260,7 @@ export class JWProxy {
         if (status === 200) {
           const value = data.value as Record<string, unknown> | undefined;
           const raw = data.sessionId ?? value?.sessionId;
-          this.sessionId =
-            typeof raw === 'string' ? raw : raw != null ? String(raw) : null;
+          this.sessionId = typeof raw === 'string' ? raw : raw != null ? String(raw) : null;
         }
         this.downstreamProtocol = this.getProtocolFromResBody(data) ?? this.downstreamProtocol;
         this.log.info(`Determined the downstream protocol as '${this.downstreamProtocol}'`);
@@ -284,18 +285,14 @@ export class JWProxy {
           this.log.info(
             util.hasValue(err.response.status)
               ? `Got response with status ${err.response.status}: ${error}`
-              : `Got response with unknown status: ${error}`
+              : `Got response with unknown status: ${error}`,
           );
         }
       } else {
         proxyErrorMsg = `Could not proxy command to the remote server. Original error: ${err.message}`;
         this.log.info(err.message);
       }
-      throw new errors.ProxyRequestError(
-        proxyErrorMsg,
-        err.response?.data,
-        err.response?.status
-      );
+      throw new errors.ProxyRequestError(proxyErrorMsg, err.response?.data, err.response?.status);
     }
   }
 
@@ -317,13 +314,11 @@ export class JWProxy {
   async proxyCommand(
     url: string,
     method: HTTPMethod,
-    body: HTTPBody = null
+    body: HTTPBody = null,
   ): Promise<[ProxyResponse, HTTPBody]> {
     const parsedUrl = this._parseUrl(url);
     const normalizedPathname = this._toNormalizedPathname(parsedUrl);
-    const commandName = normalizedPathname
-      ? routeToCommandName(normalizedPathname, method)
-      : '';
+    const commandName = normalizedPathname ? routeToCommandName(normalizedPathname, method) : '';
     if (!commandName) {
       return await this.proxy(url, method, body);
     }
@@ -335,11 +330,7 @@ export class JWProxy {
   /**
    * Executes a WebDriver command and returns the unwrapped `value` field (or throws).
    */
-  async command(
-    url: string,
-    method: HTTPMethod,
-    body: HTTPBody = null
-  ): Promise<HTTPBody> {
+  async command(url: string, method: HTTPMethod, body: HTTPBody = null): Promise<HTTPBody> {
     let response: ProxyResponse;
     let resBodyObj: HTTPBody;
     try {
@@ -362,9 +353,12 @@ export class JWProxy {
         if (util.isPlainObject(message) && Object.hasOwn(message, 'message')) {
           message = (message as Record<string, unknown>).message;
         }
-        throw errorFromMJSONWPStatusCode(status, util.isEmpty(message)
-          ? getSummaryByCode(status)
-          : (message as string | {message: string}));
+        throw errorFromMJSONWPStatusCode(
+          status,
+          util.isEmpty(message)
+            ? getSummaryByCode(status)
+            : (message as string | {message: string}),
+        );
       }
     } else if (protocol === W3C) {
       if (response.statusCode < 300) {
@@ -375,7 +369,7 @@ export class JWProxy {
         throw errorFromW3CJsonCode(
           value.error as string,
           (value.message as string) ?? '',
-          value.stacktrace as string | undefined
+          value.stacktrace as string | undefined,
         );
       }
     } else if (response.statusCode === 200) {
@@ -385,7 +379,7 @@ export class JWProxy {
       `Did not know what to do with response code '${response.statusCode}' ` +
         `and response body '${util.truncateString(JSON.stringify(resBodyObj), {
           length: 300,
-        })}'`
+        })}'`,
     );
   }
 
@@ -410,20 +404,22 @@ export class JWProxy {
       const [response, body] = await this.proxyCommand(
         req.originalUrl,
         req.method as HTTPMethod,
-        req.body
+        req.body,
       );
       statusCode = response.statusCode;
       resBodyObj = body;
     } catch (err: unknown) {
       [statusCode, resBodyObj] = getResponseForW3CError(
-        isErrorType(err, errors.ProxyRequestError) ? (err as InstanceType<typeof errors.ProxyRequestError>).getActualError() : err
+        isErrorType(err, errors.ProxyRequestError)
+          ? (err as InstanceType<typeof errors.ProxyRequestError>).getActualError()
+          : err,
       );
     }
     res.setHeader('content-type', 'application/json; charset=utf-8');
     if (!util.isPlainObject(resBodyObj)) {
       const error = new errors.UnknownError(
         `The downstream server response with the status code ${statusCode} is not a valid JSON object: ` +
-          util.truncateString(`${resBodyObj}`, {length: 300})
+          util.truncateString(`${resBodyObj}`, {length: 300}),
       );
       [statusCode, resBodyObj] = getResponseForW3CError(error);
     }
@@ -487,10 +483,14 @@ export class JWProxy {
     // This is needed for the backward compatibility
     // if drivers don't set reqBasePath properly
     if (!this.reqBasePath) {
-      if (match && match.params && Array.isArray((match.params as Record<string, unknown>).prefix)) {
+      if (
+        match &&
+        match.params &&
+        Array.isArray((match.params as Record<string, unknown>).prefix)
+      ) {
         pathname = pathname.replace(
           `/${((match.params as Record<string, unknown>).prefix as string[]).join('/')}`,
-          ''
+          '',
         );
       } else if (pathname.startsWith('/wd/hub')) {
         pathname = pathname.replace('/wd/hub', '');