appium-android-driver 12.4.8 → 12.4.10

package/lib/commands/{geolocation.js → geolocation.ts}

@@ -2,8 +2,10 @@ import _ from 'lodash';
 import {fs, tempDir} from '@appium/support';
 import path from 'node:path';
 import B from 'bluebird';
+import type {Location} from '@appium/types';
 import {SETTINGS_HELPER_ID} from 'io.appium.settings';
 import {getThirdPartyPackages} from './app-management';
+import type {AndroidDriver} from '../driver';
 
 // The value close to zero, but not zero, is needed
 // to trick JSON generation and send a float value instead of an integer,
@@ -14,17 +16,21 @@ const GEO_EPSILON = Number.MIN_VALUE;
 const MOCK_APP_IDS_STORE = '/data/local/tmp/mock_apps.json';
 
 /**
- * @this {import('../driver').AndroidDriver}
- * @param {import('@appium/types').Location} location
- * @returns {Promise<import('@appium/types').Location>}
+ * Sets the device geolocation.
+ *
+ * @param location The geolocation object containing latitude, longitude, and altitude.
+ * @returns Promise that resolves to the current geolocation after setting it.
  */
-export async function setGeoLocation(location) {
+export async function setGeoLocation(
+  this: AndroidDriver,
+  location: Location,
+): Promise<Location> {
   await this.settingsApp.setGeoLocation(location, this.isEmulator());
   try {
     return await this.getGeoLocation();
   } catch (e) {
     this.log.warn(
-      `Could not get the current geolocation info: ${/** @type {Error} */ (e).message}`,
+      `Could not get the current geolocation info: ${(e as Error).message}`,
     );
     this.log.warn(`Returning the default zero'ed values`);
     return {
@@ -38,28 +44,28 @@ export async function setGeoLocation(location) {
 /**
  * Set the device geolocation.
  *
- * @this {import('../driver').AndroidDriver}
- * @param {number} latitude Valid latitude value.
- * @param {number} longitude Valid longitude value.
- * @param {number} [altitude] Valid altitude value.
- * @param {number} [satellites] Number of satellites being tracked (1-12). Available for emulators.
- * @param {number} [speed] Valid speed value.
+ * @param latitude Valid latitude value.
+ * @param longitude Valid longitude value.
+ * @param altitude Valid altitude value.
+ * @param satellites Number of satellites being tracked (1-12). Available for emulators.
+ * @param speed Valid speed value.
  * https://developer.android.com/reference/android/location/Location#setSpeed(float)
- * @param {number} [bearing] Valid bearing value. Available for real devices.
+ * @param bearing Valid bearing value. Available for real devices.
  * https://developer.android.com/reference/android/location/Location#setBearing(float)
- * @param {number} [accuracy] Valid accuracy value. Available for real devices.
+ * @param accuracy Valid accuracy value. Available for real devices.
  * https://developer.android.com/reference/android/location/Location#setAccuracy(float),
  * https://developer.android.com/reference/android/location/Criteria
  */
 export async function mobileSetGeolocation(
-  latitude,
-  longitude,
-  altitude,
-  satellites,
-  speed,
-  bearing,
-  accuracy
-) {
+  this: AndroidDriver,
+  latitude: number,
+  longitude: number,
+  altitude?: number,
+  satellites?: number,
+  speed?: number,
+  bearing?: number,
+  accuracy?: number,
+): Promise<void> {
   await this.settingsApp.setGeoLocation({
     latitude,
     longitude,
@@ -67,7 +73,7 @@ export async function mobileSetGeolocation(
     satellites,
     speed,
     bearing,
-    accuracy
+    accuracy,
   }, this.isEmulator());
 }
 
@@ -78,22 +84,27 @@ export async function mobileSetGeolocation(
  * installed. In case the vanilla LocationManager is used the device API level
  * must be at version 30 (Android R) or higher.
  *
- * @this {import('../driver').AndroidDriver}
- * @param {number} [timeoutMs] The maximum number of milliseconds
+ * @param timeoutMs The maximum number of milliseconds
  * to block until GPS cache is refreshed. Providing zero or a negative
  * value to it skips waiting completely.
  * 20000ms by default.
- * @returns {Promise<void>}
+ * @returns Promise that resolves when the GPS cache refresh is initiated.
  */
-export async function mobileRefreshGpsCache(timeoutMs) {
+export async function mobileRefreshGpsCache(
+  this: AndroidDriver,
+  timeoutMs?: number,
+): Promise<void> {
   await this.settingsApp.refreshGeoLocationCache(timeoutMs);
 }
 
 /**
- * @this {import('../driver').AndroidDriver}
- * @returns {Promise<import('@appium/types').Location>}
+ * Gets the current device geolocation.
+ *
+ * @returns Promise that resolves to the current geolocation object.
  */
-export async function getGeoLocation() {
+export async function getGeoLocation(
+  this: AndroidDriver,
+): Promise<Location> {
   const {latitude, longitude, altitude} = await this.settingsApp.getGeoLocation();
   return {
     latitude: parseFloat(String(latitude)) || GEO_EPSILON,
@@ -103,26 +114,35 @@ export async function getGeoLocation() {
 }
 
 /**
- * @this {import('../driver').AndroidDriver}
- * @returns {Promise<import('@appium/types').Location>}
+ * Gets the current device geolocation.
+ *
+ * @returns Promise that resolves to the current geolocation object.
  */
-export async function mobileGetGeolocation() {
+export async function mobileGetGeolocation(
+  this: AndroidDriver,
+): Promise<Location> {
   return await this.getGeoLocation();
 }
 
 /**
- * @this {import('../driver').AndroidDriver}
- * @returns {Promise<boolean>}
+ * Checks if location services are enabled.
+ *
+ * @returns Promise that resolves to `true` if location services are enabled, `false` otherwise.
  */
-export async function isLocationServicesEnabled() {
+export async function isLocationServicesEnabled(
+  this: AndroidDriver,
+): Promise<boolean> {
   return (await this.adb.getLocationProviders()).includes('gps');
 }
 
 /**
- * @this {import('../driver').AndroidDriver}
- * @returns {Promise<void>}
+ * Toggles the location services state.
+ *
+ * @returns Promise that resolves when the location services state is toggled.
  */
-export async function toggleLocationServices() {
+export async function toggleLocationServices(
+  this: AndroidDriver,
+): Promise<void> {
   this.log.info('Toggling location services');
   const isGpsEnabled = await this.isLocationServicesEnabled();
   this.log.debug(
@@ -133,10 +153,14 @@ export async function toggleLocationServices() {
 }
 
 /**
- * @this {import('../driver').AndroidDriver}
- * @returns {Promise<void>}
+ * Resets the geolocation to the default state.
+ *
+ * @returns Promise that resolves when the geolocation is reset.
+ * @throws {Error} If called on an emulator (geolocation reset does not work on emulators).
  */
-export async function mobileResetGeolocation() {
+export async function mobileResetGeolocation(
+  this: AndroidDriver,
+): Promise<void> {
   if (this.isEmulator()) {
     throw new Error('Geolocation reset does not work on emulators');
   }
@@ -146,20 +170,23 @@ export async function mobileResetGeolocation() {
 // #region Internal helpers
 
 /**
- * @this {import('../driver').AndroidDriver}
- * @param {string} appId
- * @returns {Promise<void>}
+ * Sets the mock location permission for a specific app.
+ *
+ * @param appId The application package identifier.
+ * @returns Promise that resolves when the mock location permission is set.
  */
-export async function setMockLocationApp(appId) {
+export async function setMockLocationApp(
+  this: AndroidDriver,
+  appId: string,
+): Promise<void> {
   try {
     await this.adb.shell(['appops', 'set', appId, 'android:mock_location', 'allow']);
   } catch (err) {
-    this.log.warn(`Unable to set mock location for app '${appId}': ${err.message}`);
+    this.log.warn(`Unable to set mock location for app '${appId}': ${(err as Error).message}`);
     return;
   }
   try {
-    /** @type {string[]} */
-    let pkgIds = [];
+    let pkgIds: string[] = [];
     if (await this.adb.fileExists(MOCK_APP_IDS_STORE)) {
       try {
         pkgIds = JSON.parse(await this.adb.shell(['cat', MOCK_APP_IDS_STORE]));
@@ -178,18 +205,21 @@ export async function setMockLocationApp(appId) {
       await fs.rimraf(tmpRoot);
     }
   } catch (e) {
-    this.log.warn(`Unable to persist mock location app id '${appId}': ${e.message}`);
+    this.log.warn(`Unable to persist mock location app id '${appId}': ${(e as Error).message}`);
   }
 }
 
 /**
- * @this {import('../driver').AndroidDriver}
- * @returns {Promise<void>}
+ * Resets the mock location permissions for all apps.
+ *
+ * @returns Promise that resolves when the mock location permissions are reset.
  */
-async function resetMockLocation() {
+async function resetMockLocation(
+  this: AndroidDriver,
+): Promise<void> {
   try {
     const thirdPartyPkgIdsPromise = getThirdPartyPackages.bind(this)();
-    let pkgIds = [];
+    let pkgIds: string[] = [];
     if (await this.adb.fileExists(MOCK_APP_IDS_STORE)) {
       try {
         pkgIds = JSON.parse(await this.adb.shell(['cat', MOCK_APP_IDS_STORE]));
@@ -220,8 +250,9 @@ async function resetMockLocation() {
       ),
     );
   } catch (err) {
-    this.log.warn(`Unable to reset mock location: ${err.message}`);
+    this.log.warn(`Unable to reset mock location: ${(err as Error).message}`);
   }
 }
 
 // #endregion Internal helpers
+

package/lib/commands/{log.js → log.ts}

@@ -2,51 +2,42 @@ import {DEFAULT_WS_PATHNAME_PREFIX, BaseDriver} from 'appium/driver';
 import _ from 'lodash';
 import os from 'node:os';
 import WebSocket from 'ws';
+import type {AppiumServer, WSServer} from '@appium/types';
+import type {EventEmitter} from 'node:events';
+import type {ADB} from 'appium-adb';
+import type {Chromedriver} from 'appium-chromedriver';
 import {
   GET_SERVER_LOGS_FEATURE,
   toLogRecord,
   nativeLogEntryToSeleniumEntry,
+  type LogEntry,
 } from '../utils';
 import { NATIVE_WIN } from './context/helpers';
 import { BIDI_EVENT_NAME } from './bidi/constants';
 import { makeLogEntryAddedEvent } from './bidi/models';
+import type {AndroidDriver} from '../driver';
 
 export const supportedLogTypes = {
   logcat: {
     description: 'Logs for Android applications on real device and emulators via ADB',
-    /**
-     *
-     * @param {import('../driver').AndroidDriver} self
-     * @returns
-     */
-    getter: (self) => /** @type {ADB} */ (self.adb).getLogcatLogs(),
+    getter: (self: AndroidDriver) => (self.adb as ADB).getLogcatLogs(),
   },
   bugreport: {
     description: `'adb bugreport' output for advanced issues diagnostic`,
-    /**
-     *
-     * @param {import('../driver').AndroidDriver} self
-     * @returns
-     */
-    getter: async (self) => {
-      const output = await /** @type {ADB} */ (self.adb).bugreport();
+    getter: async (self: AndroidDriver) => {
+      const output = await (self.adb as ADB).bugreport();
       const timestamp = Date.now();
       return output.split(os.EOL).map((x) => toLogRecord(timestamp, x));
     },
   },
   server: {
     description: 'Appium server logs',
-    /**
-     *
-     * @param {import('../driver').AndroidDriver} self
-     * @returns
-     */
-    getter: (self) => {
+    getter: (self: AndroidDriver) => {
       self.assertFeatureEnabled(GET_SERVER_LOGS_FEATURE);
       return self.log.unwrap().record.map(nativeLogEntryToSeleniumEntry);
     },
   },
-};
+} as const;
 
 /**
  * Starts Android logcat broadcast websocket on the same host and port
@@ -56,12 +47,13 @@ export const supportedLogTypes = {
  * Each connected websocket listener will receive logcat log lines
  * as soon as they are visible to Appium.
  *
- * @this {import('../driver').AndroidDriver}
- * @returns {Promise<void>}
+ * @returns Promise that resolves when the logcat broadcasting websocket is started.
  */
-export async function mobileStartLogsBroadcast() {
-  const server = /** @type {import('@appium/types').AppiumServer} */ (this.server);
-  const pathname = WEBSOCKET_ENDPOINT(/** @type {string} */ (this.sessionId));
+export async function mobileStartLogsBroadcast(
+  this: AndroidDriver,
+): Promise<void> {
+  const server = this.server as AppiumServer;
+  const pathname = WEBSOCKET_ENDPOINT(this.sessionId as string);
   if (!_.isEmpty(await server.getWebSocketHandlers(pathname))) {
     this.log.debug(`The logcat broadcasting web socket server is already listening at ${pathname}`);
     return;
@@ -78,7 +70,7 @@ export async function mobileStartLogsBroadcast() {
   wss.on('connection', (ws, req) => {
     if (req) {
       const remoteIp = _.isEmpty(req.headers['x-forwarded-for'])
-        ? req.connection?.remoteAddress
+        ? req.socket.remoteAddress
         : req.headers['x-forwarded-for'];
       this.log.debug(`Established a new logcat listener web socket connection from ${remoteIp}`);
     } else {
@@ -86,7 +78,7 @@ export async function mobileStartLogsBroadcast() {
     }
 
     if (_.isEmpty(this._logcatWebsocketListener)) {
-      this._logcatWebsocketListener = (logRecord) => {
+      this._logcatWebsocketListener = (logRecord: LogEntry) => {
         if (ws?.readyState === WebSocket.OPEN) {
           ws.send(logRecord.message);
         }
@@ -112,19 +104,20 @@ export async function mobileStartLogsBroadcast() {
       this.log.debug(closeMsg);
     });
   });
-  await server.addWebSocketHandler(pathname, /** @type {import('@appium/types').WSServer} */ (wss));
+  await server.addWebSocketHandler(pathname, wss as WSServer);
 }
 
 /**
  * Stops the previously started logcat broadcasting wesocket server.
  * This method will return immediately if no server is running.
  *
- * @this {import('../driver').AndroidDriver}
- * @returns {Promise<void>}
+ * @returns Promise that resolves when the logcat broadcasting websocket is stopped.
  */
-export async function mobileStopLogsBroadcast() {
-  const pathname = WEBSOCKET_ENDPOINT(/** @type {string} */ (this.sessionId));
-  const server = /** @type {import('@appium/types').AppiumServer} */ (this.server);
+export async function mobileStopLogsBroadcast(
+  this: AndroidDriver,
+): Promise<void> {
+  const pathname = WEBSOCKET_ENDPOINT(this.sessionId as string);
+  const server = this.server as AppiumServer;
   if (_.isEmpty(await server.getWebSocketHandlers(pathname))) {
     return;
   }
@@ -137,40 +130,44 @@ export async function mobileStopLogsBroadcast() {
 }
 
 /**
- * @this {import('../driver').AndroidDriver}
- * @returns {Promise<string[]>}
+ * Gets the list of available log types.
+ *
+ * @returns Promise that resolves to an array of log type names.
  */
-export async function getLogTypes() {
+export async function getLogTypes(
+  this: AndroidDriver,
+): Promise<string[]> {
   // XXX why doesn't `super` work here?
   const nativeLogTypes = await BaseDriver.prototype.getLogTypes.call(this);
   if (this.isWebContext()) {
-    const webLogTypes = /** @type {string[]} */ (
-      await /** @type {import('appium-chromedriver').Chromedriver} */ (
-        this.chromedriver
-      ).jwproxy.command('/log/types', 'GET')
-    );
+    const webLogTypes = await (this.chromedriver as Chromedriver).jwproxy.command('/log/types', 'GET') as string[];
     return [...nativeLogTypes, ...webLogTypes];
   }
   return nativeLogTypes;
 }
 
 /**
+ * Assigns a BiDi log listener to an event emitter.
+ *
  * https://w3c.github.io/webdriver-bidi/#event-log-entryAdded
  *
- * @template {import('node:events').EventEmitter} EE
- * @this {import('../driver').AndroidDriver}
- * @param {EE} logEmitter
- * @param {BiDiListenerProperties} properties
- * @returns {[EE, LogListener]}
+ * @template EE The event emitter type.
+ * @param logEmitter The event emitter to attach the listener to.
+ * @param properties The BiDi listener properties.
+ * @returns A tuple containing the event emitter and the listener function.
  */
-export function assignBiDiLogListener (logEmitter, properties) {
+export function assignBiDiLogListener<EE extends EventEmitter>(
+  this: AndroidDriver,
+  logEmitter: EE,
+  properties: BiDiListenerProperties,
+): [EE, LogListener] {
   const {
     type,
     context = NATIVE_WIN,
     srcEventName = 'output',
     entryTransformer,
   } = properties;
-  const listener = (/** @type {import('../utils').LogEntry} */ logEntry) => {
+  const listener: LogListener = (logEntry: LogEntry) => {
     const finalEntry = entryTransformer ? entryTransformer(logEntry) : logEntry;
     this.eventEmitter.emit(BIDI_EVENT_NAME, makeLogEntryAddedEvent(finalEntry, context, type));
   };
@@ -179,42 +176,40 @@ export function assignBiDiLogListener (logEmitter, properties) {
 }
 
 /**
- * @this {import('../driver').AndroidDriver}
- * @param {string} logType
- * @returns {Promise<any>}
+ * Gets logs of a specific type.
+ *
+ * @param logType The type of logs to retrieve.
+ * @returns Promise that resolves to the logs for the specified type.
  */
-export async function getLog(logType) {
+export async function getLog(
+  this: AndroidDriver,
+  logType: string,
+): Promise<any> {
   if (this.isWebContext() && !_.keys(this.supportedLogTypes).includes(logType)) {
-    return await /** @type {import('appium-chromedriver').Chromedriver} */ (
-      this.chromedriver
-    ).jwproxy.command('/log', 'POST', {type: logType});
+    return await (this.chromedriver as Chromedriver).jwproxy.command('/log', 'POST', {type: logType});
   }
-  // XXX why doesn't `super` work here?
   return await BaseDriver.prototype.getLog.call(this, logType);
 }
 
 // #region Internal helpers
 
 /**
- * @param {string} sessionId
- * @returns {string}
+ * Generates the websocket endpoint path for logcat broadcasting.
+ *
+ * @param sessionId The session ID.
+ * @returns The websocket endpoint path.
  */
-const WEBSOCKET_ENDPOINT = (sessionId) =>
+const WEBSOCKET_ENDPOINT = (sessionId: string): string =>
   `${DEFAULT_WS_PATHNAME_PREFIX}/session/${sessionId}/appium/device/logcat`;
 
-
 // #endregion
 
-/**
- * @typedef {import('appium-adb').ADB} ADB
- */
+export interface BiDiListenerProperties {
+  type: string;
+  srcEventName?: string;
+  context?: string;
+  entryTransformer?: (x: LogEntry) => LogEntry;
+}
 
-/**
- * @typedef {Object} BiDiListenerProperties
- * @property {string} type
- * @property {string} [srcEventName='output']
- * @property {string} [context=NATIVE_WIN]
- * @property {(x: Object) => import('../utils').LogEntry} [entryTransformer]
- */
+export type LogListener = (logEntry: LogEntry) => any;
 
-/** @typedef {(logEntry: import('../utils').LogEntry) => any} LogListener */