appium-mac2-driver 3.4.3 → 4.0.0

package/lib/doctor/optional-checks.ts

@@ -1,5 +1,7 @@
-import {resolveExecutablePath} from './utils';
-import {doctor} from 'appium/support';
+import path from 'node:path';
+import os from 'node:os';
+import {resolveExecutablePath} from './utils.js';
+import {doctor, fs, util} from 'appium/support.js';
 import {exec} from 'teen_process';
 import type {IDoctorCheck, AppiumLogger, DoctorCheckResult} from '@appium/types';
 import '@colors/colors';
@@ -66,3 +68,126 @@ export class OptionalAutomationModeCheck implements IDoctorCheck {
   }
 }
 export const optionalAutomationModeCheck = new OptionalAutomationModeCheck();
+
+export class OptionalFullDiskAccessDaemonContainersCheck implements IDoctorCheck {
+  log!: AppiumLogger;
+  /**
+   * Upper-case UUID basename only (native recording attachment filenames). Expressed as glob
+   * segments because `fs.glob` does not accept arbitrary RegExps. Brace `{,tmp/}` matches legacy
+   * `Data/Attachments` and Xcode 26.5+ `Data/tmp/Attachments` in one pass.
+   */
+  private readonly NATIVE_RECORDING_ATTACHMENT_GLOB = (() => {
+    const h = '[0-9A-F]';
+    const seg = (n: number) => Array.from({length: n}, () => h).join('');
+    const uuid = `${seg(8)}-${seg(4)}-${seg(4)}-${seg(4)}-${seg(12)}`;
+    return `*/Data/{,tmp/}Attachments/${uuid}`;
+  })();
+  private readonly ANY_ATTACHMENT_GLOB = '*/Data/{,tmp/}Attachments/*';
+  private readonly DAEMON_CONTAINERS_ROOT = path.resolve(
+    os.homedir(),
+    'Library',
+    'Daemon Containers',
+  );
+
+  async diagnose(): Promise<DoctorCheckResult> {
+    const nonDarwin = this.checkIfNotDarwin();
+    if (nonDarwin) {
+      return nonDarwin;
+    }
+    const accessBlocked = await this.tryAccessDaemonContainers();
+    if (accessBlocked) {
+      return accessBlocked;
+    }
+    const uuidPathsOrErr = await this.globAttachmentsOrError();
+    if (!Array.isArray(uuidPathsOrErr)) {
+      return uuidPathsOrErr;
+    }
+    if (uuidPathsOrErr.length === 0) {
+      return await this.okWhenNoUuidAttachmentMatches();
+    }
+    return doctor.okOptional(
+      `This process can read "${this.DAEMON_CONTAINERS_ROOT}" ` +
+        `and found ${util.pluralize('matching path', uuidPathsOrErr.length, true)} under ` +
+        `*/Data/Attachments/ or */Data/tmp/Attachments/.`,
+    );
+  }
+
+  async fix(): Promise<string> {
+    return (
+      `Open ${'System Settings'.bold} → ${'Privacy & Security'.bold} → ${'Full Disk Access'.bold} ` +
+      `and enable the Terminal, IDE, or launchd parent that starts Appium Server. ` +
+      `Native screen recordings live under ` +
+      `~/Library/Daemon Containers/*/Data/Attachments/ or, since Xcode 26.5, ` +
+      `~/Library/Daemon Containers/*/Data/tmp/Attachments/. ` +
+      `This permission is required to retrieve videos from the XCTest daemon ` +
+      `(macos:startNativeScreenRecording / macos:stopNativeScreenRecording).`
+    );
+  }
+
+  hasAutofix(): boolean {
+    return false;
+  }
+
+  isOptional(): boolean {
+    return true;
+  }
+
+  private checkIfNotDarwin(): DoctorCheckResult | null {
+    if (process.platform === 'darwin') {
+      return null;
+    }
+    return doctor.okOptional(
+      `Full Disk Access to ${this.DAEMON_CONTAINERS_ROOT} can only be checked on macOS`,
+    );
+  }
+
+  private async tryAccessDaemonContainers(): Promise<DoctorCheckResult | null> {
+    try {
+      await fs.access(this.DAEMON_CONTAINERS_ROOT);
+      return null;
+    } catch (e) {
+      return doctor.nokOptional(
+        `Cannot access "${this.DAEMON_CONTAINERS_ROOT}": ${(e as Error).message}`,
+      );
+    }
+  }
+
+  private async globAttachmentsOrError(): Promise<string[] | DoctorCheckResult> {
+    try {
+      return await fs.glob(this.NATIVE_RECORDING_ATTACHMENT_GLOB, {
+        cwd: this.DAEMON_CONTAINERS_ROOT,
+        absolute: true,
+      });
+    } catch (e) {
+      return doctor.nokOptional(
+        `Cannot enumerate native recording attachments under "${this.DAEMON_CONTAINERS_ROOT}": ` +
+          `${(e as Error).message}`,
+      );
+    }
+  }
+
+  private async globAnyAttachmentsBestEffort(): Promise<string[]> {
+    try {
+      return await fs.glob(this.ANY_ATTACHMENT_GLOB, {
+        cwd: this.DAEMON_CONTAINERS_ROOT,
+        absolute: true,
+      });
+    } catch {
+      return [];
+    }
+  }
+
+  private async okWhenNoUuidAttachmentMatches(): Promise<DoctorCheckResult> {
+    const anyAttachmentPaths = await this.globAnyAttachmentsBestEffort();
+    return doctor.okOptional(
+      anyAttachmentPaths.length > 0
+        ? `This process can read "${this.DAEMON_CONTAINERS_ROOT}" ` +
+            `(found ${util.pluralize('path', anyAttachmentPaths.length, true)} under ` +
+            `*/Data/Attachments/* or */Data/tmp/Attachments/*, none matched the upper-case UUID filename glob).`
+        : `This process can read "${this.DAEMON_CONTAINERS_ROOT}" ` +
+            `(no files under */Data/Attachments/* or */Data/tmp/Attachments/* yet).`,
+    );
+  }
+}
+export const optionalFullDiskAccessDaemonContainersCheck =
+  new OptionalFullDiskAccessDaemonContainersCheck();

package/lib/doctor/required-checks.ts

@@ -1,4 +1,4 @@
-import {doctor} from 'appium/support';
+import {doctor} from 'appium/support.js';
 import {exec} from 'teen_process';
 import {getPath as getXcodePath} from 'appium-xcode';
 import type {IDoctorCheck, AppiumLogger, DoctorCheckResult} from '@appium/types';

package/lib/doctor/utils.ts

@@ -1,4 +1,4 @@
-import {fs} from 'appium/support';
+import {fs} from 'appium/support.js';
 
 /**
  * Return an executable path of cmd

package/lib/driver.ts

@@ -11,24 +11,24 @@ import type {
   DriverOpts,
   W3CDriverCaps,
 } from '@appium/types';
-import {BaseDriver, DeviceSettings} from 'appium/driver';
-import {WDA_MAC_SERVER, type WDAMacServer} from './wda-mac';
-import MAC2_CONSTRAINTS, {type Mac2Constraints} from './constraints';
-import * as appManagemenetCommands from './commands/app-management';
-import * as appleScriptCommands from './commands/applescript';
-import * as executeCommands from './commands/execute';
-import * as auditCommands from './commands/audit';
-import * as findCommands from './commands/find';
-import * as gesturesCommands from './commands/gestures';
-import * as navigationCommands from './commands/navigation';
-import * as recordScreenCommands from './commands/record-screen';
-import * as screenshotCommands from './commands/screenshots';
-import * as sourceCommands from './commands/source';
-import * as clipboardCommands from './commands/clipboard';
-import * as nativeScreenRecordingCommands from './commands/native-record-screen';
-import log from './logger';
-import {newMethodMap} from './method-map';
-import {executeMethodMap} from './execute-method-map';
+import {BaseDriver, DeviceSettings} from 'appium/driver.js';
+import {WDA_MAC_SERVER, type WDAMacServer} from './wda-mac.js';
+import MAC2_CONSTRAINTS, {type Mac2Constraints} from './constraints.js';
+import * as appManagemenetCommands from './commands/app-management.js';
+import * as appleScriptCommands from './commands/applescript.js';
+import * as executeCommands from './commands/execute.js';
+import * as auditCommands from './commands/audit.js';
+import * as findCommands from './commands/find.js';
+import * as gesturesCommands from './commands/gestures.js';
+import * as navigationCommands from './commands/navigation.js';
+import * as recordScreenCommands from './commands/record-screen.js';
+import * as screenshotCommands from './commands/screenshots.js';
+import * as sourceCommands from './commands/source.js';
+import * as clipboardCommands from './commands/clipboard.js';
+import * as nativeScreenRecordingCommands from './commands/native-record-screen.js';
+import log from './logger.js';
+import {newMethodMap} from './method-map.js';
+import {executeMethodMap} from './execute-method-map.js';
 
 const NO_PROXY: RouteMatcher[] = [
   ['GET', new RegExp('^/session/[^/]+/appium')],

package/lib/index.ts

@@ -1,4 +1,4 @@
-import {Mac2Driver} from './driver';
+import {Mac2Driver} from './driver.js';
 
 export default Mac2Driver;
 export {Mac2Driver};

package/lib/logger.ts

@@ -1,4 +1,4 @@
-import {logger} from 'appium/support';
+import {logger} from 'appium/support.js';
 
 const log = logger.getLogger('Mac2Driver');
 

package/lib/utils.ts

@@ -1,7 +1,9 @@
 import {exec} from 'teen_process';
-import {node} from 'appium/support';
+import {node} from 'appium/support.js';
+import {fileURLToPath} from 'node:url';
 
 const MODULE_NAME = 'appium-mac2-driver';
+const currentFilename = fileURLToPath(import.meta.url);
 
 /**
  * Calculates the path to the current module's root folder
@@ -15,7 +17,7 @@ export const getModuleRoot = function getModuleRoot(): string {
   if (moduleRootCache) {
     return moduleRootCache;
   }
-  const root = node.getModuleRootSync(MODULE_NAME, __filename);
+  const root = node.getModuleRootSync(MODULE_NAME, currentFilename);
   if (!root) {
     throw new Error(`Cannot find the root folder of the ${MODULE_NAME} Node.js module`);
   }
@@ -24,16 +26,12 @@ export const getModuleRoot = function getModuleRoot(): string {
 };
 
 /**
- * Retrieves process ids of all the children processes created by the given
- * parent process identifier
+ * Parses `ps` output and returns child process ids for the given parent pid.
  *
+ * @param stdout `ps` command output
  * @param parentPid parent process ID
- * @returns the list of matched children process ids
- * or an empty list if none matched
  */
-export async function listChildrenProcessIds(parentPid: number | string): Promise<string[]> {
-  const {stdout} = await exec('ps', ['axu', '-o', 'ppid']);
-  // USER  PID  %CPU %MEM  VSZ  RSS   TT  STAT STARTED  TIME COMMAND  PPID
+export function parseChildrenProcessIds(stdout: string, parentPid: number | string): string[] {
   return stdout
     .split('\n')
     .map((line) => line.trim())
@@ -46,6 +44,19 @@ export async function listChildrenProcessIds(parentPid: number | string): Promis
     .map(([pid]) => String(pid));
 }
 
+/**
+ * Retrieves process ids of all the children processes created by the given
+ * parent process identifier
+ *
+ * @param parentPid parent process ID
+ * @returns the list of matched children process ids
+ * or an empty list if none matched
+ */
+export async function listChildrenProcessIds(parentPid: number | string): Promise<string[]> {
+  const {stdout} = await exec('ps', ['axu', '-o', 'ppid']);
+  return parseChildrenProcessIds(stdout, parentPid);
+}
+
 /**
  * Clears the content of the given array.
  * @param items The array to clear.

package/lib/wda-mac.ts

@@ -2,14 +2,14 @@ import path from 'node:path';
 import url from 'node:url';
 import axios from 'axios';
 import {setTimeout as delay} from 'node:timers/promises';
-import {JWProxy, errors} from 'appium/driver';
-import {fs, logger, util, timing} from 'appium/support';
+import {JWProxy, errors} from 'appium/driver.js';
+import {fs, logger, util, timing} from 'appium/support.js';
 import {strongbox} from '@appium/strongbox';
 import {SubProcess, exec} from 'teen_process';
 import {waitForCondition} from 'asyncbox';
 import {checkPortStatus} from 'portscanner';
 import type {HTTPMethod, HTTPBody, ProxyResponse, ProxyOptions} from '@appium/types';
-import {listChildrenProcessIds, getModuleRoot, clearArray, removeAllOccurrences} from './utils';
+import {listChildrenProcessIds, getModuleRoot, clearArray, removeAllOccurrences} from './utils.js';
 
 const log = logger.getLogger('WebDriverAgentMac');