@devicelab/maestro-runner-darwin-arm64 1.1.25 → 1.1.28

package/drivers/ios/WebDriverAgent/WebDriverAgentTests/UnitTests_tvOS/FBTVNavigationTrackerTests.m

@@ -7,8 +7,10 @@
  */
 
 #import <XCTest/XCTest.h>
+#import <WebDriverAgentLib/FBXCElementSnapshot.h>
 
 #import "XCUIElementDouble.h"
+#import "FBXCElementSnapshotDouble.h"
 #import "FBTVNavigationTracker.h"
 #import "FBTVNavigationTracker-Private.h"
 
@@ -83,4 +85,50 @@
   XCTAssertEqual(FBTVDirectionNone, direction);
 }
 
+#pragma mark - directionTowardsTargetFromFocusedElementSnapshot:
+
+- (FBTVNavigationTracker *)trackerWithTargetFrame:(CGRect)targetFrame
+{
+  XCUIElementDouble *targetElement = XCUIElementDouble.new;
+  targetElement.wdFrame = targetFrame;
+  return [FBTVNavigationTracker trackerWithTargetElement:(XCUIElement *)targetElement];
+}
+
+- (void)testDirectionTowardsTargetFromFocusedElementSnapshotShouldPointRight
+{
+  // Target sits to the right of the currently focused element.
+  FBTVNavigationTracker *tracker = [self trackerWithTargetFrame:CGRectMake(100, 0, 0, 0)];
+  FBXCElementSnapshotDouble *focusedSnapshot = [FBXCElementSnapshotDouble snapshotWithElementId:1 frame:CGRectMake(0, 0, 0, 0) hasFocus:YES];
+
+  FBTVDirection direction = [tracker directionTowardsTargetFromFocusedElementSnapshot:(id<FBXCElementSnapshot>)focusedSnapshot];
+
+  XCTAssertEqual(FBTVDirectionRight, direction);
+}
+
+- (void)testDirectionTowardsTargetFromFocusedElementSnapshotShouldPointUp
+{
+  // Target sits above the currently focused element.
+  FBTVNavigationTracker *tracker = [self trackerWithTargetFrame:CGRectMake(0, -100, 0, 0)];
+  FBXCElementSnapshotDouble *focusedSnapshot = [FBXCElementSnapshotDouble snapshotWithElementId:1 frame:CGRectMake(0, 0, 0, 0) hasFocus:YES];
+
+  FBTVDirection direction = [tracker directionTowardsTargetFromFocusedElementSnapshot:(id<FBXCElementSnapshot>)focusedSnapshot];
+
+  XCTAssertEqual(FBTVDirectionUp, direction);
+}
+
+- (void)testDirectionTowardsTargetFromFocusedElementSnapshotShouldNotSuggestTheSameDirectionTwiceInARow
+{
+  // Same (unmoved) focused snapshot polled twice: the horizontal move gets
+  // suggested once, then withheld on the next call, per the "don't repeat a
+  // direction" bookkeeping in -directionWithItem:delta:positiveDirection:negativeDirection:.
+  FBTVNavigationTracker *tracker = [self trackerWithTargetFrame:CGRectMake(100, 0, 0, 0)];
+  FBXCElementSnapshotDouble *focusedSnapshot = [FBXCElementSnapshotDouble snapshotWithElementId:1 frame:CGRectMake(0, 0, 0, 0) hasFocus:YES];
+
+  FBTVDirection firstDirection = [tracker directionTowardsTargetFromFocusedElementSnapshot:(id<FBXCElementSnapshot>)focusedSnapshot];
+  XCTAssertEqual(FBTVDirectionRight, firstDirection);
+
+  FBTVDirection secondDirection = [tracker directionTowardsTargetFromFocusedElementSnapshot:(id<FBXCElementSnapshot>)focusedSnapshot];
+  XCTAssertEqual(FBTVDirectionNone, secondDirection);
+}
+
 @end

package/drivers/ios/WebDriverAgent/lib/check-dependencies.ts

@@ -1,34 +1,55 @@
-import { fs } from '@appium/support';
-import { exec } from 'teen_process';
 import path from 'node:path';
-import {
-  WDA_SCHEME, SDK_SIMULATOR, WDA_RUNNER_APP
-} from './constants';
-import { BOOTSTRAP_PATH } from './utils';
-import type { XcodeBuild } from './xcodebuild';
 
-async function buildWDASim (): Promise<void> {
-  const args = [
-    '-project', path.join(BOOTSTRAP_PATH, 'WebDriverAgent.xcodeproj'),
-    '-scheme', WDA_SCHEME,
-    '-sdk', SDK_SIMULATOR,
-    'CODE_SIGN_IDENTITY=""',
-    'CODE_SIGNING_REQUIRED="NO"',
-    'GCC_TREAT_WARNINGS_AS_ERRORS=0',
-  ];
-  await exec('xcodebuild', args);
-}
+import {fs} from '@appium/support';
+import {exec} from 'teen_process';
+
+import {getPlatformSchemeSuffix, isTvOS, isWatchOS, BOOTSTRAP_PATH} from './utils/index.js';
+import type {XcodeBuild} from './xcodebuild.js';
+
+/**
+ * Ensure simulator WDA is built and return the resulting app bundle path.
+ */
+export async function bundleWDASim(xcodebuild: XcodeBuild): Promise<string> {
+  const platformName = xcodebuild.platformName || '';
+  const scheme = `WebDriverAgentRunner${getPlatformSchemeSuffix(platformName)}`;
+  const sdk = getSimulatorSdk(platformName);
 
-export async function bundleWDASim (xcodebuild: XcodeBuild): Promise<string> {
   const derivedDataPath = await xcodebuild.retrieveDerivedDataPath();
   if (!derivedDataPath) {
     throw new Error('Cannot retrieve the path to the Xcode derived data folder');
   }
-  const wdaBundlePath = path.join(derivedDataPath, 'Build', 'Products', 'Debug-iphonesimulator', WDA_RUNNER_APP);
+  const wdaBundlePath = path.join(derivedDataPath, 'Build', 'Products', `Debug-${sdk}`, `${scheme}-Runner.app`);
   if (await fs.exists(wdaBundlePath)) {
     return wdaBundlePath;
   }
-  await buildWDASim();
+  await buildWDASim(scheme, sdk);
   return wdaBundlePath;
 }
 
+/**
+ * @returns The simulator SDK name for the given platform.
+ */
+function getSimulatorSdk(platformName: string): 'iphonesimulator' | 'appletvsimulator' | 'watchsimulator' {
+  if (isTvOS(platformName)) {
+    return 'appletvsimulator';
+  }
+  if (isWatchOS(platformName)) {
+    return 'watchsimulator';
+  }
+  return 'iphonesimulator';
+}
+
+async function buildWDASim(scheme: string, sdk: string): Promise<void> {
+  const args = [
+    '-project',
+    path.join(BOOTSTRAP_PATH, 'WebDriverAgent.xcodeproj'),
+    '-scheme',
+    scheme,
+    '-sdk',
+    sdk,
+    'CODE_SIGN_IDENTITY=""',
+    'CODE_SIGNING_REQUIRED="NO"',
+    'GCC_TREAT_WARNINGS_AS_ERRORS=0',
+  ];
+  await exec('xcodebuild', args);
+}

package/drivers/ios/WebDriverAgent/lib/constants.ts

@@ -4,15 +4,25 @@ export const DEFAULT_TEST_BUNDLE_SUFFIX = '.xctrunner';
 export const WDA_RUNNER_BUNDLE_ID = 'com.facebook.WebDriverAgentRunner';
 export const WDA_RUNNER_BUNDLE_ID_FOR_XCTEST = `${WDA_RUNNER_BUNDLE_ID}${DEFAULT_TEST_BUNDLE_SUFFIX}`;
 export const WDA_RUNNER_APP = 'WebDriverAgentRunner-Runner.app';
-export const WDA_SCHEME = 'WebDriverAgentRunner';
 export const PROJECT_FILE = 'project.pbxproj';
 export const WDA_BASE_URL = 'http://127.0.0.1';
 
 export const PLATFORM_NAME_TVOS = 'tvOS';
+export const PLATFORM_NAME_WATCHOS = 'watchOS';
 export const PLATFORM_NAME_IOS = 'iOS';
 
-export const SDK_SIMULATOR = 'iphonesimulator';
 export const SDK_DEVICE = 'iphoneos';
 
+/**
+ * @deprecated The WDA upgrade timestamp path is no longer used.
+ */
 export const WDA_UPGRADE_TIMESTAMP_PATH = path.join('.appium', 'webdriveragent', 'upgrade.time');
 
+/**
+ * Harmless unused build setting override appended to every xcodebuild invocation
+ * this package starts. It has no effect on the build itself, but shows up verbatim
+ * in the process' command line, letting us tell our own xcodebuild processes apart
+ * from unrelated ones (e.g. other WDA-based test runners) that happen to target the
+ * same device udid.
+ */
+export const XCODEBUILD_PROCESS_MARKER = 'APPIUM_XCODEBUILD_WDA_MARKER=1';

package/drivers/ios/WebDriverAgent/lib/index.ts

@@ -0,0 +1,7 @@
+export {bundleWDASim} from './check-dependencies.js';
+export {NoSessionProxy} from './no-session-proxy.js';
+export {WebDriverAgent} from './webdriveragent.js';
+export {WDA_BASE_URL, WDA_RUNNER_APP, WDA_RUNNER_BUNDLE_ID, PROJECT_FILE} from './constants.js';
+export {resetTestProcesses, BOOTSTRAP_PATH} from './utils/index.js';
+
+export * from './types.js';

package/drivers/ios/WebDriverAgent/lib/logger.ts

@@ -1,3 +1,3 @@
-import { logger } from '@appium/support';
+import {logger} from '@appium/support';
 
 export const log = logger.getLogger('WebDriverAgent');

package/drivers/ios/WebDriverAgent/lib/no-session-proxy.ts

@@ -1,25 +1,19 @@
-import { JWProxy } from '@appium/base-driver';
-import type { ProxyOptions } from '@appium/types';
+import {WebDriverProxy} from '@appium/base-driver';
+import type {ProxyOptions} from '@appium/types';
 
-
-export class NoSessionProxy extends JWProxy {
-  constructor (opts: ProxyOptions = {}) {
+export class NoSessionProxy extends WebDriverProxy {
+  constructor(opts: ProxyOptions = {}) {
     super(opts);
   }
 
-  override getUrlForProxy (url: string): string {
+  override getUrlForProxy(url: string): string {
     if (url === '') {
       url = '/';
     }
     const proxyBase = `${this.scheme}://${this.server}:${this.port}${this.base}`;
-    let remainingUrl = '';
-    if ((new RegExp('^/')).test(url)) {
-      remainingUrl = url;
-    } else {
-      throw new Error(`Did not know what to do with url '${url}'`);
+    if (new RegExp('^/').test(url)) {
+      return proxyBase + url.replace(/\/$/, ''); // can't have trailing slashes
     }
-    remainingUrl = remainingUrl.replace(/\/$/, ''); // can't have trailing slashes
-    return proxyBase + remainingUrl;
+    throw new Error(`Did not know what to do with url '${url}'`);
   }
 }
-

package/drivers/ios/WebDriverAgent/lib/types.ts

@@ -1,3 +1,5 @@
+import {type HTTPHeaders} from '@appium/types';
+
 // WebDriverAgentLib/Utilities/FBSettings.h
 export interface WDASettings {
   elementResponseAttribute?: string;
@@ -11,17 +13,27 @@ export interface WDASettings {
   keyboardAutocorrection?: boolean;
   keyboardPrediction?: boolean;
   customSnapshotTimeout?: number;
+  accessibilityDeadline?: number;
+  enforceCustomSnapshots?: boolean;
+  limitXPathContextScope?: boolean;
+  includeHittableInPageSource?: boolean;
+  includeNativeFrameInPageSource?: boolean;
+  includeNativeAccessibilityElementInPageSource?: boolean;
+  includeMinMaxValueInPageSource?: boolean;
+  includeCustomActionsInPageSource?: boolean;
+  respectSystemAlerts?: boolean;
+  autoClickAlertSelector?: string;
   snapshotMaxDepth?: number;
+  snapshotMaxChildren?: number;
   useFirstMatch?: boolean;
   boundElementsByIndex?: boolean;
   reduceMotion?: boolean;
   defaultActiveApplication?: string;
   activeAppDetectionPoint?: string;
-  includeNonModalElements?: boolean;
   defaultAlertAction?: 'accept' | 'dismiss';
   acceptAlertButtonSelector?: string;
   dismissAlertButtonSelector?: string;
-  screenshotOrientation?: 'auto' | 'portrait' | 'portraitUpsideDown' | 'landscapeRight' | 'landscapeLeft'
+  screenshotOrientation?: 'auto' | 'portrait' | 'portraitUpsideDown' | 'landscapeRight' | 'landscapeLeft';
   waitForIdleTimeout?: number;
   animationCoolOffTimeout?: number;
   maxTypingFrequency?: number;
@@ -36,7 +48,6 @@ export interface WDACapabilities {
   environment?: Record<string, string>;
   eventloopIdleDelaySec?: number;
   shouldWaitForQuiescence?: boolean;
-  shouldUseTestManagerForVisibilityDetection?: boolean;
   maxTypingFrequency?: number;
   shouldUseSingletonTestManager?: boolean;
   waitForIdleTimeout?: number;
@@ -49,6 +60,7 @@ export interface WDACapabilities {
   forceSimulatorSoftwareKeyboardPresence?: boolean;
   defaultAlertAction?: 'accept' | 'dismiss';
   appLaunchStateTimeoutSec?: number;
+  accessibilityDeadline?: number;
 }
 
 export interface WebDriverAgentArgs {
@@ -72,6 +84,7 @@ export interface WebDriverAgentArgs {
   usePrebuiltWDA?: boolean;
   derivedDataPath?: string;
   mjpegServerPort?: number;
+  maxHttpRequestBodySize?: number;
   updatedWDABundleId?: string;
   wdaLaunchTimeout?: number;
   usePreinstalledWDA?: boolean;
@@ -88,15 +101,69 @@ export interface WebDriverAgentArgs {
   resultBundleVersion?: string;
   reqBasePath?: string;
   launchTimeout?: number;
+  extraRequestHeaders?: HTTPHeaders;
+  hostOps?: WdaHostOps;
 }
 
 export interface AppleDevice {
   udid: string;
-  simctl?: any;
-  devicectl?: any;
-  /** @deprecated We'll stop supporting idb */
-  idb?: any;
-  [key: string]: any;
+}
+
+export type WdaStartupStrategyName =
+  | 'existing-url'
+  | 'simulator'
+  | 'real-device-xcodebuild'
+  | 'real-device-preinstalled';
+
+export type WdaLaunchEnvironment = Record<string, string | number>;
+
+export interface WdaLaunchOptions {
+  udid: string;
+  bundleId: string;
+  env: WdaLaunchEnvironment;
+  wdaLocalPort?: number;
+  wdaRemotePort: number;
+  platformName?: string;
+  platformVersion?: string;
+  timeoutMs: number;
+}
+
+export interface WdaTerminateOptions {
+  udid: string;
+  bundleId: string;
+}
+
+export interface WdaResetTestProcessesOptions {
+  udid: string;
+  isSimulator: boolean;
+}
+
+export interface WdaCleanupObsoleteProcessesOptions {
+  udid: string;
+  port: string;
+  commandLineIncludes: string;
+}
+
+export interface SimulatorHostOps {
+  launchPreinstalled(opts: WdaLaunchOptions): Promise<void>;
+  terminate(opts: WdaTerminateOptions): Promise<void>;
+  resetTestProcesses?(opts: WdaResetTestProcessesOptions): Promise<void>;
+}
+
+export interface RealDevicePreinstalledHostOps {
+  launchPreinstalled(opts: WdaLaunchOptions): Promise<void>;
+  terminate(opts: WdaTerminateOptions): Promise<void>;
+}
+
+export interface RealDeviceXcodebuildHostOps {
+  resetTestProcesses?(opts: WdaResetTestProcessesOptions): Promise<void>;
+  cleanupObsoleteProcesses?(opts: WdaCleanupObsoleteProcessesOptions): Promise<void>;
+}
+
+export interface WdaHostOps {
+  simulator?: SimulatorHostOps;
+  realDevicePreinstalled?: RealDevicePreinstalledHostOps;
+  realDeviceXcodebuild?: RealDeviceXcodebuildHostOps;
 }
 
 /**
@@ -109,6 +176,37 @@ export interface DeviceInfo {
   platformName: string;
 }
 
+/** Xcode build setting key/value pairs from `xcodebuild -showBuildSettings -json`. */
+export type XcodeBuildSettings = Record<string, string>;
+
+/** A single target entry returned by `xcodebuild -showBuildSettings -json`. */
+export interface XcodeShowBuildSettingsEntry {
+  action: string;
+  buildSettings: XcodeBuildSettings;
+  target: string;
+}
+
+export type WdaScheme =
+  | 'WebDriverAgentRunner'
+  | 'WebDriverAgentLib'
+  | 'WebDriverAgentRunner_tvOS'
+  | 'WebDriverAgentLib_tvOS'
+  | 'WebDriverAgentRunner_watchOS'
+  | 'WebDriverAgentLib_watchOS';
+
+export type WdaSdk = 'iphonesimulator' | 'iphoneos' | 'appletvsimulator' | 'appletvos' | 'watchsimulator';
+
+export type WdaBuildConfiguration = 'Debug' | 'Release';
+
+/** Options passed to {@link XcodeBuild.retrieveBuildSettings}. */
+export interface RetrieveBuildSettingsOptions {
+  scheme?: WdaScheme;
+  sdk?: WdaSdk;
+  configuration?: WdaBuildConfiguration;
+  /** `-destination` value (e.g. `id=<udid>` or a full destination specifier). */
+  destination?: string;
+}
+
 export interface XcodeBuildArgs {
   realDevice: boolean; // Required
   agentPath: string; // Required
@@ -132,8 +230,10 @@ export interface XcodeBuildArgs {
   updatedWDABundleId?: string;
   derivedDataPath?: string;
   mjpegServerPort?: number;
+  maxHttpRequestBodySize?: number;
   prebuildDelay?: number;
   allowProvisioningDeviceRegistration?: boolean;
   resultBundlePath?: string;
   resultBundleVersion?: string;
+  extraRequestHeaders?: HTTPHeaders;
 }

package/drivers/ios/WebDriverAgent/lib/utils/index.ts

@@ -0,0 +1,15 @@
+import {getWDAUpgradeTimestamp as getWDAUpgradeTimestampImpl} from './module.js';
+
+export {BOOTSTRAP_PATH} from './module.js';
+export {getPlatformSchemeSuffix, isTvOS, isWatchOS} from './platform.js';
+export {getPIDsListeningOnPort, killAppUsingPattern, resetTestProcesses} from './processes.js';
+export {setRealDeviceSecurity} from './security.js';
+export {getAdditionalRunContent, getXctestrunFileName, getXctestrunFilePath, setXctestrunFile} from './xctestrun.js';
+export type {XctestrunFileArgs} from './xctestrun.js';
+
+/**
+ * Retrieves WDA upgrade timestamp. The manifest only gets modified on package upgrade.
+ */
+export async function getWDAUpgradeTimestamp(): Promise<number | null> {
+  return await getWDAUpgradeTimestampImpl();
+}

package/drivers/ios/WebDriverAgent/lib/utils/module.ts

@@ -0,0 +1,24 @@
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+import {fs, node as supportNode} from '@appium/support';
+
+const moduleRoot = supportNode.getModuleRootSync('appium-webdriveragent', fileURLToPath(import.meta.url));
+
+if (!moduleRoot) {
+  throw new Error('Cannot find the root folder of the appium-webdriveragent Node.js module');
+}
+
+export const BOOTSTRAP_PATH = moduleRoot;
+
+/**
+ * Retrieves WDA upgrade timestamp. The manifest only gets modified on package upgrade.
+ */
+export async function getWDAUpgradeTimestamp(): Promise<number | null> {
+  const packageManifest = path.resolve(BOOTSTRAP_PATH, 'package.json');
+  if (!(await fs.exists(packageManifest))) {
+    return null;
+  }
+  const {mtime} = await fs.stat(packageManifest);
+  return mtime.getTime();
+}

package/drivers/ios/WebDriverAgent/lib/utils/platform.ts

@@ -0,0 +1,34 @@
+import {PLATFORM_NAME_TVOS, PLATFORM_NAME_WATCHOS} from '../constants.js';
+
+/**
+ * Return true if the platformName is tvOS
+ * @param platformName The name of the platform
+ * @returns Return true if the platformName is tvOS
+ */
+export function isTvOS(platformName: string): boolean {
+  return platformName?.toLowerCase() === PLATFORM_NAME_TVOS.toLowerCase();
+}
+
+/**
+ * Return true if the platformName is watchOS
+ * @param platformName The name of the platform
+ * @returns Return true if the platformName is watchOS
+ */
+export function isWatchOS(platformName: string): boolean {
+  return platformName?.toLowerCase() === PLATFORM_NAME_WATCHOS.toLowerCase();
+}
+
+/**
+ * @param platformName The name of the platform
+ * @returns The `WebDriverAgentRunner`/`WebDriverAgentLib` scheme name suffix for the given platform:
+ * '_tvOS', '_watchOS', or '' for iOS.
+ */
+export function getPlatformSchemeSuffix(platformName: string): string {
+  if (isTvOS(platformName)) {
+    return '_tvOS';
+  }
+  if (isWatchOS(platformName)) {
+    return '_watchOS';
+  }
+  return '';
+}

package/drivers/ios/WebDriverAgent/lib/utils/processes.ts

@@ -0,0 +1,166 @@
+import {waitForCondition} from 'asyncbox';
+import {exec} from 'teen_process';
+
+import {XCODEBUILD_PROCESS_MARKER} from '../constants.js';
+import {log} from '../logger.js';
+
+/**
+ * Find and terminate all processes matching the given pgrep pattern.
+ *
+ * @param pgrepPattern - Pattern used to find candidate processes.
+ * @param cmdlineIncludes - If given, a candidate is only killed if its full
+ * command line also contains this substring. Used to narrow a broad pgrep
+ * match (e.g. by device udid) down to processes this package actually started.
+ */
+export async function killAppUsingPattern(pgrepPattern: string, cmdlineIncludes?: string): Promise<void> {
+  const signals = [2, 15, 9];
+  for (const signal of signals) {
+    const matchedPids = await getPIDsUsingPattern(pgrepPattern, cmdlineIncludes);
+    if (matchedPids.length === 0) {
+      return;
+    }
+    const args = [`-${signal}`, ...matchedPids];
+    try {
+      await exec('kill', args);
+    } catch (err: any) {
+      log.debug(`kill ${args.join(' ')} -> ${err.message}`);
+    }
+    if (signal === signals[signals.length - 1]) {
+      // there is no need to wait after SIGKILL
+      return;
+    }
+    try {
+      await waitForCondition(
+        async () => {
+          const pidCheckPromises = matchedPids.map(async (pid) => {
+            try {
+              await exec('kill', ['-0', pid]);
+              // the process is still alive
+              return false;
+            } catch {
+              // the process is dead
+              return true;
+            }
+          });
+          return (await Promise.all(pidCheckPromises)).every((x) => x === true);
+        },
+        {
+          waitMs: 1000,
+          intervalMs: 100,
+        },
+      );
+      return;
+    } catch {
+      // try the next signal
+    }
+  }
+}
+
+/**
+ * Kills running XCTest processes for the particular device.
+ *
+ * The `xcodebuild` pattern is additionally scoped to processes this package started
+ * (see {@link XCODEBUILD_PROCESS_MARKER}), so other XCTest-based tools targeting the
+ * same udid (e.g. a separately managed WebDriverAgent instance) are left alone.
+ * The XCTRunner/xctest patterns below cannot be scoped the same way, since those
+ * processes do not inherit xcodebuild's command line.
+ */
+export async function resetTestProcesses(udid: string, isSimulator: boolean): Promise<void> {
+  const processPatterns = [`xcodebuild.*${udid}`];
+  if (isSimulator) {
+    processPatterns.push(`${udid}.*XCTRunner`);
+    // Some XCTest launches might not include xcodebuild in their command line
+    processPatterns.push(`xctest.*${udid}`);
+  }
+  log.debug(`Killing running processes '${processPatterns.join(', ')}' for the device ${udid}...`);
+  await Promise.all(
+    processPatterns.map((pattern) =>
+      killAppUsingPattern(pattern, pattern.startsWith('xcodebuild') ? XCODEBUILD_PROCESS_MARKER : undefined),
+    ),
+  );
+}
+
+/**
+ * Filters a list of PIDs down to those whose full command line satisfies the
+ * given lambda. PIDs that have already exited are silently dropped.
+ */
+async function filterPIDsByCommandLine(
+  pids: string[],
+  filteringFunc: (cmdline: string) => boolean | Promise<boolean>,
+): Promise<string[]> {
+  const filtered = await Promise.all(
+    pids.map(async (pid) => {
+      let stdout: string;
+      try {
+        ({stdout} = await exec('ps', ['-p', pid, '-o', 'command']));
+      } catch (e: any) {
+        if (e.code === 1) {
+          // The process does not exist anymore, there's nothing to filter
+          return null;
+        }
+        throw e;
+      }
+      return (await filteringFunc(stdout)) ? pid : null;
+    }),
+  );
+  return filtered.filter((pid): pid is string => Boolean(pid));
+}
+
+/**
+ * Get the IDs of processes listening on the particular system port.
+ * It is also possible to apply additional filtering based on the
+ * process command line.
+ *
+ * @param port - The port number.
+ * @param filteringFunc - Optional lambda function, which
+ *                                    receives command line string of the particular process
+ *                                    listening on given port, and is expected to return
+ *                                    either true or false to include/exclude the corresponding PID
+ *                                    from the resulting array.
+ * @returns - the list of matched process ids.
+ */
+export async function getPIDsListeningOnPort(
+  port: string | number,
+  filteringFunc: ((cmdline: string) => boolean | Promise<boolean>) | null = null,
+): Promise<string[]> {
+  const result: string[] = [];
+  try {
+    // This only works since Mac OS X El Capitan
+    const {stdout} = await exec('lsof', ['-ti', `tcp:${port}`]);
+    result.push(...stdout.trim().split(/\n+/));
+  } catch (e: any) {
+    if (e.code !== 1) {
+      // code 1 means no processes. Other errors need reporting
+      log.debug(`Error getting processes listening on port '${port}': ${e.stderr || e.message}`);
+    }
+    return result;
+  }
+
+  if (typeof filteringFunc !== 'function') {
+    return result;
+  }
+  return await filterPIDsByCommandLine(result, filteringFunc);
+}
+
+async function getPIDsUsingPattern(pattern: string, cmdlineIncludes?: string): Promise<string[]> {
+  const args = [
+    '-if', // case insensitive, full cmdline match
+    pattern,
+  ];
+  let pids: string[];
+  try {
+    const {stdout} = await exec('pgrep', args);
+    pids = stdout
+      .split(/\s+/)
+      .map((x) => parseInt(x, 10))
+      .filter(Number.isInteger)
+      .map((x) => `${x}`);
+  } catch (err: any) {
+    log.debug(`'pgrep ${args.join(' ')}' didn't detect any matching processes. Return code: ${err.code}`);
+    return [];
+  }
+  if (!cmdlineIncludes || pids.length === 0) {
+    return pids;
+  }
+  return await filterPIDsByCommandLine(pids, (cmdline) => cmdline.includes(cmdlineIncludes));
+}

package/drivers/ios/WebDriverAgent/lib/utils/security.ts

@@ -0,0 +1,13 @@
+import {exec} from 'teen_process';
+
+import {log} from '../logger.js';
+
+/**
+ * Configure keychain access required for real-device code signing.
+ */
+export async function setRealDeviceSecurity(keychainPath: string, keychainPassword: string): Promise<void> {
+  log.debug('Setting security for iOS device');
+  await exec('security', ['-v', 'list-keychains', '-s', keychainPath]);
+  await exec('security', ['-v', 'unlock-keychain', '-p', keychainPassword, keychainPath]);
+  await exec('security', ['set-keychain-settings', '-t', '3600', '-l', keychainPath]);
+}