@limrun/appium-xcuitest-driver 10.11.0-lim.4 → 10.14.6-lim.1

package/lib/commands/{record-audio.js → record-audio.ts}

@@ -2,6 +2,8 @@ import {fs, tempDir, logger, util} from 'appium/support';
 import {SubProcess} from 'teen_process';
 import {encodeBase64OrUpload} from '../utils';
 import {waitForCondition} from 'asyncbox';
+import type {XCUITestDriver} from '../driver';
+import type {AudioRecorderOptions} from './types';
 
 const MAX_RECORDING_TIME_SEC = 43200;
 const AUDIO_RECORD_FEAT_NAME = 'audio_record';
@@ -13,7 +15,13 @@ const FFMPEG_BINARY = 'ffmpeg';
 const ffmpegLogger = logger.getLogger(FFMPEG_BINARY);
 
 export class AudioRecorder {
-  constructor(input, log, audioPath, opts = {}) {
+  private readonly input: string | number;
+  private readonly log: any;
+  private readonly audioPath: string;
+  private readonly opts: AudioRecorderOptions;
+  private mainProcess: SubProcess | null;
+
+  constructor(input: string | number, log: any, audioPath: string, opts: AudioRecorderOptions = {} as AudioRecorderOptions) {
     this.input = input;
     this.log = log;
     this.audioPath = audioPath;
@@ -21,7 +29,7 @@ export class AudioRecorder {
     this.mainProcess = null;
   }
 
-  async start(timeoutSeconds) {
+  async start(timeoutSeconds: number): Promise<void> {
     try {
       await fs.which(FFMPEG_BINARY);
     } catch {
@@ -39,7 +47,7 @@ export class AudioRecorder {
       '-f',
       audioSource,
       '-i',
-      this.input,
+      String(this.input),
       '-c:a',
       audioCodec,
       '-b:a',
@@ -90,7 +98,7 @@ export class AudioRecorder {
     );
     this.mainProcess.once('exit', (code, signal) => {
       // ffmpeg returns code 255 if SIGINT arrives
-      if ([0, 255].includes(code)) {
+      if ([0, 255].includes(code ?? 0)) {
         this.log.info(`The recording session on audio input '${this.input}' has been finished`);
       } else {
         this.log.debug(
@@ -101,17 +109,17 @@ export class AudioRecorder {
     });
   }
 
-  isRecording() {
+  isRecording(): boolean {
     return !!this.mainProcess?.isRunning;
   }
 
-  async interrupt(force = false) {
+  async interrupt(force = false): Promise<boolean> {
     if (this.isRecording()) {
       const interruptPromise = this.mainProcess?.stop(force ? 'SIGTERM' : 'SIGINT');
       this.mainProcess = null;
       try {
         await interruptPromise;
-      } catch (e) {
+      } catch (e: any) {
         this.log.warn(
           `Cannot ${force ? 'terminate' : 'interrupt'} ${FFMPEG_BINARY}. ` +
             `Original error: ${e.message}`,
@@ -123,12 +131,12 @@ export class AudioRecorder {
     return true;
   }
 
-  async finish() {
+  async finish(): Promise<string> {
     await this.interrupt();
     return this.audioPath;
   }
 
-  async cleanup() {
+  async cleanup(): Promise<void> {
     if (await fs.exists(this.audioPath)) {
       await fs.rimraf(this.audioPath);
     }
@@ -140,27 +148,25 @@ export class AudioRecorder {
  *
  * **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`).
+ * @param 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 timeLimit - The maximum recording time, in seconds.
+ * @param audioCodec - The name of the audio codec.
+ * @param audioBitrate - The bitrate of the resulting audio stream.
+ * @param audioChannels - The count of audio channels in the resulting stream. Setting it to `1` will create a single channel (mono) audio stream.
+ * @param audioRate - The sampling rate of the resulting audio stream (in Hz).
+ * @param 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,
+  this: XCUITestDriver,
+  audioInput: string | number,
+  timeLimit: string | number = 180,
   audioCodec = 'aac',
   audioBitrate = '128k',
-  audioChannels = 2,
-  audioRate = 44100,
+  audioChannels: string | number = 2,
+  audioRate: string | number = 44100,
   forceRestart = false,
-) {
+): Promise<void> {
   if (!this.isFeatureEnabled(AUDIO_RECORD_FEAT_NAME)) {
     throw this.log.errorWithException(
       `Audio capture feature must be enabled on the server side. ` +
@@ -203,8 +209,8 @@ export async function startAudioRecording(
     audioSource: DEFAULT_SOURCE,
     audioCodec,
     audioBitrate,
-    audioChannels,
-    audioRate,
+    audioChannels: Number(audioChannels),
+    audioRate: Number(audioRate),
   });
 
   const timeoutSeconds = parseInt(String(timeLimit), 10);
@@ -231,18 +237,17 @@ export async function startAudioRecording(
  * 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
+ * @returns 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() {
+export async function stopAudioRecording(this: XCUITestDriver): Promise<string> {
   if (!this._audioRecorder) {
     this.log.info('Audio recording has not been started. There is nothing to stop');
     return '';
   }
 
-  let resultPath;
+  let resultPath: string;
   try {
     resultPath = await this._audioRecorder.finish();
     if (!(await fs.exists(resultPath))) {
@@ -259,6 +264,3 @@ export async function stopAudioRecording() {
   return await encodeBase64OrUpload(resultPath);
 }
 
-/**
- * @typedef {import('../driver').XCUITestDriver} XCUITestDriver
- */

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

@@ -5,6 +5,9 @@ import {encodeBase64OrUpload} from '../utils';
 import {WDA_BASE_URL} from 'appium-webdriveragent';
 import {waitForCondition} from 'asyncbox';
 import url from 'url';
+import type {XCUITestDriver} from '../driver';
+import type {StartRecordingScreenOptions, StopRecordingScreenOptions} from './types';
+import type {WDASettings} from 'appium-webdriveragent';
 
 /**
  * Set max timeout for 'reconnect_delay_max' ffmpeg argument usage.
@@ -20,14 +23,22 @@ const DEFAULT_VCODEC = 'mjpeg';
 const MP4_EXT = '.mp4';
 const FFMPEG_BINARY = 'ffmpeg';
 const ffmpegLogger = logger.getLogger(FFMPEG_BINARY);
-const QUALITY_MAPPING = {
+const QUALITY_MAPPING: Record<string, number> = {
   low: 10,
   medium: 25,
   high: 75,
   photo: 100,
 };
 
-const HARDWARE_ACCELERATION_PARAMETERS = {
+const HARDWARE_ACCELERATION_PARAMETERS: Record<
+  string,
+  {
+    hwaccel: string;
+    hwaccelOutputFormat: string;
+    scaleFilterHWAccel: string;
+    videoTypeHWAccel: string;
+  }
+> = {
   /* https://trac.ffmpeg.org/wiki/HWAccelIntro#VideoToolbox */
   videoToolbox: {
     hwaccel: 'videotoolbox',
@@ -54,21 +65,28 @@ const HARDWARE_ACCELERATION_PARAMETERS = {
     hwaccel: 'qsv',
     hwaccelOutputFormat: '',
     scaleFilterHWAccel: 'scale_qsv',
-    videoTypeHWAccel: 'h264_qsv'
+    videoTypeHWAccel: 'h264_qsv',
   },
   /* https://trac.ffmpeg.org/wiki/Hardware/VAAPI */
   vaapi: {
     hwaccel: 'vaapi',
     hwaccelOutputFormat: 'vaapi',
     scaleFilterHWAccel: 'scale_vaapi',
-    videoTypeHWAccel: 'h264_vaapi'
-  }
+    videoTypeHWAccel: 'h264_vaapi',
+  },
 };
 
 const CAPTURE_START_MARKER = /^\s*frame=/;
 
 export class ScreenRecorder {
-  constructor(udid, log, videoPath, opts = {}) {
+  private readonly videoPath: string;
+  private readonly log: any;
+  private readonly opts: ScreenRecorderOptions;
+  private readonly udid: string;
+  private mainProcess: SubProcess | null;
+  private timeoutHandler: NodeJS.Timeout | null;
+
+  constructor(udid: string, log: any, videoPath: string, opts: ScreenRecorderOptions = {}) {
     this.videoPath = videoPath;
     this.log = log;
     this.opts = opts;
@@ -77,7 +95,7 @@ export class ScreenRecorder {
     this.timeoutHandler = null;
   }
 
-  async start(timeoutMs) {
+  async start(timeoutMs: number): Promise<void> {
     try {
       await fs.which(FFMPEG_BINARY);
     } catch {
@@ -98,7 +116,7 @@ export class ScreenRecorder {
       pixelFormat,
     } = this.opts;
 
-    const args = [
+    const args: string[] = [
       '-f',
       'mjpeg',
       // https://github.com/appium/appium/issues/16294
@@ -115,8 +133,8 @@ export class ScreenRecorder {
       hwaccel,
       hwaccelOutputFormat,
       scaleFilterHWAccel,
-      videoTypeHWAccel
-    } = HARDWARE_ACCELERATION_PARAMETERS[hardwareAcceleration] ?? {};
+      videoTypeHWAccel,
+    } = HARDWARE_ACCELERATION_PARAMETERS[hardwareAcceleration || ''] ?? {};
 
     if (hwaccel) {
       args.push('-hwaccel', hwaccel);
@@ -127,10 +145,10 @@ export class ScreenRecorder {
     }
 
     //Parameter `-r` is optional. See details: https://github.com/appium/appium/issues/12067
-    if (videoFps && videoType === 'libx264' || videoTypeHWAccel) {
-      args.push('-r', videoFps);
+    if ((videoFps && videoType === 'libx264') || videoTypeHWAccel) {
+      args.push('-r', String(videoFps));
     }
-    const {protocol, hostname} = url.parse(remoteUrl);
+    const {protocol, hostname} = url.parse(remoteUrl || '');
     args.push('-i', `${protocol}//${hostname}:${remotePort}`);
 
     if (videoFilters || videoScale) {
@@ -141,13 +159,13 @@ export class ScreenRecorder {
     if (pixelFormat) {
       args.push('-pix_fmt', pixelFormat);
     }
-    args.push('-vcodec', videoTypeHWAccel || videoType);
+    args.push('-vcodec', videoTypeHWAccel || videoType || DEFAULT_VCODEC);
     args.push('-y');
     args.push(this.videoPath);
 
     this.mainProcess = new SubProcess(FFMPEG_BINARY, args);
     let isCaptureStarted = false;
-    this.mainProcess.on('line-stderr', (line) => {
+    this.mainProcess.on('line-stderr', (line: string) => {
       if (CAPTURE_START_MARKER.test(line)) {
         if (!isCaptureStarted) {
           isCaptureStarted = true;
@@ -175,9 +193,8 @@ export class ScreenRecorder {
       );
     }
     this.log.info(
-      `Starting screen capture on the device '${
-        this.udid
-      }' with command: '${FFMPEG_BINARY} ${args.join(' ')}'. ` + `Will timeout in ${timeoutMs}ms`,
+      `Starting screen capture on the device '${this.udid}' with command: '${FFMPEG_BINARY} ${args.join(' ')}'. ` +
+        `Will timeout in ${timeoutMs}ms`,
     );
 
     this.timeoutHandler = setTimeout(async () => {
@@ -189,7 +206,7 @@ export class ScreenRecorder {
     }, timeoutMs);
   }
 
-  async interrupt(force = false) {
+  async interrupt(force = false): Promise<boolean> {
     let result = true;
 
     if (this.timeoutHandler) {
@@ -202,7 +219,7 @@ export class ScreenRecorder {
       this.mainProcess = null;
       try {
         await interruptPromise;
-      } catch (e) {
+      } catch (e: any) {
         this.log.warn(
           `Cannot ${force ? 'terminate' : 'interrupt'} ${FFMPEG_BINARY}. ` +
             `Original error: ${e.message}`,
@@ -214,12 +231,12 @@ export class ScreenRecorder {
     return result;
   }
 
-  async finish() {
+  async finish(): Promise<string> {
     await this.interrupt();
     return this.videoPath;
   }
 
-  async cleanup() {
+  async cleanup(): Promise<void> {
     if (await fs.exists(this.videoPath)) {
       await fs.rimraf(this.videoPath);
     }
@@ -235,13 +252,15 @@ export class ScreenRecorder {
  * 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
+ * @param options - The available options.
+ * @returns 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 = {}) {
+export async function startRecordingScreen(
+  this: XCUITestDriver,
+  options: StartRecordingScreenOptions = {},
+): Promise<string> {
   const {
     videoType = DEFAULT_VCODEC,
     timeLimit = DEFAULT_RECORDING_TIME_SEC,
@@ -251,21 +270,21 @@ export async function startRecordingScreen(options = {}) {
     videoScale,
     forceRestart,
     pixelFormat,
-    hardwareAcceleration
+    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.`
+        `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
+    suffix: MP4_EXT,
   });
 
   const wdaBaseUrl = this.opts.wdaBaseUrl || WDA_BASE_URL;
@@ -275,9 +294,9 @@ export async function startRecordingScreen(options = {}) {
     videoType,
     videoFilters,
     videoScale,
-    videoFps,
+    videoFps: typeof videoFps === 'string' ? parseInt(videoFps, 10) : videoFps,
     pixelFormat,
-    hardwareAcceleration
+    hardwareAcceleration,
   });
   if (!(await screenRecorder.interrupt(true))) {
     throw this.log.errorWithException('Unable to stop screen recording process');
@@ -295,10 +314,10 @@ export async function startRecordingScreen(options = {}) {
     );
   }
 
-  let {mjpegServerScreenshotQuality, mjpegServerFramerate} =
-    /** @type {import('appium-webdriveragent').WDASettings} */ (
-    await this.proxyCommand('/appium/settings', 'GET')
-  );
+  let {mjpegServerScreenshotQuality, mjpegServerFramerate} = (await this.proxyCommand(
+    '/appium/settings',
+    'GET',
+  )) as WDASettings;
   if (videoQuality) {
     const quality = _.isInteger(videoQuality)
       ? videoQuality
@@ -306,11 +325,12 @@ export async function startRecordingScreen(options = {}) {
     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`
+          _.keys(QUALITY_MAPPING),
+        )} or a number in range 1..100. ` + `'${videoQuality}' is given instead`,
       );
     }
-    mjpegServerScreenshotQuality = mjpegServerScreenshotQuality !== quality ? quality : undefined;
+    mjpegServerScreenshotQuality =
+      mjpegServerScreenshotQuality !== quality ? (quality as number) : undefined;
   } else {
     mjpegServerScreenshotQuality = undefined;
   }
@@ -319,7 +339,7 @@ export async function startRecordingScreen(options = {}) {
     if (isNaN(fps)) {
       throw new Error(
         `videoFps value should be a valid number in range 1..60. ` +
-        `'${videoFps}' is given instead`
+          `'${videoFps}' is given instead`,
       );
     }
     mjpegServerFramerate = mjpegServerFramerate !== fps ? fps : undefined;
@@ -330,8 +350,8 @@ export async function startRecordingScreen(options = {}) {
     await this.proxyCommand('/appium/settings', 'POST', {
       settings: {
         mjpegServerScreenshotQuality,
-        mjpegServerFramerate
-      }
+        mjpegServerFramerate,
+      },
     });
   }
 
@@ -355,16 +375,17 @@ export async function startRecordingScreen(options = {}) {
  * 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
+ * @param options - The available options.
+ * @returns 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 = {}) {
+export async function stopRecordingScreen(
+  this: XCUITestDriver,
+  options: StopRecordingScreenOptions = {},
+): Promise<string | null> {
   if (!this._recentScreenRecorder) {
     this.log.info('Screen recording is not running. There is nothing to stop.');
     return '';
@@ -375,7 +396,7 @@ export async function stopRecordingScreen(options = {}) {
     if (!(await fs.exists(videoPath))) {
       throw this.log.errorWithException(
         `The screen recorder utility has failed ` +
-        `to store the actual screen recording at '${videoPath}'`
+          `to store the actual screen recording at '${videoPath}'`,
       );
     }
     return await encodeBase64OrUpload(videoPath, options.remotePath, options);
@@ -386,6 +407,13 @@ export async function stopRecordingScreen(options = {}) {
   }
 }
 
-/**
- * @typedef {import('../driver').XCUITestDriver} XCUITestDriver
- */
+interface ScreenRecorderOptions {
+  hardwareAcceleration?: string;
+  remotePort?: number;
+  remoteUrl?: string;
+  videoFps?: number;
+  videoType?: string;
+  videoScale?: string;
+  videoFilters?: string;
+  pixelFormat?: string;
+}

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

@@ -2,19 +2,23 @@ import {retryInterval} from 'asyncbox';
 import _ from 'lodash';
 import {errors} from 'appium/driver';
 import {util, imageUtil} from 'appium/support';
+import type {XCUITestDriver} from '../driver';
+import type {Simulator} from 'appium-ios-simulator';
+import type {Element} from '@appium/types';
 
 /**
- * @this {XCUITestDriver}
- * @returns {Promise<string>}
+ * Takes a screenshot of the current screen.
+ *
+ * @returns Base64-encoded screenshot data
  */
-export async function getScreenshot() {
+export async function getScreenshot(this: XCUITestDriver): Promise<string> {
   if (this.isWebContext()) {
     const webScreenshotMode = (await this.settings.getSettings()).webScreenshotMode;
     switch (_.toLower(webScreenshotMode)) {
       case 'page':
       case 'viewport':
-        return await (/** @type {import('appium-remote-debugger').RemoteDebugger} */ (this.remote)).captureScreenshot({
-          coordinateSystem: /** @type {'Viewport'|'Page'} */ (_.capitalize(webScreenshotMode)),
+        return await this.remote.captureScreenshot({
+          coordinateSystem: _.capitalize(webScreenshotMode) as 'Viewport' | 'Page',
         });
       case 'native':
       case undefined:
@@ -29,7 +33,7 @@ export async function getScreenshot() {
     }
   }
 
-  const getScreenshotFromWDA = async () => {
+  const getScreenshotFromWDA = async (): Promise<string> => {
     this.log.debug(`Taking screenshot with WDA`);
     const data = await this.proxyCommand('/screenshot', 'GET');
     if (!_.isString(data)) {
@@ -53,14 +57,14 @@ export async function getScreenshot() {
 
   try {
     return await getScreenshotFromWDA();
-  } catch (err) {
+  } catch (err: any) {
     this.log.warn(`Error getting screenshot: ${err.message}`);
   }
 
   // simulator attempt
   if (this.isSimulator()) {
     this.log.info(`Falling back to 'simctl io screenshot' API`);
-    const payload = await /** @type {import('appium-ios-simulator').Simulator} */ (this.device).simctl.getScreenshot();
+    const payload = await (this.device as Simulator).simctl.getScreenshot();
     if (!payload) {
       throw new errors.UnableToCaptureScreen();
     }
@@ -68,13 +72,19 @@ export async function getScreenshot() {
   }
 
   // Retry for real devices only. Fail fast on Simulator if simctl does not work as expected
-  return /** @type {string} */ (await retryInterval(2, 1000, getScreenshotFromWDA));
+  return await retryInterval(2, 1000, getScreenshotFromWDA) as string;
 }
 
 /**
- * @this {XCUITestDriver}
+ * Takes a screenshot of a specific element.
+ *
+ * @param el - Element to capture
+ * @returns Base64-encoded screenshot data
  */
-export async function getElementScreenshot(el) {
+export async function getElementScreenshot(
+  this: XCUITestDriver,
+  el: Element<string> | string,
+): Promise<string> {
   el = util.unwrapElement(el);
   if (this.isWebContext()) {
     const atomsElement = this.getAtomsElement(el);
@@ -83,8 +93,7 @@ export async function getElementScreenshot(el) {
       throw new errors.UnableToCaptureScreen('Cannot take a screenshot of a zero-size element');
     }
     const {x, y} = await this.executeAtom('get_top_left_coordinates', [atomsElement]);
-    return await (/** @type {import('appium-remote-debugger').RemoteDebugger} */ (this.remote))
-      .captureScreenshot({rect: {x, y, width, height}});
+    return await this.remote.captureScreenshot({rect: {x, y, width, height}});
   }
 
   const data = await this.proxyCommand(`/element/${el}/screenshot`, 'GET');
@@ -97,13 +106,13 @@ export async function getElementScreenshot(el) {
 }
 
 /**
- * @this {XCUITestDriver}
- * @returns {Promise<string>}
+ * Takes a screenshot of the current viewport.
+ *
+ * @returns Base64-encoded screenshot data
  */
-export async function getViewportScreenshot() {
+export async function getViewportScreenshot(this: XCUITestDriver): Promise<string> {
   if (this.isWebContext()) {
-    return await (/** @type {import('appium-remote-debugger').RemoteDebugger} */ (this.remote))
-      .captureScreenshot();
+    return await this.remote.captureScreenshot();
   }
 
   const screenshot = await this.getScreenshot();
@@ -132,6 +141,3 @@ export async function getViewportScreenshot() {
   return await imageUtil.cropBase64Image(screenshot, region);
 }
 
-/**
- * @typedef {import('../driver').XCUITestDriver} XCUITestDriver
- */

package/lib/commands/simctl.ts

@@ -0,0 +1,82 @@
+import { errors } from 'appium/driver';
+import type {XCUITestDriver} from '../driver';
+import type {Simulator} from 'appium-ios-simulator';
+
+/**
+ * List of subcommands for `simctl` we provide as mobile simctl command.
+ * They accept 'device' target.
+ */
+const SUBCOMMANDS_HAS_DEVICE = [
+  'boot',
+  'get_app_container',
+  'getenv',
+  'icloud_sync',
+  'install',
+  'install_app_data',
+  'io',
+  'keychain',
+  'launch',
+  'location',
+  'logverbose',
+  'openurl',
+  'pbcopy',
+  'pbpaste',
+  'privacy',
+  'push',
+  'shutdown',
+  'spawn',
+  'status_bar',
+  'terminate',
+  'ui',
+  'uninstall'
+] as const;
+
+export interface SimctlExecResponse {
+  /** The output of standard out. */
+  stdout: string;
+  /** The output of standard error. */
+  stderr: string;
+  /** Return code. */
+  code: number;
+}
+
+/**
+ * Run the given command with arguments as `xcrun simctl` subcommand.
+ * This method works behind the 'simctl' security flag.
+ *
+ * @param command - Subcommand to run with `xcrun simctl`. Must be one of the supported commands.
+ * @param args - Arguments for the subcommand. The arguments should be after <device> in the help.
+ * @param timeout - The maximum number of milliseconds
+ * @returns The execution result with stdout, stderr, and return code
+ * @throws If the simctl subcommand command returns non-zero return code, or the given subcommand was invalid.
+ */
+export async function mobileSimctl(
+  this: XCUITestDriver,
+  command: string,
+  args: string[] = [],
+  timeout?: number,
+): Promise<SimctlExecResponse> {
+  if (!this.isSimulator()) {
+    throw new errors.UnsupportedOperationError(`Only simulator is supported.`);
+  }
+
+  if (!this.opts.udid) {
+    throw new errors.InvalidArgumentError(`Unknown device or simulator UDID: '${this.opts.udid}'`);
+  }
+
+  if (!(SUBCOMMANDS_HAS_DEVICE as readonly string[]).includes(command)) {
+    throw new errors.InvalidArgumentError(`The given command '${command}' is not supported. ` +
+      `Available subcommands are ${SUBCOMMANDS_HAS_DEVICE.join(',')}`);
+  }
+
+  const result = await (this.device as Simulator).simctl.exec(
+    command as typeof SUBCOMMANDS_HAS_DEVICE[number],
+    {args: [this.opts.udid, ...args], timeout}
+  );
+  return {
+    stdout: result?.stdout ?? '',
+    stderr: result?.stderr ?? '',
+    code: result?.code ?? 0
+  };
+}
+