appium-mac2-driver 4.4.0 → 4.5.0

package/lib/commands/windows.ts

@@ -0,0 +1,44 @@
+import type {Mac2Driver} from '../driver.js';
+import type {AdjustedWindowInfo, WindowInfo, WindowState} from '../types.js';
+
+/**
+ * Lists the windows of the current application
+ *
+ * @returns Information about each window, including its element identifier
+ */
+export async function macosListWindows(this: Mac2Driver): Promise<WindowInfo[]> {
+  return (await this.wda.proxy.command('/wda/windows', 'GET')) as WindowInfo[];
+}
+
+/**
+ * Changes the state and/or geometry of an application window, optionally moving it to another display
+ *
+ * @param windowId - Identifier of the window element. The main window is used by default
+ * @param state - The state to put the window into
+ * @param x - Horizontal origin. Global, or relative to the display if `displayId` is set
+ * @param y - Vertical origin. Global, or relative to the display if `displayId` is set
+ * @param width - Window width
+ * @param height - Window height
+ * @param displayId - Identifier of the display to move the window to
+ * @returns The updated window information. `windowId` is null if a minimized window was adjusted
+ */
+export async function macosAdjustWindow(
+  this: Mac2Driver,
+  windowId?: string,
+  state?: WindowState,
+  x?: number,
+  y?: number,
+  width?: number,
+  height?: number,
+  displayId?: number,
+): Promise<AdjustedWindowInfo> {
+  return (await this.wda.proxy.command('/wda/window/adjust', 'POST', {
+    windowId,
+    state,
+    x,
+    y,
+    width,
+    height,
+    displayId,
+  })) as AdjustedWindowInfo;
+}

package/lib/driver.ts

@@ -25,6 +25,7 @@ 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 windowCommands from './commands/windows.js';
 import MAC2_CONSTRAINTS, {type Mac2Constraints} from './constraints.js';
 import {executeMethodMap} from './execute-method-map.js';
 import log from './logger.js';
@@ -111,6 +112,9 @@ export class Mac2Driver
 
   macosSource = sourceCommands.macosSource;
 
+  macosListWindows = windowCommands.macosListWindows;
+  macosAdjustWindow = windowCommands.macosAdjustWindow;
+
   _videoChunksBroadcaster!: nativeScreenRecordingCommands.NativeVideoChunksBroadcaster;
   _screenRecorder: recordScreenCommands.ScreenRecorder | null = null;
   public proxyReqRes!: (...args: any) => any;

package/lib/execute-method-map.ts

@@ -130,6 +130,15 @@ export const executeMethodMap = {
       optional: ['displayId'],
     },
   },
+  'macos: listWindows': {
+    command: 'macosListWindows',
+  },
+  'macos: adjustWindow': {
+    command: 'macosAdjustWindow',
+    params: {
+      optional: ['windowId', 'state', 'x', 'y', 'width', 'height', 'displayId'],
+    },
+  },
   'macos: appleScript': {
     command: 'macosExecAppleScript',
     params: {

package/lib/types.ts

@@ -26,3 +26,31 @@ export interface ScreenshotInfo {
 
 /** A dictionary where each key contains a unique display identifier */
 export type ScreenshotsInfo = StringRecord<ScreenshotInfo>;
+
+export interface Rect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export type WindowState = 'normal' | 'minimized' | 'maximized' | 'fullscreen';
+
+export interface WindowInfo {
+  /** Identifier of the window element */
+  windowId: string;
+  title: string;
+  rect: Rect;
+  /** The display that contains most of the window, if any */
+  displayId: number | null;
+  /** Traits below are null if the Accessibility permission is not granted */
+  isMain: boolean | null;
+  isFocused: boolean | null;
+  isMinimized: boolean | null;
+  isFullscreen: boolean | null;
+  isMovable: boolean | null;
+  isResizable: boolean | null;
+}
+
+/** `windowId` is null if a minimized window has been adjusted */
+export type AdjustedWindowInfo = Omit<WindowInfo, 'windowId'> & {windowId: string | null};

package/node_modules/bare-url/README.md

@@ -28,6 +28,10 @@ require('bare-url/global')
 
 See the [`bare-url` reference](https://docs.pears.com/reference/bare/modules/bare-url).
 
+## Threat model
+
+`bare-url` is one of the addons Bare compiles into its binary, so it inherits [Bare's threat model](https://github.com/holepunchto/bare/blob/main/docs/threat-model.md). See [`docs/threat-model.md`](docs/threat-model.md) for where this addon sits in it.
+
 ## License
 
 Apache-2.0

package/node_modules/bare-url/index.d.ts

@@ -87,6 +87,9 @@ declare namespace URL {
   /**
    * Convert a platform-specific file path to a `file:` URL.
    * @param pathname - The platform-specific file path to convert.
+   * @throws {INVALID_ARG_VALUE} (Windows) the path is a UNC path with an empty server name or
+   * no resource path.
+   * @throws {INVALID_URL} the path does not form a valid `file:` URL.
    */
   export function pathToFileURL(pathname: string): URL
 

package/node_modules/bare-url/index.js

@@ -494,6 +494,26 @@ function encodePath(value) {
   return value.replace(pathDelimiterAll, (match) => escapes[match])
 }
 
+function encodeFilePath(value) {
+  // Paths hardly ever contain any of these, so one pass to rule them out is
+  // cheaper than the six or seven replacements it stands in for.
+  if (!reserved.test(value)) return value
+
+  value = value
+    .replaceAll('%', '%25') // Must be first
+    .replaceAll('#', '%23')
+    .replaceAll('?', '%3f')
+    .replaceAll('\n', '%0a')
+    .replaceAll('\r', '%0d')
+    .replaceAll('\t', '%09')
+
+  if (!isWindows) {
+    value = value.replaceAll('\\', '%5c')
+  }
+
+  return value
+}
+
 function encodeQuery(value) {
   if (value.indexOf('#') === -1) return value
 
@@ -600,7 +620,27 @@ exports.fileURLToPath = function fileURLToPath(url) {
 }
 
 exports.pathToFileURL = function pathToFileURL(pathname) {
-  let resolved = path.resolve(pathname)
+  const isUNC = isWindows && pathname.startsWith('\\\\')
+
+  let resolved = isUNC ? pathname : path.resolve(pathname)
+
+  if (isUNC || (isWindows && resolved.startsWith('\\\\'))) {
+    // https://learn.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation
+    const hostStart = resolved.startsWith('\\\\?\\UNC\\') ? 8 : 2
+    const hostEnd = resolved.indexOf('\\', hostStart)
+
+    if (hostEnd === -1) {
+      throw errors.INVALID_ARG_VALUE('Missing UNC resource path')
+    }
+
+    if (hostEnd === 2) {
+      throw errors.INVALID_ARG_VALUE('Empty UNC servername')
+    }
+
+    const hostname = truncateHost('file', resolved.slice(hostStart, hostEnd))
+
+    return new URL('file://' + hostname + encodeFilePath(resolved.slice(hostEnd)))
+  }
 
   if (pathname[pathname.length - 1] === '/') {
     resolved += '/'
@@ -608,23 +648,7 @@ exports.pathToFileURL = function pathToFileURL(pathname) {
     resolved += '\\'
   }
 
-  // Paths hardly ever contain any of these, so one pass to rule them out is
-  // cheaper than the six or seven replacements it stands in for.
-  if (reserved.test(resolved)) {
-    resolved = resolved
-      .replaceAll('%', '%25') // Must be first
-      .replaceAll('#', '%23')
-      .replaceAll('?', '%3f')
-      .replaceAll('\n', '%0a')
-      .replaceAll('\r', '%0d')
-      .replaceAll('\t', '%09')
-
-    if (!isWindows) {
-      resolved = resolved.replaceAll('\\', '%5c')
-    }
-  }
-
-  return new URL('file:' + resolved)
+  return new URL('file:' + encodeFilePath(resolved))
 }
 
 exports.format = function format(parts) {

package/node_modules/bare-url/lib/errors.js

@@ -30,4 +30,8 @@ module.exports = class URLError extends Error {
   static INVALID_FILE_URL_PATH(msg = 'Invalid file: URL path') {
     return new URLError(msg, URLError.INVALID_FILE_URL_PATH)
   }
+
+  static INVALID_ARG_VALUE(msg = 'Invalid argument value') {
+    return new URLError(msg, URLError.INVALID_ARG_VALUE)
+  }
 }

package/node_modules/bare-url/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bare-url",
-  "version": "2.5.4",
+  "version": "2.5.5",
   "description": "WHATWG URL implementation for JavaScript",
   "exports": {
     "./package": "./package.json",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appium-mac2-driver",
-  "version": "4.4.0",
+  "version": "4.5.0",
   "description": "XCTest-based Appium driver for macOS apps automation",
   "keywords": [
     "XCTest",
@@ -69,7 +69,8 @@
     ],
     "mainClass": "Mac2Driver",
     "scripts": {
-      "open-wda": "./scripts/open-wda.mjs"
+      "open-wda": "./scripts/open-wda.mjs",
+      "setup-accessibility": "./scripts/setup-accessibility.mjs"
     },
     "doctor": {
       "checks": [

package/scripts/setup-accessibility.mjs

@@ -0,0 +1,175 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+import {logger} from 'appium/support.js';
+import {exec} from 'teen_process';
+
+const RUNNER_NAME = 'WebDriverAgentRunner-Runner.app';
+const RUNNER_SCHEME = 'WebDriverAgentRunner';
+// Keep the build arguments in sync with the driver, so it reuses this build without re-signing it
+const DISABLE_STORE_ARG = 'COMPILER_INDEX_STORE_ENABLE=NO';
+const XCODEPROJ_NAME = 'WebDriverAgentMac.xcodeproj';
+const DERIVED_DATA_ROOT = path.join(os.homedir(), 'Library', 'Developer', 'Xcode', 'DerivedData');
+const SETTINGS_URL = 'x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility';
+const NO_OPEN_FLAG = '--no-open';
+const RUNNER_PATH_ENV = 'WDA_RUNNER_PATH';
+const KEEP_RUNNING_FLAG = '--keep-running';
+const RUNNER_EXECUTABLE_FRAGMENT = `/${RUNNER_NAME}/Contents/MacOS/`;
+
+const log = logger.getLogger('WDA');
+
+async function exists(p) {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Xcode stores the project path of each derived data folder in its info.plist
+ */
+async function readWorkspacePath(derivedDataDir) {
+  try {
+    const {stdout} = await exec('plutil', [
+      '-extract',
+      'WorkspacePath',
+      'raw',
+      '-o',
+      '-',
+      path.join(derivedDataDir, 'info.plist'),
+    ]);
+    return stdout.trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Finds the runner app built from the WebDriverAgent project of this driver.
+ * The newest one wins if there are many.
+ */
+async function findRunner(projectPath) {
+  let entries;
+  try {
+    entries = await fs.readdir(DERIVED_DATA_ROOT);
+  } catch {
+    return null;
+  }
+  const candidates = [];
+  for (const entry of entries.filter((name) => name.startsWith('WebDriverAgentMac-'))) {
+    const derivedDataDir = path.join(DERIVED_DATA_ROOT, entry);
+    const runnerPath = path.join(derivedDataDir, 'Build', 'Products', 'Debug', RUNNER_NAME);
+    if (!(await exists(runnerPath)) || (await readWorkspacePath(derivedDataDir)) !== projectPath) {
+      continue;
+    }
+    candidates.push({runnerPath, mtimeMs: (await fs.stat(runnerPath)).mtimeMs});
+  }
+  return candidates.sort((a, b) => b.mtimeMs - a.mtimeMs)[0]?.runnerPath ?? null;
+}
+
+/**
+ * Stops the runner and the xcodebuild process that hosts it. macOS evaluates the permission
+ * when a process starts, so a runner started before the grant stays untrusted.
+ * Appium itself keeps running, but an active session loses its runner.
+ */
+async function stopRunningRunners() {
+  const {stdout} = await exec('ps', ['-axo', 'pid=,command=']);
+  const pids = [];
+  for (const line of stdout.split('\n')) {
+    const match = line.trim().match(/^(\d+)\s+(.*)$/);
+    if (!match) {
+      continue;
+    }
+    const pid = Number(match[1]);
+    const command = match[2];
+    const isRunner = command.includes(RUNNER_EXECUTABLE_FRAGMENT);
+    const isHost =
+      /(^|\/)xcodebuild\s/.test(command) &&
+      command.includes('test-without-building') &&
+      command.includes(`-scheme ${RUNNER_SCHEME}`);
+    if ((isRunner || isHost) && pid !== process.pid && pid !== process.ppid) {
+      pids.push(pid);
+    }
+  }
+  for (const pid of pids) {
+    try {
+      process.kill(pid, 'SIGTERM');
+    } catch (e) {
+      log.warn(`Cannot stop the process ${pid}: ${e.message}`);
+    }
+  }
+  if (pids.length > 0) {
+    log.info(`Stopped the running WebDriverAgent processes: ${pids.join(', ')}`);
+  }
+}
+
+/**
+ * Builds the runner the same way the driver does
+ */
+async function buildRunner(projectPath) {
+  log.info(`Building ${RUNNER_NAME}. This may take a few minutes`);
+  try {
+    await exec(
+      'xcodebuild',
+      ['build-for-testing', '-project', projectPath, '-scheme', RUNNER_SCHEME, DISABLE_STORE_ARG],
+      {cwd: path.dirname(projectPath)},
+    );
+  } catch (e) {
+    const output = String(e.stdout ?? '')
+      .trim()
+      .split('\n')
+      .slice(-20)
+      .join('\n');
+    throw new Error(`Cannot build ${RUNNER_NAME}: ${e.stderr || e.message}\n${output}`, {cause: e});
+  }
+}
+
+async function setupAccessibility() {
+  const args = process.argv.slice(2);
+  const shouldOpen = !args.includes(NO_OPEN_FLAG);
+  const shouldStop = !args.includes(KEEP_RUNNING_FLAG);
+  const explicitPath = args.find((arg) => !arg.startsWith('--')) ?? process.env[RUNNER_PATH_ENV];
+
+  if (shouldStop) {
+    await stopRunningRunners();
+  }
+
+  const __dirname = path.dirname(fileURLToPath(import.meta.url));
+  const projectPath = path.resolve(__dirname, '..', 'WebDriverAgentMac', XCODEPROJ_NAME);
+  let runnerPath = explicitPath ? path.resolve(explicitPath) : await findRunner(projectPath);
+  if (!runnerPath && !explicitPath) {
+    await buildRunner(projectPath);
+    runnerPath = await findRunner(projectPath);
+  }
+  if (!runnerPath || !(await exists(runnerPath))) {
+    log.error(
+      `Cannot find ${RUNNER_NAME}${explicitPath ? ` at '${runnerPath}'` : ` built from '${projectPath}'`}. ` +
+        `If your Xcode derived data folder is not in '${DERIVED_DATA_ROOT}', ` +
+        `set the ${RUNNER_PATH_ENV} environment variable to the full path to ${RUNNER_NAME}.`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  log.info(`WebDriverAgent runner: '${runnerPath}'`);
+  log.info(
+    `Add the runner to System Settings > Privacy & Security > Accessibility and turn it on. ` +
+      `Then restart your Appium session. Do not rebuild the runner after granting the permission, ` +
+      `because the grant may be tied to the exact build.`,
+  );
+  if (!shouldOpen) {
+    return;
+  }
+  // Selects the runner in Finder, so it can be dragged into the Accessibility list
+  await exec('open', ['-R', runnerPath]);
+  await exec('open', [SETTINGS_URL]);
+}
+
+setupAccessibility().catch((e) => {
+  log.error(e.message);
+  process.exitCode = 1;
+});