appium-mac2-driver 2.0.0 → 2.1.0

package/lib/commands/native-record-screen.ts

@@ -0,0 +1,180 @@
+import _ from 'lodash';
+import path from 'node:path';
+import { fs, util } from 'appium/support';
+import type { Mac2Driver } from '../driver';
+import { uploadRecordedMedia } from './helpers';
+import type { StringRecord } from '@appium/types';
+
+/**
+ * Initiates a new native screen recording session via XCTest.
+ * If the screen recording is already running then this call results in noop.
+ * A screen recording is running until a testing session is finished.
+ * If a recording has never been stopped explicitly during a test session
+ * then it would be stopped automatically upon test session termination,
+ * and leftover videos would be deleted as well.
+ *
+ * @since Xcode 15
+ * @param fps Frame Per Second setting for the resulting screen recording. 24 by default.
+ * @param codec Possible codec value, where `0` means H264 (the default setting), `1` means HEVC
+ * @param displayId Valid display identifier to record the video from. Main display is assumed
+ * by default.
+ * @returns The information about the asynchronously running video recording.
+ */
+export async function macosStartNativeScreenRecording(
+  this: Mac2Driver,
+  fps?: number,
+  codec?: number,
+  displayId?: number,
+): Promise<ActiveVideoInfo> {
+  const result = await this.wda.proxy.command('/wda/video/start', 'POST', {
+    fps,
+    codec,
+    displayId,
+  }) as ActiveVideoInfo;
+  this._recordedVideoIds.add(result.uuid);
+  return result;
+}
+
+/**
+ * @since Xcode 15
+ * @returns The information about the asynchronously running video recording or
+ * null if no native video recording has been started.
+ */
+export async function macosGetNativeScreenRecordingInfo(
+  this: Mac2Driver
+): Promise<ActiveVideoInfo | null> {
+  return await this.wda.proxy.command('/wda/video', 'GET') as ActiveVideoInfo | null;
+}
+
+/**
+ * Stops native screen recordind.
+ * If no screen recording has been started before then the method throws an exception.
+ *
+ * @since Xcode 15
+ * @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 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 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.
+ * @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 macosStopNativeScreenRecording(
+  this: Mac2Driver,
+  remotePath?: string,
+  user?: string,
+  pass?: string,
+  method?: string,
+  headers?: StringRecord|[string, any][],
+  fileFieldName?: string,
+  formFields?: StringRecord|[string, string][],
+): Promise<string> {
+  const response: ActiveVideoInfo | null = (
+    await this.wda.proxy.command('/wda/video/stop', 'POST', {})
+  ) as ActiveVideoInfo | null;
+  if (!response || !_.isPlainObject(response)) {
+    throw new Error(
+      'There is no active screen recording, thus nothing to stop. Did you start it before?'
+    );
+  }
+
+  const { uuid } = response;
+  const matchedVideoPath = _.first(
+    (await listAttachments()).filter((name) => name.endsWith(uuid))
+  );
+  if (!matchedVideoPath) {
+    throw new Error(
+      `The screen recording identified by ${uuid} has not been found. Is it accessible?`
+    );
+  }
+  const options = {
+    user,
+    pass,
+    method,
+    headers,
+    fileFieldName,
+    formFields
+  };
+  const result = await uploadRecordedMedia.bind(this)(matchedVideoPath, remotePath, options);
+  await cleanupNativeRecordedVideos.bind(this)(uuid);
+  this._recordedVideoIds.delete(uuid);
+  return result;
+}
+
+/**
+ * Deletes previously recorded videos with given ids.
+ * This call is safe and does not raise any errors.
+ *
+ * @param uuids One or more video UUIDs to be deleted
+ */
+export async function cleanupNativeRecordedVideos(
+  this: Mac2Driver,
+  uuids: string | Set<string>,
+): Promise<void> {
+  const attachments = await listAttachments();
+  if (_.isEmpty(attachments)) {
+    return;
+  }
+  const tasks: Promise<any>[] = attachments
+    .map((attachmentPath) => [path.basename(attachmentPath), attachmentPath])
+    .filter(([name,]) => _.isString(uuids) ? uuids === name : uuids.has(name))
+    .map(([, attachmentPath]) => fs.rimraf(attachmentPath));
+  if (_.isEmpty(tasks)) {
+    return;
+  }
+  try {
+    await Promise.all(tasks);
+    this.log.debug(
+      `Successfully deleted ${util.pluralize('leftover video recording', tasks.length, true)}`
+    );
+  } catch (e) {
+    this.log.warn(`Could not cleanup some leftover video recordings: ${e.message}`);
+  }
+}
+
+/**
+ * Fetches information about available displays
+ *
+ * @returns A map where keys are display identifiers and values are display infos
+ */
+export async function macosListDisplays(this: Mac2Driver): Promise<StringRecord<DisplayInfo>> {
+  return await this.wda.proxy.command('/wda/displays/list', 'GET') as StringRecord<DisplayInfo>;
+}
+
+// #region Private functions
+
+async function listAttachments(): Promise<string[]> {
+  // The expected path looks like
+  // $HOME/Library/Daemon Containers/EFDD24BF-F856-411F-8954-CD5F0D6E6F3E/Data/Attachments/CAE7E5E2-5AC9-4D33-A47B-C491D644DE06
+  const deamonContainersRoot = path.resolve(process.env.HOME as string, 'Library', 'Daemon Containers');
+  return await fs.glob(`*/Data/Attachments/*`, {
+    cwd: deamonContainersRoot,
+    absolute: true,
+  });
+}
+
+interface ActiveVideoInfo {
+  fps: number;
+  codec: number;
+  displayId: number;
+  uuid: string;
+  startedAt: number;
+}
+
+interface DisplayInfo {
+  id: number;
+  isMain: boolean;
+}
+
+// #endregion

package/lib/commands/record-screen.js

@@ -1,8 +1,9 @@
 import _ from 'lodash';
 import { waitForCondition } from 'asyncbox';
-import { util, fs, net, tempDir } from 'appium/support';
+import { util, fs, tempDir } from 'appium/support';
 import { SubProcess } from 'teen_process';
 import B from 'bluebird';
+import { uploadRecordedMedia } from './helpers';
 
 
 const RETRY_PAUSE = 300;
@@ -14,35 +15,6 @@ const FFMPEG_BINARY = 'ffmpeg';
 const DEFAULT_FPS = 15;
 const DEFAULT_PRESET = 'veryfast';
 
-/**
- *
- * @this {Mac2Driver}
- * @param {string} localFile
- * @param {string?} remotePath
- * @param {import('@appium/types').StringRecord} [uploadOptions={}]
- * @returns
- */
-async function uploadRecordedMedia (localFile, remotePath = null, uploadOptions = {}) {
-  if (_.isEmpty(remotePath) || _.isNil(remotePath)) {
-    const {size} = await fs.stat(localFile);
-    this.log.debug(`The size of the resulting screen recording is ${util.toReadableSizeString(size)}`);
-    return (await util.toInMemoryBase64(localFile)).toString();
-  }
-
-  const {user, pass, method, headers, fileFieldName, formFields} = uploadOptions;
-  const options = {
-    method: method || 'PUT',
-    headers,
-    fileFieldName,
-    formFields,
-  };
-  if (user && pass) {
-    options.auth = {user, pass};
-  }
-  await net.uploadFile(localFile, remotePath, options);
-  return '';
-}
-
 /**
  * @param {import('@appium/types').AppiumLogger} log
  */

package/lib/driver.js

@@ -14,6 +14,7 @@ import * as sourceCommands from './commands/source';
 import log from './logger';
 import { newMethodMap } from './method-map';
 import { executeMethodMap } from './execute-method-map';
+import * as nativeScreenRecordingCommands from './commands/native-record-screen';
 
 /** @type {import('@appium/types').RouteMatcher[]} */
 const NO_PROXY = [
@@ -34,6 +35,9 @@ export class Mac2Driver extends BaseDriver {
   /** @type {import('./wda-mac').WDAMacServer} */
   wda;
 
+  /** @type {Set<string>} */
+  _recordedVideoIds;
+
   static newMethodMap = newMethodMap;
   static executeMethodMap = executeMethodMap;
 
@@ -71,6 +75,7 @@ export class Mac2Driver extends BaseDriver {
     this.wda = null;
     this.proxyReqRes = null;
     this.isProxyActive = false;
+    this._recordedVideoIds = new Set();
     this._screenRecorder = null;
   }
 
@@ -131,6 +136,14 @@ export class Mac2Driver extends BaseDriver {
 
   async deleteSession () {
     await this._screenRecorder?.stop(true);
+    if (!_.isEmpty(this._recordedVideoIds)) {
+      try {
+        await this.wda.proxy.command('/wda/video/stop', 'POST', {});
+      } catch {}
+      await nativeScreenRecordingCommands.cleanupNativeRecordedVideos.bind(this)(
+        this._recordedVideoIds
+      );
+    }
     await this.wda.stopSession();
 
     if (this.opts.postrun) {
@@ -187,6 +200,11 @@ export class Mac2Driver extends BaseDriver {
   startRecordingScreen = recordScreenCommands.startRecordingScreen;
   stopRecordingScreen = recordScreenCommands.stopRecordingScreen;
 
+  macosStartNativeScreenRecording = nativeScreenRecordingCommands.macosStartNativeScreenRecording;
+  macosGetNativeScreenRecordingInfo = nativeScreenRecordingCommands.macosGetNativeScreenRecordingInfo;
+  macosStopNativeScreenRecording = nativeScreenRecordingCommands.macosStopNativeScreenRecording;
+  macosListDisplays = nativeScreenRecordingCommands.macosListDisplays;
+
   macosScreenshots = screenshotCommands.macosScreenshots;
 
   macosSource = sourceCommands.macosSource;

package/lib/execute-method-map.ts

@@ -302,4 +302,34 @@ export const executeMethodMap = {
       ],
     },
   },
+  'macos: startNativeScreenRecording': {
+    command: 'macosStartNativeScreenRecording',
+    params: {
+      optional: [
+        'fps',
+        'codec',
+        'displayId',
+      ],
+    },
+  },
+  'macos: getNativeScreenRecordingInfo': {
+    command: 'macosGetNativeScreenRecordingInfo',
+  },
+  'macos: stopNativeScreenRecording': {
+    command: 'macosStopNativeScreenRecording',
+    params: {
+      optional: [
+        'remotePath',
+        'user',
+        'pass',
+        'method',
+        'headers',
+        'fileFieldName',
+        'formFields'
+      ],
+    },
+  },
+  'macos: listDisplays': {
+    command: 'macosListDisplays',
+  },
 } as const satisfies ExecuteMethodMap<any>;

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "appium-mac2-driver",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "appium-mac2-driver",
-      "version": "2.0.0",
+      "version": "2.1.0",
       "license": "Apache-2.0",
       "dependencies": {
         "@appium/strongbox": "^0.x",

package/package.json

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