appium-mac2-driver 3.2.3 → 3.2.4

package/lib/commands/navigation.ts

@@ -0,0 +1,19 @@
+import type { Mac2Driver } from '../driver';
+
+/**
+ * Opens the given URL with the default or the given application.
+ * Xcode must be at version 14.3+.
+ *
+ * @param url - The URL to be opened.
+ * @param bundleId - The bundle identifier of an application to open
+ *                 the given url with. If not provided then the default application
+ *                 for the given url scheme is going to be used.
+ */
+export async function macosDeepLink(
+  this: Mac2Driver,
+  url: string,
+  bundleId?: string
+): Promise<unknown> {
+  return await this.wda.proxy.command('/url', 'POST', { url, bundleId });
+}
+

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

@@ -4,7 +4,8 @@ import { util, fs, tempDir } from 'appium/support';
 import { SubProcess } from 'teen_process';
 import B from 'bluebird';
 import { uploadRecordedMedia } from './helpers';
-
+import type { Mac2Driver } from '../driver';
+import type { AppiumLogger, StringRecord } from '@appium/types';
 
 const RETRY_PAUSE = 300;
 const RETRY_TIMEOUT = 5000;
@@ -15,94 +16,107 @@ const FFMPEG_BINARY = 'ffmpeg';
 const DEFAULT_FPS = 15;
 const DEFAULT_PRESET = 'veryfast';
 
+type Preset = 'ultrafast' | 'superfast' | 'veryfast' | 'faster' | 'fast' | 'medium' | 'slow' | 'slower' | 'veryslow';
+
+interface ScreenRecorderOptions {
+  fps?: number;
+  deviceId: string | number;
+  preset?: Preset;
+  captureCursor?: boolean;
+  captureClicks?: boolean;
+  videoFilter?: string;
+  timeLimit?: number;
+}
+
 /**
- * @param {import('@appium/types').AppiumLogger} log
+ * @param log - Logger instance
  */
-async function requireFfmpegPath (log) {
+async function requireFfmpegPath(log: AppiumLogger): Promise<string> {
   try {
     return await fs.which(FFMPEG_BINARY);
   } catch {
     throw log.errorWithException(
-      `${FFMPEG_BINARY} has not been found in PATH. ` +
-      `Please make sure it is installed`
+      `${FFMPEG_BINARY} has not been found in PATH. ` + `Please make sure it is installed`
     );
   }
 }
 
 export class ScreenRecorder {
+  private readonly _log: AppiumLogger;
+  private readonly _videoPath: string;
+  private _process: SubProcess | null;
+  private readonly _fps: number;
+  private readonly _deviceId: string | number;
+  private readonly _captureCursor?: boolean;
+  private readonly _captureClicks?: boolean;
+  private readonly _preset: Preset;
+  private readonly _videoFilter?: string;
+  private readonly _timeLimit: number;
+
   /**
    *
-   * @param {string} videoPath
-   * @param {import('@appium/types').AppiumLogger} log
-   * @param {ScreenRecorderOptions} opts
+   * @param videoPath - Path to the video file
+   * @param log - Logger instance
+   * @param opts - Screen recorder options
    */
-  constructor (videoPath, log, opts) {
+  constructor(videoPath: string, log: AppiumLogger, opts: ScreenRecorderOptions) {
     this._log = log;
     this._videoPath = videoPath;
     this._process = null;
-    this._fps = (opts.fps && opts.fps > 0) ? opts.fps : DEFAULT_FPS;
+    this._fps = opts.fps && opts.fps > 0 ? opts.fps : DEFAULT_FPS;
     this._deviceId = opts.deviceId;
     this._captureCursor = opts.captureCursor;
     this._captureClicks = opts.captureClicks;
     this._preset = opts.preset || DEFAULT_PRESET;
     this._videoFilter = opts.videoFilter;
-    this._timeLimit = (opts.timeLimit && opts.timeLimit > 0)
-      ? opts.timeLimit
-      : DEFAULT_TIME_LIMIT;
+    this._timeLimit =
+      opts.timeLimit && opts.timeLimit > 0 ? opts.timeLimit : DEFAULT_TIME_LIMIT;
   }
 
-  async getVideoPath () {
+  async getVideoPath(): Promise<string> {
     return (await fs.exists(this._videoPath)) ? this._videoPath : '';
   }
 
-  isRunning () {
+  isRunning(): boolean {
     return !!(this._process?.isRunning);
   }
 
-  async _enforceTermination () {
-    if (this._process && this.isRunning()) {
-      this._log.debug('Force-stopping the currently running video recording');
-      try {
-        await this._process.stop('SIGKILL');
-      } catch {}
-    }
-    this._process = null;
-    const videoPath = await this.getVideoPath();
-    if (videoPath) {
-      await fs.rimraf(videoPath);
-    }
-    return '';
-  }
-
-  async start () {
+  async start(): Promise<void> {
     const ffmpeg = await requireFfmpegPath(this._log);
 
-    /** @type {string[]} */
-    const args = [
-      '-loglevel', 'error',
-      '-t', `${this._timeLimit}`,
-      '-f', 'avfoundation',
+    const args: string[] = [
+      '-loglevel',
+      'error',
+      '-t',
+      `${this._timeLimit}`,
+      '-f',
+      'avfoundation',
       ...(this._captureCursor ? ['-capture_cursor', '1'] : []),
       ...(this._captureClicks ? ['-capture_mouse_clicks', '1'] : []),
-      '-framerate', `${this._fps}`,
-      '-i', `${this._deviceId}`,
-      '-vcodec', 'libx264',
-      '-preset', this._preset,
-      '-tune', 'zerolatency',
-      '-pix_fmt', 'yuv420p',
-      '-movflags', '+faststart',
-      '-fflags', 'nobuffer',
-      '-f', DEFAULT_EXT,
-      '-r', `${this._fps}`,
+      '-framerate',
+      `${this._fps}`,
+      '-i',
+      `${this._deviceId}`,
+      '-vcodec',
+      'libx264',
+      '-preset',
+      this._preset,
+      '-tune',
+      'zerolatency',
+      '-pix_fmt',
+      'yuv420p',
+      '-movflags',
+      '+faststart',
+      '-fflags',
+      'nobuffer',
+      '-f',
+      DEFAULT_EXT,
+      '-r',
+      `${this._fps}`,
       ...(this._videoFilter ? ['-filter:v', this._videoFilter] : []),
     ];
 
-    /** @type {string[]} */
-    const fullCmd = [
-      ffmpeg,
-      ...args,
-      this._videoPath,
-    ];
+    const fullCmd: string[] = [ffmpeg, ...args, this._videoPath];
     this._process = new SubProcess(fullCmd[0], fullCmd.slice(1));
     this._log.debug(`Starting ${FFMPEG_BINARY}: ${util.quote(fullCmd)}`);
     this._process.on('output', (stdout, stderr) => {
@@ -121,29 +135,34 @@ export class ScreenRecorder {
     });
     await this._process.start(0);
     try {
-      await waitForCondition(async () => {
-        if (await this.getVideoPath()) {
-          return true;
-        }
-        if (!this._process) {
-          throw new Error(`${FFMPEG_BINARY} process died unexpectedly`);
+      await waitForCondition(
+        async () => {
+          if (await this.getVideoPath()) {
+            return true;
+          }
+          if (!this._process) {
+            throw new Error(`${FFMPEG_BINARY} process died unexpectedly`);
+          }
+          return false;
+        },
+        {
+          waitMs: RETRY_TIMEOUT,
+          intervalMs: RETRY_PAUSE,
         }
-        return false;
-      }, {
-        waitMs: RETRY_TIMEOUT,
-        intervalMs: RETRY_PAUSE,
-      });
+      );
     } catch {
       await this._enforceTermination();
       throw this._log.errorWithException(
         `The expected screen record file '${this._videoPath}' does not exist. ` +
-        `Check the server log for more details`
+          `Check the server log for more details`
       );
     }
-    this._log.info(`The video recording has started. Will timeout in ${util.pluralize('second', this._timeLimit, true)}`);
+    this._log.info(
+      `The video recording has started. Will timeout in ${util.pluralize('second', this._timeLimit, true)}`
+    );
   }
 
-  async stop (force = false) {
+  async stop(force: boolean = false): Promise<string> {
     if (force) {
       return await this._enforceTermination();
     }
@@ -156,7 +175,9 @@ export class ScreenRecorder {
     return new B((resolve, reject) => {
       const timer = setTimeout(async () => {
         await this._enforceTermination();
-        reject(new Error(`Screen recording has failed to exit after ${PROCESS_SHUTDOWN_TIMEOUT}ms`));
+        reject(
+          new Error(`Screen recording has failed to exit after ${PROCESS_SHUTDOWN_TIMEOUT}ms`)
+        );
       }, PROCESS_SHUTDOWN_TIMEOUT);
 
       this._process?.once('exit', async (code, signal) => {
@@ -172,6 +193,23 @@ export class ScreenRecorder {
       this._process?.proc?.stdin?.end();
     });
   }
+
+  private async _enforceTermination(): Promise<string> {
+    if (this._process && this.isRunning()) {
+      this._log.debug('Force-stopping the currently running video recording');
+      try {
+        await this._process.stop('SIGKILL');
+      } catch {
+        // Ignore errors during force stop
+      }
+    }
+    this._process = null;
+    const videoPath = await this.getVideoPath();
+    if (videoPath) {
+      await fs.rimraf(videoPath);
+    }
+    return '';
+  }
 }
 
 /**
@@ -181,47 +219,48 @@ export class ScreenRecorder {
  * in System Preferences->Security & Privacy->Screen Recording.
  * The resulting video uses H264 codec and is ready to be played by media players built-in into web browsers.
  *
- * @this {Mac2Driver}
- * @param {string|number} deviceId Screen device index to use for the recording.
+ * @param deviceId - Screen device index to use for the recording.
  *                        The list of available devices could be retrieved using
  *                       `ffmpeg -f avfoundation -list_devices true -i` command.
- * @param {string|number} [timeLimit] The maximum recording time, in seconds. The default
+ * @param timeLimit - The maximum recording time, in seconds. The default
  *                        value is 600 seconds (10 minutes).
- * @param {string} [videoFilter] The video filter spec to apply for ffmpeg.
+ * @param videoFilter - The video filter spec to apply for ffmpeg.
  *                 See https://trac.ffmpeg.org/wiki/FilteringGuide for more details on the possible values.
  *                 Example: Set it to `scale=ifnot(gte(iw\,1024)\,iw\,1024):-2` in order to limit the video width
  *                 to 1024px. The height will be adjusted automatically to match the actual ratio.
- * @param {string|number} [fps] The count of frames per second in the resulting video.
+ * @param fps - The count of frames per second in the resulting video.
  *                        The greater fps it has the bigger file size is. 15 by default.
- * @param {'ultrafast'|'superfast'|'veryfast'|'faster'|'fast'|'medium'|'slow'|'slower'|'veryslow'} [preset]
- *         One of the supported encoding presets. A preset is a collection of options that will provide a
+ * @param preset - One of the supported encoding presets. A preset is a collection of options that will provide a
  *         certain encoding speed to compression ratio.
  *         A slower preset will provide better compression (compression is quality per filesize).
  *         This means that, for example, if you target a certain file size or constant bit rate, you will
  *         achieve better quality with a slower preset. Read https://trac.ffmpeg.org/wiki/Encode/H.264 for more details.
  *         `veryfast` by default
- * @param {boolean} [captureCursor] Whether to capture the mouse cursor while recording the screen.
+ * @param captureCursor - Whether to capture the mouse cursor while recording the screen.
  *                  False by default
- * @param {boolean} [captureClicks] Whether to capture mouse clicks while recording the screen.
+ * @param captureClicks - Whether to capture mouse clicks while recording the screen.
  *                  False by default.
- * @param {boolean} [forceRestart=true] Whether to ignore the call if a screen recording is currently running
-   *                (`false`) or to start a new recording immediately and terminate the existing one
-   *                if running (`true`). The default value is `true`.
+ * @param forceRestart - Whether to ignore the call if a screen recording is currently running
+ *                (`false`) or to start a new recording immediately and terminate the existing one
+ *                if running (`true`). The default value is `true`.
  * @throws {Error} If screen recording has failed to start or is not supported on the device under test.
  */
-export async function startRecordingScreen (
-  deviceId,
-  timeLimit,
-  videoFilter,
-  fps,
-  preset,
-  captureCursor,
-  captureClicks,
-  forceRestart = true
-) {
+export async function startRecordingScreen(
+  this: Mac2Driver,
+  deviceId: string | number,
+  timeLimit?: string | number,
+  videoFilter?: string,
+  fps?: string | number,
+  preset?: Preset,
+  captureCursor?: boolean,
+  captureClicks?: boolean,
+  forceRestart: boolean = true
+): Promise<void> {
   if (_.isNil(deviceId)) {
-    throw new Error(`'deviceId' option must be provided. Run 'ffmpeg -f avfoundation -list_devices true -i' ` +
-      'to fetch the list of available device ids');
+    throw new Error(
+      `'deviceId' option must be provided. Run 'ffmpeg -f avfoundation -list_devices true -i' ` +
+        'to fetch the list of available device ids'
+    );
   }
 
   if (this._screenRecorder?.isRunning?.()) {
@@ -239,58 +278,60 @@ export async function startRecordingScreen (
     prefix: util.uuidV4().substring(0, 8),
     suffix: `.${DEFAULT_EXT}`,
   });
-  this._screenRecorder = new ScreenRecorder(videoPath, this.log, {
-    fps: parseInt(`${fps}`, 10),
-    timeLimit: parseInt(`${timeLimit}`, 10),
-    preset,
-    captureCursor,
-    captureClicks,
-    videoFilter,
-    deviceId,
-  });
+  this._screenRecorder = new ScreenRecorder(
+    videoPath,
+    this.log,
+    {
+      fps: parseInt(`${fps}`, 10),
+      timeLimit: parseInt(`${timeLimit}`, 10),
+      preset,
+      captureCursor,
+      captureClicks,
+      videoFilter,
+      deviceId,
+    }
+  );
   try {
     await this._screenRecorder.start();
   } catch (e) {
     this._screenRecorder = null;
     throw e;
   }
-};
+}
 
 /**
  * Stop recording the screen.
  * If no screen recording has been started before then the method returns an empty string.
  *
- * @param {string} [remotePath] The path to the remote location, where the resulting video should be uploaded.
+ * @param remotePath - The path to the remote location, where the resulting video should be uploaded.
  *                              The following protocols are supported: http/https, ftp.
  *                              Null or empty string value (the default setting) means the content of resulting
  *                              file should be encoded as Base64 and passed as the endpoint response value.
  *                              An exception will be thrown if the generated media file is too big to
  *                              fit into the available process memory.
- * @param {string} [user] The name of the user for the remote authentication.
- * @param {string} [pass] The password for the remote authentication.
- * @param {string} [method] The http multipart upload method name. The 'PUT' one is used by default.
- * @param {import('@appium/types').StringRecord|[string, any][]} [headers]
- *                             Additional headers mapping for multipart http(s) uploads
- * @param {string} [fileFieldName] The name of the form field, where the file content BLOB should
+ * @param user - The name of the user for the remote authentication.
+ * @param pass - The password for the remote authentication.
+ * @param method - The http multipart upload method name. The 'PUT' one is used by default.
+ * @param headers - Additional headers mapping for multipart http(s) uploads
+ * @param fileFieldName - The name of the form field, where the file content BLOB should
  *                                 be stored for http(s) uploads
- * @param {import('@appium/types').StringRecord|[string, string][]} [formFields]
- *                              Additional form fields for multipart http(s) uploads
- * @returns {Promise<string>} Base64-encoded content of the recorded media file if 'remotePath'
+ * @param formFields - Additional form fields for multipart http(s) uploads
+ * @returns Base64-encoded content of the recorded media file if 'remotePath'
  * parameter is falsy or an empty string.
- * @this {Mac2Driver}
  * @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
  * or screen recording is not supported on the device under test.
  */
-export async function stopRecordingScreen (
-  remotePath,
-  user,
-  pass,
-  method,
-  headers,
-  fileFieldName,
-  formFields
-) {
+export async function stopRecordingScreen(
+  this: Mac2Driver,
+  remotePath?: string | null,
+  user?: string,
+  pass?: string,
+  method?: string,
+  headers?: StringRecord | [string, any][],
+  fileFieldName?: string,
+  formFields?: StringRecord | [string, string][]
+): Promise<string> {
   if (!this._screenRecorder) {
     this.log.debug('No screen recording has been started. Doing nothing');
     return '';
@@ -302,28 +343,14 @@ export async function stopRecordingScreen (
     this.log.debug('No video data is found. Returning an empty string');
     return '';
   }
-  const options = {
+  const options: StringRecord = {
     user,
     pass,
     method,
     headers,
     fileFieldName,
-    formFields
+    formFields,
   };
   return await uploadRecordedMedia.bind(this)(videoPath, remotePath, options);
-};
-
-/**
- * @typedef {import('../driver').Mac2Driver} Mac2Driver
- */
+}
 
-/**
- * @typedef {Object} ScreenRecorderOptions
- * @property {number} [fps]
- * @property {string|number} deviceId
- * @property {string} [preset]
- * @property {boolean} [captureCursor]
- * @property {boolean} [captureClicks]
- * @property {string} [videoFilter]
- * @property {number} [timeLimit]
- */

package/lib/commands/screenshots.ts

@@ -0,0 +1,18 @@
+import type { Mac2Driver } from '../driver';
+import type { ScreenshotsInfo } from '../types';
+
+/**
+ * Retrieves screenshots of each display available to macOS
+ *
+ * @param displayId - macOS display identifier to take a screenshot for.
+ *                 If not provided then screenshots of all displays are going to be returned.
+ *                 If no matches were found then an error is thrown.
+ * @returns Screenshots information for the requested display(s)
+ */
+export async function macosScreenshots(
+  this: Mac2Driver,
+  displayId?: number
+): Promise<ScreenshotsInfo> {
+  return (await this.wda.proxy.command('/wda/screenshots', 'POST', { displayId })) as ScreenshotsInfo;
+}
+

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

@@ -1,21 +1,20 @@
+import type { Mac2Driver } from '../driver';
+
 /**
  * Retrieves the string representation of the current application
  *
- * @this {Mac2Driver}
- * @param {string} [format='xml'] The format of the application source to retrieve.
+ * @param format - The format of the application source to retrieve.
  *                 Only two formats are supported:
  *                   - xml: Returns the source formatted as XML document (the default setting)
  *                   - description: Returns the source formatted as debugDescription output.
  *                 See https://developer.apple.com/documentation/xctest/xcuielement/1500909-debugdescription?language=objc
  *                 for more details.
- * @returns {Promise<string>} the page source in the requested format
+ * @returns the page source in the requested format
  */
-export async function macosSource (format = 'xml') {
-  return /** @type {String} */ (
-    await this.wda.proxy.command(`/source?format=${encodeURIComponent(format)}`, 'GET')
-  );
-};
+export async function macosSource(
+  this: Mac2Driver,
+  format: string = 'xml'
+): Promise<string> {
+  return (await this.wda.proxy.command(`/source?format=${encodeURIComponent(format)}`, 'GET')) as string;
+}
 
-/**
- * @typedef {import('../driver').Mac2Driver} Mac2Driver
- */

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "appium-mac2-driver",
-  "version": "3.2.3",
+  "version": "3.2.4",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "appium-mac2-driver",
-      "version": "3.2.3",
+      "version": "3.2.4",
       "license": "Apache-2.0",
       "dependencies": {
         "@appium/strongbox": "^1.0.0-rc.1",
@@ -1574,9 +1574,9 @@
       "license": "MIT"
     },
     "node_modules/color-string": {
-      "version": "2.1.3",
-      "resolved": "https://registry.npmjs.org/color-string/-/color-string-2.1.3.tgz",
-      "integrity": "sha512-r/wfcFshhORndnDjn3GtNVLA4QL4TAi0A/XIBNuWUIEAVyUBNWYLuckrDz/JM1aQlpIDzKuY5hAYdHcLYgwJsg==",
+      "version": "2.1.4",
+      "resolved": "https://registry.npmjs.org/color-string/-/color-string-2.1.4.tgz",
+      "integrity": "sha512-Bb6Cq8oq0IjDOe8wJmi4JeNn763Xs9cfrBcaylK1tPypWzyoy2G3l90v9k64kjphl/ZJjPIShFztenRomi8WTg==",
       "extraneous": true,
       "license": "MIT",
       "dependencies": {

package/package.json

@@ -6,7 +6,7 @@
     "mac",
     "XCTest"
   ],
-  "version": "3.2.3",
+  "version": "3.2.4",
   "author": "Appium Contributors",
   "license": "Apache-2.0",
   "repository": {

package/lib/commands/app-management.js

@@ -1,83 +0,0 @@
-/**
- * Start an app with given bundle identifier or activates it
- * if the app is already running. An exception is thrown if the
- * app with the given identifier cannot be found.
- *
- * @this {Mac2Driver}
- * @param {string} [bundleId] Bundle identifier of the app to be launched or activated.
- *                 Either this property or `path` must be provided
- * @param {string} [path] Full path to the app bundle. Either this property or
- *                 `bundleId` must be provided
- * @param {string[]} [args] The list of command line arguments for the app to be launched with.
- *                   This parameter is ignored if the app is already running.
- * @param {import('@appium/types').StringRecord} [environment] Environment variables mapping.
- *                   Custom variables are added to the default process environment.
- */
-export async function macosLaunchApp (
-  bundleId,
-  path,
-  args,
-  environment,
-) {
-  return await this.wda.proxy.command('/wda/apps/launch', 'POST', {
-    arguments: args,
-    environment,
-    bundleId,
-    path,
-  });
-};
-
-/**
- * Activate an app with given bundle identifier. An exception is thrown if the
- * app cannot be found or is not running.
- *
- * @this {Mac2Driver}
- * @param {string} [bundleId] Bundle identifier of the app to be activated.
- *                 Either this property or `path` must be provided
- * @param {string} [path] Full path to the app bundle. Either this property
- *                 or `bundleId` must be provided
- */
-export async function macosActivateApp (bundleId, path) {
-  return await this.wda.proxy.command('/wda/apps/activate', 'POST', { bundleId, path });
-};
-
-/**
- * Terminate an app with given bundle identifier. An exception is thrown if the
- * app cannot be found.
- *
- * @this {Mac2Driver}
- * @param {string} [bundleId] Bundle identifier of the app to be terminated.
- *                 Either this property or `path` must be provided
- * @param {string} [path] Full path to the app bundle. Either this property
- *                 or `bundleId` must be provided
- * @returns {Promise<boolean>} `true` if the app was running and has been successfully terminated.
- * `false` if the app was not running before.
- */
-export async function macosTerminateApp (bundleId, path) {
-  return /** @type {boolean} */ (
-    await this.wda.proxy.command('/wda/apps/terminate', 'POST', { bundleId, path })
-  );
-};
-
-/**
- * Query an app state with given bundle identifier. An exception is thrown if the
- * app cannot be found.
- *
- * @this {Mac2Driver}
- * @param {string} [bundleId] Bundle identifier of the app whose state should be queried.
- *                 Either this property or `path` must be provided
- * @param {string} [path] Full path to the app bundle. Either this property
- *                 or `bundleId` must be provided
- * @returns {Promise<number>} The application state code. See
- * https://developer.apple.com/documentation/xctest/xcuiapplicationstate?language=objc
- * for more details
- */
-export async function macosQueryAppState (bundleId, path) {
-  return /** @type {number} */ (
-    await this.wda.proxy.command('/wda/apps/state', 'POST', { bundleId, path })
-  );
-};
-
-/**
- * @typedef {import('../driver').Mac2Driver} Mac2Driver
- */