@appium/base-driver 10.2.0 → 10.2.2

package/lib/helpers/capabilities.ts

@@ -0,0 +1,83 @@
+import type {Constraints, W3CCapabilities, Capabilities, AppiumLogger} from '@appium/types';
+import _ from 'lodash';
+
+/**
+ * Determine whether the given argument is valid
+ * W3C capabilities instance.
+ */
+export function isW3cCaps(caps: unknown): caps is W3CCapabilities<Constraints> {
+  if (!_.isPlainObject(caps)) {
+    return false;
+  }
+
+  const c = caps as Record<string, unknown>;
+  const isFirstMatchValid = () =>
+    _.isArray(c.firstMatch) &&
+    !_.isEmpty(c.firstMatch) &&
+    _.every(c.firstMatch, _.isPlainObject);
+  const isAlwaysMatchValid = () => _.isPlainObject(c.alwaysMatch);
+  if (_.has(c, 'firstMatch') && _.has(c, 'alwaysMatch')) {
+    return isFirstMatchValid() && isAlwaysMatchValid();
+  }
+  if (_.has(c, 'firstMatch')) {
+    return isFirstMatchValid();
+  }
+  if (_.has(c, 'alwaysMatch')) {
+    return isAlwaysMatchValid();
+  }
+  return false;
+}
+
+/**
+ * Normalize capability values according to constraints (e.g. string 'true' → boolean).
+ */
+export function fixCaps<C extends Constraints>(
+  oldCaps: Record<string, unknown>,
+  desiredCapConstraints: C,
+  log: AppiumLogger
+): Capabilities<C> {
+  const caps = _.clone(oldCaps) as Record<string, unknown>;
+
+  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 = _.keys(_.pickBy(desiredCapConstraints, (k) => k.isBoolean === true));
+  for (const cap of booleanCaps) {
+    const value = oldCaps[cap];
+    if (!_.isString(value)) {
+      continue;
+    }
+
+    if (!['true', 'false'].includes(value.toLowerCase())) {
+      logCastWarning(`String capability '${cap}' ('${value}') cannot be converted to a boolean`);
+      continue;
+    }
+
+    logCastWarning(`Capability '${cap}' changed from string '${value}' to boolean`);
+    caps[cap] = value.toLowerCase() === 'true';
+  }
+
+  // int capabilities are often sent in as strings by frameworks
+  const intCaps = _.keys(_.pickBy(desiredCapConstraints, (k) => k.isNumber === true));
+  for (const cap of intCaps) {
+    const value = oldCaps[cap];
+    if (!_.isString(value)) {
+      continue;
+    }
+
+    const intValue = parseInt(value as string, 10);
+    const floatValue = parseFloat(value as string);
+    const newValue = floatValue !== intValue ? floatValue : intValue;
+
+    if (Number.isNaN(newValue)) {
+      logCastWarning(`String capability '${cap}' ('${value}') cannot be converted to a number`);
+      continue;
+    }
+
+    logCastWarning(`Capability '${cap}' changed from string '${value}' to number ${newValue}`);
+    caps[cap] = newValue;
+  }
+
+  return caps as Capabilities<C>;
+}

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

@@ -0,0 +1,284 @@
+import type {AppiumLogger, HTTPBody, ProxyResponse} from '@appium/types';
+import _ from 'lodash';
+import {logger, util} from '@appium/support';
+import {duplicateKeys} from '../basedriver/helpers';
+import {MJSONWP_ELEMENT_KEY, W3C_ELEMENT_KEY, PROTOCOLS} from '../constants';
+
+export type ProxyFunction = (
+  url: string,
+  method: string,
+  body?: HTTPBody
+) => Promise<[ProxyResponse, HTTPBody]>;
+
+export const COMMAND_URLS_CONFLICTS = [
+  {
+    commandNames: ['execute', 'executeAsync'],
+    jsonwpConverter: (url: string) =>
+      url.replace(/\/execute.*/, url.includes('async') ? '/execute_async' : '/execute'),
+    w3cConverter: (url: string) =>
+      url.replace(/\/execute.*/, url.includes('async') ? '/execute/async' : '/execute/sync'),
+  },
+  {
+    commandNames: ['getElementScreenshot'],
+    jsonwpConverter: (url: string) => url.replace(/\/element\/([^/]+)\/screenshot$/, '/screenshot/$1'),
+    w3cConverter: (url: string) => url.replace(/\/screenshot\/([^/]+)/, '/element/$1/screenshot'),
+  },
+  {
+    commandNames: ['getWindowHandles', 'getWindowHandle'],
+    jsonwpConverter(url: string) {
+      return url.endsWith('/window')
+        ? url.replace(/\/window$/, '/window_handle')
+        : url.replace(/\/window\/handle(s?)$/, '/window_handle$1');
+    },
+    w3cConverter(url: string) {
+      return url.endsWith('/window_handle')
+        ? url.replace(/\/window_handle$/, '/window')
+        : url.replace(/\/window_handles$/, '/window/handles');
+    },
+  },
+  {
+    commandNames: ['getProperty'],
+    jsonwpConverter: (w3cUrl: string) => {
+      const w3cPropertyRegex = /\/element\/([^/]+)\/property\/([^/]+)/;
+      return w3cUrl.replace(w3cPropertyRegex, '/element/$1/attribute/$2');
+    },
+    // Don't convert JSONWP URL to W3C. W3C accepts /attribute and /property
+    w3cConverter: (jsonwpUrl: string) => jsonwpUrl,
+  },
+] as const;
+
+const {MJSONWP, W3C} = PROTOCOLS;
+const DEFAULT_LOG = logger.getLogger('Protocol Converter');
+
+export class ProtocolConverter {
+  private _downstreamProtocol: string | null | undefined = null;
+  private readonly _log: AppiumLogger | null;
+
+  /**
+   * @param proxyFunc - Function to perform the actual proxy request
+   * @param log - Logger instance, or null to use the default
+   */
+  constructor(
+    public proxyFunc: ProxyFunction,
+    log: AppiumLogger | null = null
+  ) {
+    this._log = log;
+  }
+
+  get log(): AppiumLogger {
+    return this._log ?? DEFAULT_LOG;
+  }
+
+  set downstreamProtocol(value: string | null | undefined) {
+    this._downstreamProtocol = value;
+  }
+
+  get downstreamProtocol(): string | null | undefined {
+    return this._downstreamProtocol;
+  }
+
+  /**
+   * Handle "crossing" endpoints for the case when upstream and downstream
+   * drivers operate different protocols.
+   */
+  async convertAndProxy(
+    commandName: string,
+    url: string,
+    method: string,
+    body?: HTTPBody
+  ): Promise<[ProxyResponse, HTTPBody]> {
+    if (!this.downstreamProtocol) {
+      return await this.proxyFunc(url, method, body);
+    }
+
+    // Same url, but different arguments
+    switch (commandName) {
+      case 'timeouts':
+        return await this.proxySetTimeouts(url, method, body);
+      case 'setWindow':
+        return await this.proxySetWindow(url, method, body);
+      case 'setValue':
+        return await this.proxySetValue(url, method, body);
+      case 'performActions':
+        return await this.proxyPerformActions(url, method, body);
+      case 'releaseActions':
+        return await this.proxyReleaseActions(url, method);
+      case 'setFrame':
+        return await this.proxySetFrame(url, method, body);
+      default:
+        break;
+    }
+
+    // Same arguments, but different URLs
+    for (const {commandNames, jsonwpConverter, w3cConverter} of COMMAND_URLS_CONFLICTS) {
+      if (!(commandNames as readonly string[]).includes(commandName)) {
+        continue;
+      }
+      const rewrittenUrl =
+        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`
+        );
+        break;
+      }
+      this.log.info(
+        `Rewrote the original URL '${url}' to '${rewrittenUrl}' for ${this.downstreamProtocol} protocol`
+      );
+      return await this.proxyFunc(rewrittenUrl, method, body);
+    }
+
+    // No matches found. Proceed normally
+    return await this.proxyFunc(url, method, body);
+  }
+
+  /**
+   * W3C /timeouts can take as many as 3 timeout types at once, MJSONWP /timeouts only takes one
+   * at a time. So if we're using W3C and proxying to MJSONWP and there's more than one timeout type
+   * provided in the request, we need to do 3 proxies and combine the result.
+   */
+  private getTimeoutRequestObjects(body: HTTPBody): Record<string, unknown>[] {
+    if (_.isNil(body)) {
+      return [];
+    }
+
+    const bodyObj = (util.safeJsonParse(body) as Record<string, unknown>) ?? {};
+    if (this.downstreamProtocol === W3C && _.has(bodyObj, 'ms') && _.has(bodyObj, 'type')) {
+      const typeToW3C = (x: string) => (x === 'page load' ? 'pageLoad' : x);
+      return [
+        {
+          [typeToW3C(bodyObj.type as string)]: bodyObj.ms,
+        },
+      ];
+    }
+
+    if (this.downstreamProtocol === MJSONWP && (!_.has(bodyObj, 'ms') || !_.has(bodyObj, 'type'))) {
+      const typeToJSONWP = (x: string) => (x === 'pageLoad' ? 'page load' : x);
+      return _.toPairs(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];
+  }
+
+  /**
+   * Proxy an array of timeout objects and merge the result.
+   */
+  private async proxySetTimeouts(
+    url: string,
+    method: string,
+    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)}`
+    );
+
+    let response!: ProxyResponse;
+    let resBody!: HTTPBody;
+    for (const timeoutObj of timeoutRequestObjects) {
+      [response, resBody] = await this.proxyFunc(url, method, timeoutObj as HTTPBody);
+
+      // If we got a non-MJSONWP response, return the result, nothing left to do
+      if (this.downstreamProtocol !== MJSONWP) {
+        return [response, resBody];
+      }
+      // If we got an error, return the error right away
+      if (response.statusCode >= 400) {
+        return [response, resBody];
+      }
+      // ...Otherwise, continue to the next timeouts call
+    }
+    return [response, resBody];
+  }
+
+  private async proxySetWindow(
+    url: string,
+    method: string,
+    body: HTTPBody
+  ): Promise<[ProxyResponse, HTTPBody]> {
+    const bodyObj = util.safeJsonParse(body);
+    if (_.isPlainObject(bodyObj)) {
+      const obj = bodyObj as Record<string, unknown>;
+      if (this.downstreamProtocol === W3C && _.has(bodyObj, 'name') && !_.has(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});
+      }
+      if (
+        this.downstreamProtocol === MJSONWP &&
+        _.has(bodyObj, 'handle') &&
+        !_.has(bodyObj, 'name')
+      ) {
+        this.log.debug(`Copied 'handle' value '${obj.handle}' to 'name' as per JSONWP spec`);
+        return await this.proxyFunc(url, method, {...obj, name: obj.handle});
+      }
+    }
+    return await this.proxyFunc(url, method, body);
+  }
+
+  private async proxySetValue(
+    url: string,
+    method: string,
+    body: HTTPBody
+  ): Promise<[ProxyResponse, HTTPBody]> {
+    const bodyObj = util.safeJsonParse(body) as Record<string, unknown> | undefined;
+    if (_.isPlainObject(bodyObj) && (util.hasValue(bodyObj?.text) || util.hasValue(bodyObj?.value))) {
+      let {text, value} = bodyObj;
+      if (util.hasValue(text) && !util.hasValue(value)) {
+        value = _.isString(text) ? [...text] : _.isArray(text) ? text : [];
+        this.log.debug(`Added 'value' property to 'setValue' request body`);
+      } else if (!util.hasValue(text) && util.hasValue(value)) {
+        text = _.isArray(value) ? value.join('') : _.isString(value) ? value : '';
+        this.log.debug(`Added 'text' property to 'setValue' request body`);
+      }
+      return await this.proxyFunc(url, method, {...bodyObj, text, value});
+    }
+    return await this.proxyFunc(url, method, body);
+  }
+
+  private async proxySetFrame(
+    url: string,
+    method: string,
+    body: HTTPBody
+  ): Promise<[ProxyResponse, HTTPBody]> {
+    const bodyObj = util.safeJsonParse(body);
+    if (_.has(bodyObj, 'id') && _.isPlainObject(bodyObj.id)) {
+      return await this.proxyFunc(url, method, {
+        ...(bodyObj as object),
+        id: duplicateKeys(bodyObj.id as object, MJSONWP_ELEMENT_KEY, W3C_ELEMENT_KEY),
+      });
+    }
+    return await this.proxyFunc(url, method, body);
+  }
+
+  private async proxyPerformActions(
+    url: string,
+    method: string,
+    body: HTTPBody
+  ): Promise<[ProxyResponse, HTTPBody]> {
+    const bodyObj = util.safeJsonParse(body);
+    if (_.isPlainObject(bodyObj)) {
+      return await this.proxyFunc(
+        url,
+        method,
+        duplicateKeys(bodyObj as object, MJSONWP_ELEMENT_KEY, W3C_ELEMENT_KEY)
+      );
+    }
+    return await this.proxyFunc(url, method, body);
+  }
+
+  private async proxyReleaseActions(
+    url: string,
+    method: string
+  ): Promise<[ProxyResponse, HTTPBody]> {
+    return await this.proxyFunc(url, method);
+  }
+}

package/lib/jsonwp-proxy/proxy.js

@@ -10,7 +10,7 @@ import {
 } from '../protocol/errors';
 import {isSessionCommand, routeToCommandName} from '../protocol';
 import {MAX_LOG_BODY_LENGTH, DEFAULT_BASE_PATH, PROTOCOLS} from '../constants';
-import ProtocolConverter from './protocol-converter';
+import {ProtocolConverter} from './protocol-converter';
 import {formatResponseValue, ensureW3cResponse} from '../protocol/helpers';
 import http from 'node:http';
 import https from 'node:https';

package/lib/jsonwp-status/{status.js → status.ts}

@@ -1,6 +1,4 @@
-import _ from 'lodash';
-
-const codes = {
+export const codes = {
   Success: {
     code: 0,
     summary: 'The command executed successfully.',
@@ -112,17 +110,16 @@ const codes = {
     code: 35,
     summary: 'No such context found.',
   },
-};
+} as const;
 
-function getSummaryByCode(code) {
-  code = parseInt(code, 10);
-  for (let obj of _.values(codes)) {
-    if (!_.isUndefined(obj.code) && obj.code === code) {
-      return obj.summary;
-    }
-  }
-  return 'An error occurred';
+/**
+ * Returns the summary message for a JSONWP status code.
+ *
+ * @param code - Numeric status code (e.g. 0, 7) or string representation
+ * @returns Human-readable summary for the code, or 'An error occurred' if unknown
+ */
+export function getSummaryByCode(code: number | string): string {
+  const parsed = parseInt(String(code), 10);
+  const match = Object.values(codes).find((obj) => obj.code === parsed);
+  return match?.summary ?? 'An error occurred';
 }
-
-export default codes;
-export {codes, getSummaryByCode};

package/lib/protocol/{bidi-commands.js → bidi-commands.ts}

@@ -1,9 +1,11 @@
-const SUBSCRIPTION_REQUEST_PARAMS = /** @type {const} */ ({
+import type {BidiModuleMap} from '@appium/types';
+
+const SUBSCRIPTION_REQUEST_PARAMS = {
   required: ['events'],
   optional: ['contexts'],
-});
+} as const;
 
-export const BIDI_COMMANDS = /** @type {const} */ ({
+export const BIDI_COMMANDS = {
   session: {
     subscribe: {
       command: 'bidiSubscribe',
@@ -16,7 +18,7 @@ export const BIDI_COMMANDS = /** @type {const} */ ({
     status: {
       command: 'bidiStatus',
       params: {},
-    }
+    },
   },
   browsingContext: {
     navigate: {
@@ -27,7 +29,7 @@ export const BIDI_COMMANDS = /** @type {const} */ ({
       },
     },
   },
-});
+} as const satisfies BidiModuleMap;
 
 // TODO add definitions for all bidi commands.
 // spec link: https://w3c.github.io/webdriver-bidi/

package/lib/protocol/errors.ts

@@ -1,7 +1,7 @@
 import _ from 'lodash';
 import {util, logger} from '@appium/support';
 import {StatusCodes as HTTPStatusCodes} from 'http-status-codes';
-import type { ErrorBiDiCommandResponse, Class } from '@appium/types';
+import type {ErrorBiDiCommandResponse, Class} from '@appium/types';
 
 const mjsonwpLog = logger.getLogger('MJSONWP');
 const w3cLog = logger.getLogger('W3C');

package/lib/protocol/{helpers.js → helpers.ts}

@@ -5,13 +5,12 @@ import {MJSONWP_ELEMENT_KEY, W3C_ELEMENT_KEY} from '../constants';
 /**
  * Preprocesses the resulting value for API responses,
  * so they have keys for both W3C and JSONWP protocols.
- * The argument value is NOT mutated
+ * The argument value is NOT mutated.
  *
- * @param {Object | undefined} resValue The actual response value
- * @returns {Object | null} Either modified value or the same one if
- * nothing has been modified
+ * @param resValue - The actual response value
+ * @returns Either modified value or the same one if nothing has been modified
  */
-export function formatResponseValue(resValue) {
+export function formatResponseValue(resValue: object | undefined): object | null {
   if (_.isUndefined(resValue)) {
     // convert undefined to null
     return null;
@@ -27,13 +26,11 @@ export function formatResponseValue(resValue) {
  * Properly formats the status for API responses,
  * so they are correct for the W3C protocol.
  *
- * @param {Object} responseBody
- * @returns {Object} The fixed response body
+ * @param responseBody - The response body
+ * @returns The fixed response body
  */
-export function ensureW3cResponse(responseBody) {
+export function ensureW3cResponse(responseBody: Record<string, unknown>): Record<string, unknown> {
   return _.isPlainObject(responseBody)
-    ? _.omit(responseBody, ['status', 'sessionId'])
+    ? (_.omit(responseBody, ['status', 'sessionId']) as Record<string, unknown>)
     : responseBody;
 }
-
-export {MJSONWP_ELEMENT_KEY, W3C_ELEMENT_KEY};