appium-android-driver 12.4.7 → 12.4.8

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

@@ -1,8 +1,12 @@
 import {fs, net, system, tempDir, timing, util} from '@appium/support';
+import type {NetOptions, HttpUploadOptions} from '@appium/support';
 import {waitForCondition} from 'asyncbox';
 import _ from 'lodash';
 import path from 'path';
 import {exec} from 'teen_process';
+import type {AndroidDriver} from '../driver';
+import type {ADB} from 'appium-adb';
+import type {StartScreenRecordingOpts, StopScreenRecordingOpts, ScreenRecordingProperties} from './types';
 
 const RETRY_PAUSE = 300;
 const RETRY_TIMEOUT = 5000;
@@ -17,12 +21,22 @@ const FFMPEG_BINARY = `ffmpeg${system.isWindows() ? '.exe' : ''}`;
 const ADB_PULL_TIMEOUT = 5 * 60 * 1000;
 
 /**
+ * Starts screen recording on the Android device.
  *
- * @this {import('../driver').AndroidDriver}
- * @param {import('./types').StartScreenRecordingOpts} [options={}]
- * @returns {Promise<string>}
+ * This method uses Android's `screenrecord` command to capture the screen.
+ * The recording can be configured with various options such as video size,
+ * bit rate, time limit, and more.
+ *
+ * @param options Recording options. See {@link StartScreenRecordingOpts} for details.
+ * @returns Promise that resolves to the result of stopping any previous recording,
+ * or an empty string if no previous recording was active.
+ * @throws {Error} If screen recording is not supported on the device or emulator,
+ * or if the time limit is invalid.
  */
-export async function startRecordingScreen(options = {}) {
+export async function startRecordingScreen(
+  this: AndroidDriver,
+  options: StartScreenRecordingOpts = {},
+): Promise<string> {
   await verifyScreenRecordIsSupported(this.adb, this.isEmulator());
 
   let result = '';
@@ -47,7 +61,8 @@ export async function startRecordingScreen(options = {}) {
 
   if (!_.isEmpty(this._screenRecordingProperties)) {
     // XXX: this doesn't need to be done in serial, does it?
-    for (const record of this._screenRecordingProperties.records || []) {
+    const props = this._screenRecordingProperties;
+    for (const record of props.records || []) {
       await this.adb.rimraf(record);
     }
     this._screenRecordingProperties = undefined;
@@ -61,7 +76,7 @@ export async function startRecordingScreen(options = {}) {
     );
   }
 
-  this._screenRecordingProperties = {
+  const recordingProps: ScreenRecordingProperties = {
     timer: new timing.Timer().start(),
     videoSize,
     timeLimit,
@@ -72,42 +87,55 @@ export async function startRecordingScreen(options = {}) {
     recordingProcess: null,
     stopped: false,
   };
-  await scheduleScreenRecord.bind(this)(this._screenRecordingProperties);
+  this._screenRecordingProperties = recordingProps;
+  await scheduleScreenRecord.bind(this)(recordingProps);
   return result;
 }
 
 /**
+ * Stops screen recording and returns the recorded video.
+ *
+ * This method stops any active screen recording session and returns the recorded
+ * video as a base64-encoded string or uploads it to a remote location if specified.
+ * If multiple recording chunks were created (for long recordings), they will be
+ * merged using ffmpeg if available.
  *
- * @this {import('../driver').AndroidDriver}
- * @param {import('./types').StopScreenRecordingOpts} [options={}]
- * @returns {Promise<string>}
+ * @param options Stop recording options. See {@link StopScreenRecordingOpts} for details.
+ * @returns Promise that resolves to the recorded video as a base64-encoded string
+ * if `remotePath` is not provided, or an empty string if the video was uploaded to a remote location.
+ * @throws {Error} If screen recording is not supported, no recording was active,
+ * or if the recording process cannot be stopped.
  */
-export async function stopRecordingScreen(options = {}) {
+export async function stopRecordingScreen(
+  this: AndroidDriver,
+  options: StopScreenRecordingOpts = {},
+): Promise<string> {
   await verifyScreenRecordIsSupported(this.adb, this.isEmulator());
 
-  if (!_.isEmpty(this._screenRecordingProperties)) {
-    this._screenRecordingProperties.stopped = true;
+  const props = this._screenRecordingProperties;
+  if (!_.isEmpty(props)) {
+    props.stopped = true;
   }
 
   try {
     await terminateBackgroundScreenRecording(this.adb, false);
   } catch (err) {
-    this.log.warn(/** @type {Error} */ (err).message);
-    if (!_.isEmpty(this._screenRecordingProperties)) {
+    this.log.warn((err as Error).message);
+    if (!_.isEmpty(props)) {
       this.log.warn('The resulting video might be corrupted');
     }
   }
 
-  if (_.isEmpty(this._screenRecordingProperties)) {
+  if (_.isEmpty(props)) {
     this.log.info(
       `Screen recording has not been previously started by Appium. There is nothing to stop`,
     );
     return '';
   }
 
-  if (this._screenRecordingProperties.recordingProcess?.isRunning) {
+  if (props.recordingProcess?.isRunning) {
     try {
-      await this._screenRecordingProperties.recordingProcess.stop(
+      await props.recordingProcess.stop(
         'SIGINT',
         PROCESS_SHUTDOWN_TIMEOUT,
       );
@@ -116,10 +144,10 @@ export async function stopRecordingScreen(options = {}) {
         `Unable to stop screen recording within ${PROCESS_SHUTDOWN_TIMEOUT}ms`,
       );
     }
-    this._screenRecordingProperties.recordingProcess = null;
+    props.recordingProcess = null;
   }
 
-  if (_.isEmpty(this._screenRecordingProperties.records)) {
+  if (_.isEmpty(props.records)) {
     throw this.log.errorWithException(
       `No screen recordings have been stored on the device so far. ` +
         `Are you sure the ${SCREENRECORD_BINARY} utility works as expected?`,
@@ -128,14 +156,14 @@ export async function stopRecordingScreen(options = {}) {
 
   const tmpRoot = await tempDir.openDir();
   try {
-    const localRecords = [];
-    for (const pathOnDevice of this._screenRecordingProperties.records) {
+    const localRecords: string[] = [];
+    for (const pathOnDevice of props.records) {
       const relativePath = path.resolve(tmpRoot, path.posix.basename(pathOnDevice));
       localRecords.push(relativePath);
       await this.adb.pull(pathOnDevice, relativePath, { timeout: ADB_PULL_TIMEOUT });
       await this.adb.rimraf(pathOnDevice);
     }
-    let resultFilePath = /** @type {string} */ (_.last(localRecords));
+    let resultFilePath = _.last(localRecords) as string;
     if (localRecords.length > 1) {
       this.log.info(`Got ${localRecords.length} screen recordings. Trying to merge them`);
       try {
@@ -143,7 +171,7 @@ export async function stopRecordingScreen(options = {}) {
       } catch (e) {
         this.log.warn(
           `Cannot merge the recorded files. The most recent screen recording is going to be returned as the result. ` +
-            `Original error: ${/** @type {Error} */ (e).message}`,
+            `Original error: ${(e as Error).message}`,
         );
       }
     }
@@ -162,23 +190,17 @@ export async function stopRecordingScreen(options = {}) {
 
 // #region Internal helpers
 
-/**
- *
- * @param {string} localFile
- * @param {string} [remotePath]
- * @param {import('./types').StopScreenRecordingOpts} uploadOptions
- * @returns {Promise<string>}
- */
-async function uploadRecordedMedia(localFile, remotePath, uploadOptions = {}) {
+async function uploadRecordedMedia(
+  localFile: string,
+  remotePath?: string,
+  uploadOptions: StopScreenRecordingOpts = {},
+): Promise<string> {
   if (_.isEmpty(remotePath)) {
     return (await util.toInMemoryBase64(localFile)).toString();
   }
 
   const {user, pass, method, headers, fileFieldName, formFields} = uploadOptions;
-  /**
-   * @type {import('@appium/support').NetOptions & import('@appium/support').HttpUploadOptions}
-   */
-  const options = {
+  const options: NetOptions & HttpUploadOptions = {
     method: method || 'PUT',
     headers,
     fileFieldName,
@@ -187,16 +209,11 @@ async function uploadRecordedMedia(localFile, remotePath, uploadOptions = {}) {
   if (user && pass) {
     options.auth = {user, pass};
   }
-  await net.uploadFile(localFile, /** @type {string} */ (remotePath), options);
+  await net.uploadFile(localFile, remotePath as string, options);
   return '';
 }
 
-/**
- *
- * @param {ADB} adb
- * @param {boolean} isEmulator
- */
-async function verifyScreenRecordIsSupported(adb, isEmulator) {
+async function verifyScreenRecordIsSupported(adb: ADB, isEmulator: boolean): Promise<void> {
   const apiLevel = await adb.getApiLevel();
   if (isEmulator && apiLevel < MIN_EMULATOR_API_LEVEL) {
     throw new Error(
@@ -205,12 +222,10 @@ async function verifyScreenRecordIsSupported(adb, isEmulator) {
   }
 }
 
-/**
- * @this {import('../driver').AndroidDriver}
- * @param {import('@appium/types').StringRecord} recordingProperties
- * @returns {Promise<void>}
- */
-async function scheduleScreenRecord(recordingProperties) {
+async function scheduleScreenRecord(
+  this: AndroidDriver,
+  recordingProperties: ScreenRecordingProperties,
+): Promise<void> {
   if (recordingProperties.stopped) {
     return;
   }
@@ -219,7 +234,7 @@ async function scheduleScreenRecord(recordingProperties) {
 
   let currentTimeLimit = MAX_RECORDING_TIME_SEC;
   if (util.hasValue(recordingProperties.currentTimeLimit)) {
-    const currentTimeLimitInt = parseInt(recordingProperties.currentTimeLimit, 10);
+    const currentTimeLimitInt = parseInt(String(recordingProperties.currentTimeLimit), 10);
     if (!isNaN(currentTimeLimitInt) && currentTimeLimitInt < MAX_RECORDING_TIME_SEC) {
       currentTimeLimit = currentTimeLimitInt;
     }
@@ -238,13 +253,13 @@ async function scheduleScreenRecord(recordingProperties) {
     }
     const currentDuration = timer.getDuration().asSeconds.toFixed(0);
     this.log.debug(`The overall screen recording duration is ${currentDuration}s so far`);
-    const timeLimitInt = parseInt(timeLimit, 10);
-    if (isNaN(timeLimitInt) || currentDuration >= timeLimitInt) {
+    const timeLimitInt = parseInt(String(timeLimit), 10);
+    if (isNaN(timeLimitInt) || Number(currentDuration) >= timeLimitInt) {
       this.log.debug('There is no need to start the next recording chunk');
       return;
     }
 
-    recordingProperties.currentTimeLimit = timeLimitInt - currentDuration;
+    recordingProperties.currentTimeLimit = timeLimitInt - Number(currentDuration);
     const chunkDuration =
       recordingProperties.currentTimeLimit < MAX_RECORDING_TIME_SEC
         ? recordingProperties.currentTimeLimit
@@ -257,7 +272,7 @@ async function scheduleScreenRecord(recordingProperties) {
       try {
         await scheduleScreenRecord.bind(this)(recordingProperties);
       } catch (e) {
-        this.log.error(/** @type {Error} */ (e).stack);
+        this.log.error((e as Error).stack);
         recordingProperties.stopped = true;
       }
     })();
@@ -280,13 +295,10 @@ async function scheduleScreenRecord(recordingProperties) {
   recordingProperties.recordingProcess = recordingProc;
 }
 
-/**
- *
- * @this {import('../driver').AndroidDriver}
- * @param {string[]} mediaFiles
- * @returns {Promise<string>}
- */
-async function mergeScreenRecords(mediaFiles) {
+async function mergeScreenRecords(
+  this: AndroidDriver,
+  mediaFiles: string[],
+): Promise<string> {
   try {
     await fs.which(FFMPEG_BINARY);
   } catch {
@@ -310,14 +322,9 @@ async function mergeScreenRecords(mediaFiles) {
   return result;
 }
 
-/**
- *
- * @param {ADB} adb
- * @param {boolean} force
- * @returns {Promise<boolean>}
- */
-async function terminateBackgroundScreenRecording(adb, force = true) {
-  const isScreenrecordRunning = async () => _.includes(await adb.listProcessStatus(), SCREENRECORD_BINARY);
+async function terminateBackgroundScreenRecording(adb: ADB, force = true): Promise<boolean> {
+  const isScreenrecordRunning = async (): Promise<boolean> =>
+    _.includes(await adb.listProcessStatus(), SCREENRECORD_BINARY);
   if (!await isScreenrecordRunning()) {
     return false;
   }
@@ -331,13 +338,10 @@ async function terminateBackgroundScreenRecording(adb, force = true) {
     return true;
   } catch (err) {
     throw new Error(
-      `Unable to stop the background screen recording: ${/** @type {Error} */ (err).message}`,
+      `Unable to stop the background screen recording: ${(err as Error).message}`,
     );
   }
 }
 
 // #endregion
 
-/**
- * @typedef {import('appium-adb').ADB} ADB
- */

package/lib/commands/types.ts

@@ -1,5 +1,7 @@
 import type {HTTPMethod, StringRecord} from '@appium/types';
 import type {AndroidDriverCaps} from '../driver';
+import type {SubProcess} from 'teen_process';
+import {timing} from '@appium/support';
 
 /**
  * @privateRemarks probably better defined in `appium-adb`
@@ -618,3 +620,18 @@ export interface InjectedImageProperties {
   position?: InjectedImagePosition;
   rotation?: InjectedImageRotation;
 }
+
+/**
+ * @internal
+ */
+export interface ScreenRecordingProperties {
+  timer: timing.Timer;
+  videoSize?: string;
+  timeLimit: string | number;
+  currentTimeLimit?: string | number;
+  bitRate?: string | number;
+  bugReport?: boolean;
+  records: string[];
+  recordingProcess: SubProcess | null;
+  stopped: boolean;
+}

package/lib/driver.ts

@@ -210,6 +210,7 @@ import {getSystemBars, mobilePerformStatusBarCommand} from './commands/system-ba
 import {getDeviceTime, mobileGetDeviceTime} from './commands/time';
 import { executeMethodMap } from './execute-method-map';
 import { LRUCache } from 'lru-cache';
+import type {ScreenRecordingProperties} from './commands/types';
 
 export type AndroidDriverCaps = DriverCaps<AndroidDriverConstraints>;
 export type W3CAndroidDriverCaps = W3CDriverCaps<AndroidDriverConstraints>;
@@ -240,7 +241,7 @@ class AndroidDriver
   _wasWindowAnimationDisabled?: boolean;
   _cachedActivityArgs: StringRecord;
   _screenStreamingProps?: StringRecord;
-  _screenRecordingProperties?: StringRecord;
+  _screenRecordingProperties?: ScreenRecordingProperties;
   _logcatWebsocketListener?: LogcatListener;
   _bidiServerLogListener?: (...args: any[]) => void;
   _bidiProxyUrl: string | null = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appium-android-driver",
-  "version": "12.4.7",
+  "version": "12.4.8",
   "description": "Android UiAutomator and Chrome support for Appium",
   "keywords": [
     "appium",