@appium/base-driver 10.0.0-beta.2 → 10.0.0-rc.2

package/lib/basedriver/driver.ts

@@ -9,7 +9,6 @@ import {
   type Driver,
   type DriverCaps,
   type DriverData,
-  type MultiSessionData,
   type ServerArgs,
   type StringRecord,
   type W3CDriverCaps,
@@ -26,6 +25,7 @@ import {DELETE_SESSION_COMMAND, determineProtocol, errors} from '../protocol';
 import {processCapabilities, validateCaps} from './capabilities';
 import {DriverCore} from './core';
 import * as helpers from './helpers';
+import {resolveExecuteExtensionName} from '../helpers/extension-command-name';
 
 const EVENT_SESSION_INIT = 'newSessionRequested';
 const EVENT_SESSION_START = 'newSessionStarted';
@@ -162,6 +162,11 @@ export class BaseDriver<
 
     // log timing information about this command
     const endTime = Date.now();
+
+    if (this.clarifyCommandName) {
+      cmd = this.clarifyCommandName(cmd, args);
+    }
+
     this._eventHistory.commands.push({cmd, startTime, endTime});
     if (cmd === 'createSession') {
       this.logEvent(EVENT_SESSION_START);
@@ -172,6 +177,17 @@ export class BaseDriver<
     return res;
   }
 
+  clarifyCommandName(cmd: string, args: string[]): string {
+    if (cmd === 'execute') {
+      const firstArg = args?.[0];
+      if (_.isString(firstArg) && firstArg.trim().length > 0) {
+        return resolveExecuteExtensionName.call(this, firstArg);
+      }
+    }
+
+    return cmd;
+  }
+
   async startUnexpectedShutdown(
     err: Error = new errors.NoSuchDriverError('The driver was unexpectedly shut down!'),
   ) {
@@ -302,6 +318,7 @@ export class BaseDriver<
     this.validateDesiredCaps(caps);
 
     this.sessionId = util.uuidV4();
+    this.sessionCreationTimestampMs = Date.now();
     this.caps = caps;
     // merge caps onto opts so we don't need to worry about what's where
     this.opts = {..._.cloneDeep(this.initialOpts), ...this.caps};
@@ -345,22 +362,10 @@ export class BaseDriver<
 
     return [this.sessionId, caps] as CreateResult;
   }
-  async getSessions() {
-    const ret: MultiSessionData<C>[] = [];
-
-    if (this.sessionId) {
-      ret.push({
-        id: this.sessionId,
-        capabilities: this.caps,
-      });
-    }
-
-    return ret;
-  }
 
   /**
    * Returns capabilities for the session and event history (if applicable)
-   * @deprecated Use {@linkcode ISessionCommands.getAppiumSessionCapabilities} instead for getting the capabilities.
+   * @deprecated Use {@linkcode getAppiumSessionCapabilities} instead for getting the capabilities.
    * Use {@linkcode EventCommands.getLogEvents} instead to get the event history.
    */
   async getSession() {

package/lib/basedriver/extension-core.ts

@@ -71,7 +71,7 @@ export class ExtensionCore {
     }
 
     // if the command module or method isn't part of our spec, reject
-    if (!this.bidiCommands[moduleName] || !this.bidiCommands[moduleName][methodName]) {
+    if (!(this.bidiCommands[moduleName]?.[methodName])) {
       throw new errors.UnknownCommandError();
     }
 

package/lib/basedriver/helpers.js

@@ -101,7 +101,7 @@ export async function configureApp(
   const originalAppLink = app;
   let packageHash = null;
   /** @type {import('axios').AxiosResponse['headers']|undefined} */
-  let headers = undefined;
+  let headers;
   /** @type {RemoteAppProps} */
   const remoteAppProps = {
     lastModified: null,
@@ -121,12 +121,12 @@ export async function configureApp(
   }
   const appCacheKey = toCacheKey(app);
 
-  const cachedAppInfo = APPLICATIONS_CACHE.get(appCacheKey);
-  if (cachedAppInfo) {
-    logger.debug(`Cached app data: ${JSON.stringify(cachedAppInfo, null, 2)}`);
-  }
-
   return await APPLICATIONS_CACHE_GUARD.acquire(appCacheKey, async () => {
+    const cachedAppInfo = APPLICATIONS_CACHE.get(appCacheKey);
+    if (cachedAppInfo) {
+      logger.debug(`Cached app data: ${JSON.stringify(cachedAppInfo, null, 2)}`);
+    }
+
     if (isUrl) {
       // Use the app from remote URL
       logger.info(`Using downloadable app '${newApp}'`);
@@ -434,7 +434,7 @@ async function fetchApp(srcStream, dstPath) {
  *
  * @param {string} app App link.
  * @returns {string} Transformed app link or the original arg if
- * no transfromation is needed.
+ * no transformation is needed.
  */
 function toCacheKey(app) {
   if (!isEnvOptionEnabled('APPIUM_APPS_CACHE_IGNORE_URL_QUERY') || !isSupportedUrl(app)) {
@@ -529,7 +529,7 @@ function isSupportedUrl(app) {
  *
  * @param {string} optionName Option name
  * @param {boolean|null} [defaultValue=null] The value to return if the given env value
- * is not set explcitly
+ * is not set explicitly
  * @returns {boolean} True if the option is enabled
  */
 function isEnvOptionEnabled(optionName, defaultValue = null) {

package/lib/express/express-logging.js

@@ -3,6 +3,7 @@ import '@colors/colors';
 import morgan from 'morgan';
 import log from './logger';
 import {MAX_LOG_BODY_LENGTH} from '../constants';
+import {logger} from '@appium/support';
 
 // Copied the morgan compile function over so that cooler formats
 // may be configured
@@ -51,7 +52,7 @@ const startLogFormatter = morgan(
         });
       } catch {}
     }
-    log.info(requestStartLoggingFormat(tokens, req, res), reqBody.grey);
+    log.info(requestStartLoggingFormat(tokens, req, res), logger.markSensitive(reqBody.grey));
   },
   {immediate: true}
 );

package/lib/express/server.js

@@ -231,7 +231,7 @@ function configureHttp({httpServer, reject, keepAliveTimeout, gracefulShutdownTi
       }, gracefulShutdownTimeout);
       httpServer.once('close', () => {
         log.info(
-          `Appium HTTP server has been succesfully closed after ` +
+          `Appium HTTP server has been successfully closed after ` +
           `${timer.getDuration().asMilliSeconds.toFixed(0)}ms`
         );
         clearTimeout(onTimeout);
@@ -309,7 +309,7 @@ export function normalizeBasePath(basePath) {
 
   // likewise, ensure the path prefix does always START with /, unless the path
   // is empty meaning no base path at all
-  if (basePath !== '' && basePath[0] !== '/') {
+  if (basePath !== '' && !basePath.startsWith('/')) {
     basePath = `/${basePath}`;
   }
 

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

@@ -0,0 +1,27 @@
+import _ from 'lodash';
+import type {Constraints, Driver, DriverClass} from '@appium/types';
+import type {BaseDriver} from '../basedriver/driver';
+
+/**
+ * Resolves the name of extension method corresponding to an `execute` command string
+ * based on the driver's `executeMethodMap`.
+ *
+ * @param commandName - The command name to resolve.
+ * @returns The resolved extension command name if a mapping exists. Otherwise, the original command name.
+ */
+export function resolveExecuteExtensionName<C extends Constraints>(
+  this: BaseDriver<C>,
+  commandName: string
+): string {
+  const Driver = this.constructor as DriverClass<Driver<C>>;
+  const methodMap = Driver.executeMethodMap;
+
+  if (methodMap && _.isPlainObject(methodMap) && commandName in methodMap) {
+    const command = methodMap[commandName]?.command;
+    if (typeof command === 'string') {
+      return command;
+    }
+  }
+
+  return commandName;
+}

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

@@ -19,12 +19,12 @@ export const COMMAND_URLS_CONFLICTS = [
   {
     commandNames: ['getWindowHandles', 'getWindowHandle'],
     jsonwpConverter(url) {
-      return /\/window$/.test(url)
+      return url.endsWith('/window')
         ? url.replace(/\/window$/, '/window_handle')
         : url.replace(/\/window\/handle(s?)$/, '/window_handle$1');
     },
     w3cConverter(url) {
-      return /\/window_handle$/.test(url)
+      return url.endsWith('/window_handle')
         ? url.replace(/\/window_handle$/, '/window')
         : url.replace(/\/window_handles$/, '/window/handles');
     },
@@ -186,20 +186,19 @@ class ProtocolConverter {
       let {text, value} = bodyObj;
       if (util.hasValue(text) && !util.hasValue(value)) {
         value = _.isString(text) ? [...text] : _.isArray(text) ? text : [];
-        this.log.debug(
-          `Added 'value' property ${JSON.stringify(value)} to 'setValue' request body`
-        );
+        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 ${JSON.stringify(text)} to 'setValue' request body`);
+        this.log.debug(`Added 'text' property to 'setValue' request body`);
       }
       return await this.proxyFunc(
         url,
         method,
-        Object.assign({}, bodyObj, {
+        {
+          ...bodyObj,
           text,
           value,
-        })
+        }
       );
     }
 

package/lib/jsonwp-proxy/proxy.js

@@ -203,8 +203,11 @@ export class JWProxy {
       if (typeof body !== 'object') {
         try {
           reqOpts.data = JSON.parse(body);
-        } catch {
-          throw new Error(`Cannot interpret the request body as valid JSON: ${truncateBody(body)}`);
+        } catch (error) {
+          this.log.warn('Invalid body payload (%s): %s', error.message, logger.markSensitive(truncateBody(body)));
+          throw new Error(
+            'Cannot interpret the request body as valid JSON. Check the server log for more details.'
+          );
         }
       } else {
         reqOpts.data = body;
@@ -212,8 +215,9 @@ export class JWProxy {
     }
 
     this.log.debug(
-      `Proxying [${method} ${url || '/'}] to [${method} ${newUrl}] ` +
-        (reqOpts.data ? `with body: ${truncateBody(reqOpts.data)}` : 'with no body')
+      `Proxying [%s %s] to [%s %s] with ${reqOpts.data ? 'body: %s' : '%s body'}`,
+      method, url || '/', method, newUrl,
+      reqOpts.data ? logger.markSensitive(truncateBody(reqOpts.data)) : 'no'
     );
 
     const throwProxyError = (error) => {
@@ -236,7 +240,7 @@ export class JWProxy {
       }
       this.log.debug(`Got response with status ${status}: ${truncateBody(data)}`);
       isResponseLogged = true;
-      const isSessionCreationRequest = /\/session$/.test(url) && method === 'POST';
+      const isSessionCreationRequest = url.endsWith('/session') && method === 'POST';
       if (isSessionCreationRequest) {
         if (status === 200) {
           this.sessionId = data.sessionId || (data.value || {}).sessionId;

package/lib/protocol/protocol.ts

@@ -317,9 +317,9 @@ function buildHandler(
       if (spec.deprecated && spec.command && !deprecatedCommandsLogged.has(spec.command)) {
         deprecatedCommandsLogged.add(spec.command);
         getLogger(driver, req.params.sessionId).warn(
-          `Command '${spec.command}' has been deprecated and will be removed in a future ` +
-            `version of Appium or your driver/plugin. Please use a different method or contact the ` +
-            `driver/plugin author to add explicit support for the command before it is removed`
+          `The ${method} ${path} endpoint has been deprecated and will be removed in a future ` +
+            `version of Appium or your driver/plugin. Please use a different endpoint or contact the ` +
+            `driver/plugin author to add explicit support for the endpoint before it is removed`
         );
       }
 
@@ -394,9 +394,9 @@ function buildHandler(
 
       // run the driver command wrapped inside the argument validators
       getLogger(driver, req.params.sessionId).debug(
-        `Calling ` +
-          `${driver.constructor.name}.${spec.command}() with args: ` +
-          _.truncate(JSON.stringify(args), {length: MAX_LOG_BODY_LENGTH})
+        `Calling %s.%s() with args: %s`,
+        driver.constructor.name, spec.command,
+        logger.markSensitive(_.truncate(JSON.stringify(args), {length: MAX_LOG_BODY_LENGTH}))
       );
 
       if (didPluginOverrideProxy) {

package/lib/protocol/routes.js

@@ -269,8 +269,15 @@ export const METHOD_MAP = /** @type {const} */ ({
     POST: {command: 'setRotation', payloadParams: {required: ['x', 'y', 'z']}},
   },
   '/session/:sessionId/location': {
-    GET: {command: 'getGeoLocation'},
-    POST: {command: 'setGeoLocation', payloadParams: {required: ['location']}},
+    GET: {
+      command: 'getGeoLocation',
+      deprecated: true,
+    },
+    POST: {
+      command: 'setGeoLocation',
+      payloadParams: {required: ['location']},
+      deprecated: true,
+    },
   },
   '/session/:sessionId/orientation': {
     GET: {command: 'getOrientation'},
@@ -406,7 +413,7 @@ export const METHOD_MAP = /** @type {const} */ ({
   // #endregion
 
   //
-  // 3rd party vendor/protcol support
+  // 3rd party vendor/protocol support
   //
   // #region Selenium/Chromium browsers
   '/session/:sessionId/se/log': {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appium/base-driver",
-  "version": "10.0.0-beta.2",
+  "version": "10.0.0-rc.2",
   "description": "Base driver class for Appium drivers",
   "keywords": [
     "automation",
@@ -44,38 +44,38 @@
     "test:types": "tsd"
   },
   "dependencies": {
-    "@appium/support": "^6.1.0",
-    "@appium/types": "^0.25.3",
+    "@appium/support": "^7.0.0-rc.1",
+    "@appium/types": "^1.0.0-rc.1",
     "@colors/colors": "1.6.0",
     "async-lock": "1.4.1",
     "asyncbox": "3.0.0",
-    "axios": "1.9.0",
+    "axios": "1.11.0",
     "bluebird": "3.7.2",
-    "body-parser": "1.20.3",
-    "express": "5.0.1",
+    "body-parser": "2.2.0",
+    "express": "5.1.0",
     "fastest-levenshtein": "1.0.16",
     "http-status-codes": "2.3.0",
     "lodash": "4.17.21",
-    "lru-cache": "10.4.3",
+    "lru-cache": "11.1.0",
     "method-override": "3.0.0",
-    "morgan": "1.10.0",
+    "morgan": "1.10.1",
     "path-to-regexp": "8.2.0",
-    "serve-favicon": "2.5.0",
+    "serve-favicon": "2.5.1",
     "source-map-support": "0.5.21",
-    "type-fest": "4.40.0"
+    "type-fest": "4.41.0"
   },
   "optionalDependencies": {
     "spdy": "4.0.2"
   },
   "engines": {
-    "node": "^20.9.0 || >=22.11.0",
+    "node": "^20.19.0 || ^22.12.0 || >=24.0.0",
     "npm": ">=10"
   },
   "publishConfig": {
     "access": "public",
-    "tag": "beta"
+    "tag": "rc"
   },
-  "gitHead": "dc5ef8d5f62c8a0775131305107a4037cd9ec9c9",
+  "gitHead": "157425ce6aa01c009533f5bf6a56b14570222b00",
   "tsd": {
     "directory": "test/types"
   }