appium-xcuitest-driver 10.2.2 → 10.4.0

package/lib/commands/record-audio.js

@@ -11,6 +11,7 @@ const PROCESS_STARTUP_TIMEOUT_MS = 5000;
 const DEFAULT_EXT = '.mp4';
 const FFMPEG_BINARY = 'ffmpeg';
 const ffmpegLogger = logger.getLogger(FFMPEG_BINARY);
+
 export class AudioRecorder {
   constructor(input, log, audioPath, opts = {}) {
     this.input = input;
@@ -134,135 +135,129 @@ export class AudioRecorder {
   }
 }
 
-export default {
-  /**
-   * @type {AudioRecorder|null}
-   */
-  _audioRecorder: null,
-  /**
-   * Records the given hardware audio input and saves it into an `.mp4` file.
-   *
-   * **To use this command, the `audio_record` security feature must be enabled _and_ [FFMpeg](https://ffmpeg.org/) must be installed on the Appium server.**
-   *
-   * @param {string|number} audioInput - The name of the corresponding audio input device to use for the capture. The full list of capture devices could be shown by executing `ffmpeg -f avfoundation -list_devices true -i ""`
-   * @param {string|number} timeLimit - The maximum recording time, in seconds.
-   * @param {string} audioCodec - The name of the audio codec.
-   * @param {string} audioBitrate - The bitrate of the resulting audio stream.
-   * @param {string|number} audioChannels - The count of audio channels in the resulting stream. Setting it to `1` will create a single channel (mono) audio stream.
-   * @param {string|number} audioRate - The sampling rate of the resulting audio stream (in Hz).
-   * @param {boolean} forceRestart - Whether to restart audio capture process forcefully when `mobile: startRecordingAudio` is called (`true`) or ignore the call until the current audio recording is completed (`false`).
-   * @group Real Device Only
-   * @this {XCUITestDriver}
-   * @returns {Promise<void>}
-   * @privateRemarks Using string literals for the default parameters makes better documentation.
-   */
-  async startAudioRecording(
-    audioInput,
-    timeLimit = 180,
-    audioCodec = 'aac',
-    audioBitrate = '128k',
-    audioChannels = 2,
-    audioRate = 44100,
-    forceRestart = false,
-  ) {
-    if (!this.isFeatureEnabled(AUDIO_RECORD_FEAT_NAME)) {
-      throw this.log.errorWithException(
-        `Audio capture feature must be enabled on the server side. ` +
-          `Please set '--relaxed-security' or '--allow-insecure' with '${AUDIO_RECORD_FEAT_NAME}' option. ` +
-          `Read https://github.com/appium/appium/blob/master/docs/en/writing-running-appium/security.md for more details.`,
-      );
-    }
-    if (!audioInput) {
-      throw this.log.errorWithException(
-        `The mandatory audioInput option is not provided. Please set it ` +
-          `to a correct value (e. g. ':1'). Use 'ffmpeg -f avfoundation -list_devices true -i ""' ` +
-          `command to list available input sources`,
-      );
-    }
+/**
+ * Records the given hardware audio input and saves it into an `.mp4` file.
+ *
+ * **To use this command, the `audio_record` security feature must be enabled _and_ [FFMpeg](https://ffmpeg.org/) must be installed on the Appium server.**
+ *
+ * @param {string|number} audioInput - The name of the corresponding audio input device to use for the capture. The full list of capture devices could be shown by executing `ffmpeg -f avfoundation -list_devices true -i ""`
+ * @param {string|number} timeLimit - The maximum recording time, in seconds.
+ * @param {string} audioCodec - The name of the audio codec.
+ * @param {string} audioBitrate - The bitrate of the resulting audio stream.
+ * @param {string|number} audioChannels - The count of audio channels in the resulting stream. Setting it to `1` will create a single channel (mono) audio stream.
+ * @param {string|number} audioRate - The sampling rate of the resulting audio stream (in Hz).
+ * @param {boolean} forceRestart - Whether to restart audio capture process forcefully when `mobile: startRecordingAudio` is called (`true`) or ignore the call until the current audio recording is completed (`false`).
+ * @group Real Device Only
+ * @this {XCUITestDriver}
+ * @returns {Promise<void>}
+ * @privateRemarks Using string literals for the default parameters makes better documentation.
+ */
+export async function startAudioRecording(
+  audioInput,
+  timeLimit = 180,
+  audioCodec = 'aac',
+  audioBitrate = '128k',
+  audioChannels = 2,
+  audioRate = 44100,
+  forceRestart = false,
+) {
+  if (!this.isFeatureEnabled(AUDIO_RECORD_FEAT_NAME)) {
+    throw this.log.errorWithException(
+      `Audio capture feature must be enabled on the server side. ` +
+        `Please set '--relaxed-security' or '--allow-insecure' with '${AUDIO_RECORD_FEAT_NAME}' option. ` +
+        `Read https://github.com/appium/appium/blob/master/docs/en/writing-running-appium/security.md for more details.`,
+    );
+  }
+  if (!audioInput) {
+    throw this.log.errorWithException(
+      `The mandatory audioInput option is not provided. Please set it ` +
+        `to a correct value (e. g. ':1'). Use 'ffmpeg -f avfoundation -list_devices true -i ""' ` +
+        `command to list available input sources`,
+    );
+  }
 
-    if (this._audioRecorder?.isRecording()) {
-      this.log.info(`There is an active audio recording process`);
-      if (forceRestart) {
-        this.log.info(`Stopping it because 'forceRestart' option is set to true`);
-        await this._audioRecorder.interrupt(true);
-      } else {
-        this.log.info(
-          `Doing nothing. ` +
-            `Set 'forceRestart' option to true if you'd like to start a new audio recording session`,
-        );
-        return;
-      }
-    }
-    if (this._audioRecorder) {
-      await this._audioRecorder.cleanup();
-      this._audioRecorder = null;
+  if (this._audioRecorder?.isRecording()) {
+    this.log.info(`There is an active audio recording process`);
+    if (forceRestart) {
+      this.log.info(`Stopping it because 'forceRestart' option is set to true`);
+      await this._audioRecorder.interrupt(true);
+    } else {
+      this.log.info(
+        `Doing nothing. ` +
+          `Set 'forceRestart' option to true if you'd like to start a new audio recording session`,
+      );
+      return;
     }
+  }
+  if (this._audioRecorder) {
+    await this._audioRecorder.cleanup();
+    this._audioRecorder = null;
+  }
 
-    const audioPath = await tempDir.path({
-      prefix: `appium_${util.uuidV4().substring(0, 8)}`,
-      suffix: DEFAULT_EXT,
-    });
+  const audioPath = await tempDir.path({
+    prefix: `appium_${util.uuidV4().substring(0, 8)}`,
+    suffix: DEFAULT_EXT,
+  });
 
-    const audioRecorder = new AudioRecorder(audioInput, this.log, audioPath, {
-      audioSource: DEFAULT_SOURCE,
-      audioCodec,
-      audioBitrate,
-      audioChannels,
-      audioRate,
-    });
+  const audioRecorder = new AudioRecorder(audioInput, this.log, audioPath, {
+    audioSource: DEFAULT_SOURCE,
+    audioCodec,
+    audioBitrate,
+    audioChannels,
+    audioRate,
+  });
 
-    const timeoutSeconds = parseInt(String(timeLimit), 10);
-    if (isNaN(timeoutSeconds) || timeoutSeconds > MAX_RECORDING_TIME_SEC || timeoutSeconds <= 0) {
-      throw this.log.errorWithException(
-        `The timeLimit value must be in range [1, ${MAX_RECORDING_TIME_SEC}] seconds. ` +
-          `The value of '${timeLimit}' has been passed instead.`,
-      );
-    }
+  const timeoutSeconds = parseInt(String(timeLimit), 10);
+  if (isNaN(timeoutSeconds) || timeoutSeconds > MAX_RECORDING_TIME_SEC || timeoutSeconds <= 0) {
+    throw this.log.errorWithException(
+      `The timeLimit value must be in range [1, ${MAX_RECORDING_TIME_SEC}] seconds. ` +
+        `The value of '${timeLimit}' has been passed instead.`,
+    );
+  }
 
-    try {
-      await audioRecorder.start(timeoutSeconds);
-    } catch (e) {
-      await audioRecorder.interrupt(true);
-      await audioRecorder.cleanup();
-      throw e;
-    }
-    this._audioRecorder = audioRecorder;
-  },
+  try {
+    await audioRecorder.start(timeoutSeconds);
+  } catch (e) {
+    await audioRecorder.interrupt(true);
+    await audioRecorder.cleanup();
+    throw e;
+  }
+  this._audioRecorder = audioRecorder;
+}
 
-  /**
-   * Stop recording of the audio input. If no audio recording process is running then
-   * the endpoint will try to get the recently recorded file.
-   * If no previously recorded file is found and no active audio recording
-   * processes are running then the method returns an empty string.
-   *
-   * @returns {Promise<string>} Base64-encoded content of the recorded media file or an
-   * empty string if no audio recording has been started before.
-   * @throws {Error} If there was an error while getting the recorded file.
-   * @this {XCUITestDriver}
-   */
-  async stopAudioRecording() {
-    if (!this._audioRecorder) {
-      this.log.info('Audio recording has not been started. There is nothing to stop');
-      return '';
-    }
+/**
+ * Stop recording of the audio input. If no audio recording process is running then
+ * the endpoint will try to get the recently recorded file.
+ * If no previously recorded file is found and no active audio recording
+ * processes are running then the method returns an empty string.
+ *
+ * @returns {Promise<string>} Base64-encoded content of the recorded media file or an
+ * empty string if no audio recording has been started before.
+ * @throws {Error} If there was an error while getting the recorded file.
+ * @this {XCUITestDriver}
+ */
+export async function stopAudioRecording() {
+  if (!this._audioRecorder) {
+    this.log.info('Audio recording has not been started. There is nothing to stop');
+    return '';
+  }
 
-    let resultPath;
-    try {
-      resultPath = await this._audioRecorder.finish();
-      if (!(await fs.exists(resultPath))) {
-        throw this.log.errorWithException(
-          `${FFMPEG_BINARY} has failed ` + `to store the actual audio recording at '${resultPath}'`,
-        );
-      }
-    } catch (e) {
-      await this._audioRecorder.interrupt(true);
-      await this._audioRecorder.cleanup();
-      this._audioRecorder = null;
-      throw e;
+  let resultPath;
+  try {
+    resultPath = await this._audioRecorder.finish();
+    if (!(await fs.exists(resultPath))) {
+      throw this.log.errorWithException(
+        `${FFMPEG_BINARY} has failed ` + `to store the actual audio recording at '${resultPath}'`,
+      );
     }
-    return await encodeBase64OrUpload(resultPath);
-  },
-};
+  } catch (e) {
+    await this._audioRecorder.interrupt(true);
+    await this._audioRecorder.cleanup();
+    this._audioRecorder = null;
+    throw e;
+  }
+  return await encodeBase64OrUpload(resultPath);
+}
 
 /**
  * @typedef {import('../driver').XCUITestDriver} XCUITestDriver

package/lib/commands/recordscreen.js

@@ -226,169 +226,165 @@ export class ScreenRecorder {
   }
 }
 
-export default {
-  /** @type {ScreenRecorder?} */
-  _recentScreenRecorder: null,
-  /**
-   * Direct Appium to start recording the device screen
-   *
-   * Record the display of devices running iOS Simulator since Xcode 9 or real devices since iOS 11
-   * (ffmpeg utility is required: 'brew install ffmpeg').
-   * It records screen activity to a MPEG-4 file. Audio is not recorded with the video file.
-   * If screen recording has been already started then the command will stop it forcefully and start a new one.
-   * The previously recorded video file will be deleted.
-   *
-   * @param {import('./types').StartRecordingScreenOptions} [options] - The available options.
-   * @returns {Promise<string>} Base64-encoded content of the recorded media file if
-   *                   any screen recording is currently running or an empty string.
-   * @throws {Error} If screen recording has failed to start.
-   * @this {XCUITestDriver}
-   */
-  async startRecordingScreen(options = {}) {
-    const {
-      videoType = DEFAULT_VCODEC,
-      timeLimit = DEFAULT_RECORDING_TIME_SEC,
-      videoQuality = DEFAULT_QUALITY,
-      videoFps = DEFAULT_FPS,
-      videoFilters,
-      videoScale,
-      forceRestart,
-      pixelFormat,
-      hardwareAcceleration
-    } = options;
+/**
+ * Direct Appium to start recording the device screen
+ *
+ * Record the display of devices running iOS Simulator since Xcode 9 or real devices since iOS 11
+ * (ffmpeg utility is required: 'brew install ffmpeg').
+ * It records screen activity to a MPEG-4 file. Audio is not recorded with the video file.
+ * If screen recording has been already started then the command will stop it forcefully and start a new one.
+ * The previously recorded video file will be deleted.
+ *
+ * @param {import('./types').StartRecordingScreenOptions} [options] - The available options.
+ * @returns {Promise<string>} Base64-encoded content of the recorded media file if
+ *                   any screen recording is currently running or an empty string.
+ * @throws {Error} If screen recording has failed to start.
+ * @this {XCUITestDriver}
+ */
+export async function startRecordingScreen(options = {}) {
+  const {
+    videoType = DEFAULT_VCODEC,
+    timeLimit = DEFAULT_RECORDING_TIME_SEC,
+    videoQuality = DEFAULT_QUALITY,
+    videoFps = DEFAULT_FPS,
+    videoFilters,
+    videoScale,
+    forceRestart,
+    pixelFormat,
+    hardwareAcceleration
+  } = options;
 
-    let result = '';
-    if (!forceRestart) {
-      this.log.info(
-        `Checking if there is/was a previous screen recording. ` +
-        `Set 'forceRestart' option to 'true' if you'd like to skip this step.`
-      );
-      result = (await this.stopRecordingScreen(options)) ?? result;
-    }
+  let result = '';
+  if (!forceRestart) {
+    this.log.info(
+      `Checking if there is/was a previous screen recording. ` +
+      `Set 'forceRestart' option to 'true' if you'd like to skip this step.`
+    );
+    result = (await this.stopRecordingScreen(options)) ?? result;
+  }
 
-    const videoPath = await tempDir.path({
-      prefix: `appium_${Math.random().toString(16).substring(2, 8)}`,
-      suffix: MP4_EXT
-    });
+  const videoPath = await tempDir.path({
+    prefix: `appium_${Math.random().toString(16).substring(2, 8)}`,
+    suffix: MP4_EXT
+  });
 
-    const wdaBaseUrl = this.opts.wdaBaseUrl || WDA_BASE_URL;
-    const screenRecorder = new ScreenRecorder(this.device.udid, this.log, videoPath, {
-      remotePort: this.opts.mjpegServerPort || DEFAULT_MJPEG_SERVER_PORT,
-      remoteUrl: wdaBaseUrl,
-      videoType,
-      videoFilters,
-      videoScale,
-      videoFps,
-      pixelFormat,
-      hardwareAcceleration
-    });
-    if (!(await screenRecorder.interrupt(true))) {
-      throw this.log.errorWithException('Unable to stop screen recording process');
-    }
-    if (this._recentScreenRecorder) {
-      await this._recentScreenRecorder.cleanup();
-      this._recentScreenRecorder = null;
-    }
+  const wdaBaseUrl = this.opts.wdaBaseUrl || WDA_BASE_URL;
+  const screenRecorder = new ScreenRecorder(this.device.udid, this.log, videoPath, {
+    remotePort: this.opts.mjpegServerPort || DEFAULT_MJPEG_SERVER_PORT,
+    remoteUrl: wdaBaseUrl,
+    videoType,
+    videoFilters,
+    videoScale,
+    videoFps,
+    pixelFormat,
+    hardwareAcceleration
+  });
+  if (!(await screenRecorder.interrupt(true))) {
+    throw this.log.errorWithException('Unable to stop screen recording process');
+  }
+  if (this._recentScreenRecorder) {
+    await this._recentScreenRecorder.cleanup();
+    this._recentScreenRecorder = null;
+  }
 
-    const timeoutSeconds = parseFloat(String(timeLimit));
-    if (isNaN(timeoutSeconds) || timeoutSeconds > MAX_RECORDING_TIME_SEC || timeoutSeconds <= 0) {
-      throw this.log.errorWithException(
-        `The timeLimit value must be in range [1, ${MAX_RECORDING_TIME_SEC}] seconds. ` +
-          `The value of '${timeLimit}' has been passed instead.`,
+  const timeoutSeconds = parseFloat(String(timeLimit));
+  if (isNaN(timeoutSeconds) || timeoutSeconds > MAX_RECORDING_TIME_SEC || timeoutSeconds <= 0) {
+    throw this.log.errorWithException(
+      `The timeLimit value must be in range [1, ${MAX_RECORDING_TIME_SEC}] seconds. ` +
+        `The value of '${timeLimit}' has been passed instead.`,
+    );
+  }
+
+  let {mjpegServerScreenshotQuality, mjpegServerFramerate} =
+    /** @type {import('appium-webdriveragent').WDASettings} */ (
+    await this.proxyCommand('/appium/settings', 'GET')
+  );
+  if (videoQuality) {
+    const quality = _.isInteger(videoQuality)
+      ? videoQuality
+      : QUALITY_MAPPING[_.toLower(String(videoQuality))];
+    if (!quality) {
+      throw new Error(
+        `videoQuality value should be one of ${JSON.stringify(
+          _.keys(QUALITY_MAPPING)
+        )} or a number in range 1..100. ` + `'${videoQuality}' is given instead`
       );
     }
-
-    let {mjpegServerScreenshotQuality, mjpegServerFramerate} =
-      /** @type {import('appium-webdriveragent').WDASettings} */ (
-      await this.proxyCommand('/appium/settings', 'GET')
-    );
-    if (videoQuality) {
-      const quality = _.isInteger(videoQuality)
-        ? videoQuality
-        : QUALITY_MAPPING[_.toLower(String(videoQuality))];
-      if (!quality) {
-        throw new Error(
-          `videoQuality value should be one of ${JSON.stringify(
-            _.keys(QUALITY_MAPPING)
-          )} or a number in range 1..100. ` + `'${videoQuality}' is given instead`
-        );
-      }
-      mjpegServerScreenshotQuality = mjpegServerScreenshotQuality !== quality ? quality : undefined;
-    } else {
-      mjpegServerScreenshotQuality = undefined;
+    mjpegServerScreenshotQuality = mjpegServerScreenshotQuality !== quality ? quality : undefined;
+  } else {
+    mjpegServerScreenshotQuality = undefined;
+  }
+  if (videoFps) {
+    const fps = parseInt(String(videoFps), 10);
+    if (isNaN(fps)) {
+      throw new Error(
+        `videoFps value should be a valid number in range 1..60. ` +
+        `'${videoFps}' is given instead`
+      );
     }
-    if (videoFps) {
-      const fps = parseInt(String(videoFps), 10);
-      if (isNaN(fps)) {
-        throw new Error(
-          `videoFps value should be a valid number in range 1..60. ` +
-          `'${videoFps}' is given instead`
-        );
+    mjpegServerFramerate = mjpegServerFramerate !== fps ? fps : undefined;
+  } else {
+    mjpegServerFramerate = undefined;
+  }
+  if (util.hasValue(mjpegServerScreenshotQuality) || util.hasValue(mjpegServerFramerate)) {
+    await this.proxyCommand('/appium/settings', 'POST', {
+      settings: {
+        mjpegServerScreenshotQuality,
+        mjpegServerFramerate
       }
-      mjpegServerFramerate = mjpegServerFramerate !== fps ? fps : undefined;
-    } else {
-      mjpegServerFramerate = undefined;
-    }
-    if (util.hasValue(mjpegServerScreenshotQuality) || util.hasValue(mjpegServerFramerate)) {
-      await this.proxyCommand('/appium/settings', 'POST', {
-        settings: {
-          mjpegServerScreenshotQuality,
-          mjpegServerFramerate
-        }
-      });
-    }
+    });
+  }
 
-    try {
-      await screenRecorder.start(timeoutSeconds * 1000);
-    } catch (e) {
-      await screenRecorder.interrupt(true);
-      await screenRecorder.cleanup();
-      throw e;
-    }
-    this._recentScreenRecorder = screenRecorder;
+  try {
+    await screenRecorder.start(timeoutSeconds * 1000);
+  } catch (e) {
+    await screenRecorder.interrupt(true);
+    await screenRecorder.cleanup();
+    throw e;
+  }
+  this._recentScreenRecorder = screenRecorder;
 
-    return result;
-  },
+  return result;
+}
 
-  /**
-   * Direct Appium to stop screen recording and return the video
-   *
-   * If no screen recording process is running then the endpoint will try to get
-   * the recently recorded file. If no previously recorded file is found and no
-   * active screen recording processes are running then the method returns an
-   * empty string.
-   *
-   * @param {import('./types').StopRecordingScreenOptions} options - The available
-   * options.
-   * @returns {Promise<string?>} Base64-encoded content of the recorded media
-   * file if `remotePath` parameter is empty or null or an empty string.
-   * @throws {Error} If there was an error while getting the name of a media
-   *                 file or the file content cannot be uploaded to the remote
-   *                 location.
-   * @this {XCUITestDriver}
-   */
-  async stopRecordingScreen(options = {}) {
-    if (!this._recentScreenRecorder) {
-      this.log.info('Screen recording is not running. There is nothing to stop.');
-      return '';
-    }
+/**
+ * Direct Appium to stop screen recording and return the video
+ *
+ * If no screen recording process is running then the endpoint will try to get
+ * the recently recorded file. If no previously recorded file is found and no
+ * active screen recording processes are running then the method returns an
+ * empty string.
+ *
+ * @param {import('./types').StopRecordingScreenOptions} options - The available
+ * options.
+ * @returns {Promise<string?>} Base64-encoded content of the recorded media
+ * file if `remotePath` parameter is empty or null or an empty string.
+ * @throws {Error} If there was an error while getting the name of a media
+ *                 file or the file content cannot be uploaded to the remote
+ *                 location.
+ * @this {XCUITestDriver}
+ */
+export async function stopRecordingScreen(options = {}) {
+  if (!this._recentScreenRecorder) {
+    this.log.info('Screen recording is not running. There is nothing to stop.');
+    return '';
+  }
 
-    try {
-      const videoPath = await this._recentScreenRecorder.finish();
-      if (!(await fs.exists(videoPath))) {
-        throw this.log.errorWithException(
-          `The screen recorder utility has failed ` +
-          `to store the actual screen recording at '${videoPath}'`
-        );
-      }
-      return await encodeBase64OrUpload(videoPath, options.remotePath, options);
-    } finally {
-      await this._recentScreenRecorder.interrupt(true);
-      await this._recentScreenRecorder.cleanup();
-      this._recentScreenRecorder = null;
+  try {
+    const videoPath = await this._recentScreenRecorder.finish();
+    if (!(await fs.exists(videoPath))) {
+      throw this.log.errorWithException(
+        `The screen recorder utility has failed ` +
+        `to store the actual screen recording at '${videoPath}'`
+      );
     }
+    return await encodeBase64OrUpload(videoPath, options.remotePath, options);
+  } finally {
+    await this._recentScreenRecorder.interrupt(true);
+    await this._recentScreenRecorder.cleanup();
+    this._recentScreenRecorder = null;
   }
-};
+}
 
 /**
  * @typedef {import('../driver').XCUITestDriver} XCUITestDriver