feat: Add helper method to fetch build settings (#1139)

Author: mykola-mokhnach

lib/types.ts

@@ -115,6 +115,35 @@ 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';
+
+export type WdaSdk = 'iphonesimulator' | 'iphoneos' | 'appletvsimulator' | 'appletvos';
+
+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

lib/webdriveragent.ts

@@ -21,7 +21,12 @@ import {
   DEFAULT_TEST_BUNDLE_SUFFIX,
 } from './constants';
 import {strongbox} from '@appium/strongbox';
-import type {WebDriverAgentArgs, AppleDevice} from './types';
+import type {
+  WebDriverAgentArgs,
+  AppleDevice,
+  XcodeBuildSettings,
+  RetrieveBuildSettingsOptions,
+} from './types';
 import type {Simctl} from 'node-simctl';
 import type {Devicectl} from 'node-devicectl';
 
@@ -51,13 +56,11 @@ export class WebDriverAgent {
   jwproxy?: JWProxy;
   proxyReqRes?: any;
   private readonly log: AppiumLogger;
-  private readonly wdaBundlePath?: string;
   private readonly wdaLocalPort?: number;
   private readonly prebuildWDA?: boolean;
   private readonly wdaConnectionTimeout?: number;
   private readonly useXctestrunFile?: boolean;
   private readonly usePrebuiltWDA?: boolean;
-  private readonly derivedDataPath?: string;
   private readonly mjpegServerPort?: number;
   private readonly wdaLaunchTimeout: number;
   private readonly usePreinstalledWDA?: boolean;
@@ -80,7 +83,6 @@ export class WebDriverAgent {
     this.iosSdkVersion = args.iosSdkVersion;
     this.host = args.host;
     this.isRealDevice = !!args.realDevice;
-    this.wdaBundlePath = args.wdaBundlePath;
 
     this.setWDAPaths(args.bootstrapPath, args.agentPath);
 
@@ -102,7 +104,6 @@ export class WebDriverAgent {
 
     this.useXctestrunFile = args.useXctestrunFile;
     this.usePrebuiltWDA = args.usePrebuiltWDA;
-    this.derivedDataPath = args.derivedDataPath;
     this.mjpegServerPort = args.mjpegServerPort;
 
     this.updatedWDABundleId = args.updatedWDABundleId;
@@ -396,7 +397,21 @@ export class WebDriverAgent {
   }
 
   /**
-   * Retrieves the Xcode derived data path for WebDriverAgent.
+   * Retrieves Xcode build settings.
+   * @param options - Optional scheme, SDK, configuration, or destination
+   * @returns Build settings, or `undefined` if xcodebuild is skipped or settings cannot be determined
+   */
+  async retrieveBuildSettings(
+    options?: RetrieveBuildSettingsOptions,
+  ): Promise<XcodeBuildSettings | undefined> {
+    if (this.canSkipXcodebuild) {
+      return;
+    }
+    return await this.xcodebuild.retrieveBuildSettings(options);
+  }
+
+  /**
+   * @deprecated Use {@link retrieveBuildSettings} instead. Will be removed in a future release.
    * @returns The derived data path, or `undefined` if xcodebuild is skipped
    */
   async retrieveDerivedDataPath(): Promise<string | undefined> {

lib/xcodebuild.ts

@@ -14,7 +14,13 @@ import {
 } from './utils';
 import path from 'node:path';
 import {WDA_RUNNER_BUNDLE_ID} from './constants';
-import type {AppleDevice, XcodeBuildArgs} from './types';
+import type {
+  AppleDevice,
+  RetrieveBuildSettingsOptions,
+  XcodeBuildArgs,
+  XcodeBuildSettings,
+  XcodeShowBuildSettingsEntry,
+} from './types';
 import type {NoSessionProxy} from './no-session-proxy';
 
 const DEFAULT_SIGNING_ID = 'iPhone Developer';
@@ -42,7 +48,6 @@ const REAL_DEVICES_CONFIG_DOCS_LINK =
 const xcodeLog = logger.getLogger('Xcode');
 
 export class XcodeBuild {
-  xcodebuild?: SubProcess;
   readonly device: AppleDevice;
   readonly realDevice: boolean;
   readonly agentPath: string;
@@ -51,9 +56,9 @@ export class XcodeBuild {
   readonly platformName?: string;
   readonly iosSdkVersion?: string;
   readonly xcodeSigningId: string;
-  usePrebuiltWDA?: boolean;
-  derivedDataPath?: string;
-  agentUrl?: string;
+  private xcodebuild?: SubProcess;
+  private usePrebuiltWDA?: boolean;
+  private derivedDataPath?: string;
   private readonly log: AppiumLogger;
   private readonly showXcodeLog?: boolean;
   private readonly xcodeConfigFile?: string;
@@ -73,7 +78,10 @@ export class XcodeBuild {
   private readonly resultBundleVersion?: string;
   private _didBuildFail: boolean;
   private _didProcessExit: boolean;
-  private _derivedDataPathPromise?: Promise<string | undefined>;
+  private readonly _buildSettingsPromises = new Map<
+    string,
+    Promise<XcodeBuildSettings | undefined>
+  >();
   private noSessionProxy?: NoSessionProxy;
   private xctestrunFilePath?: string;
 
@@ -158,42 +166,42 @@ export class XcodeBuild {
   }
 
   /**
-   * Retrieves the Xcode derived data path for the build.
-   * Uses cached value if available, otherwise queries xcodebuild for BUILD_DIR.
+   * Retrieves Xcode build settings via `xcodebuild -showBuildSettings -json`.
+   * @param options - Optional scheme, SDK, configuration, or destination
+   * @returns Build settings for the `build` action, or `undefined` if they cannot be determined
+   */
+  async retrieveBuildSettings(
+    options?: RetrieveBuildSettingsOptions,
+  ): Promise<XcodeBuildSettings | undefined> {
+    const cacheKey = buildSettingsCacheKey(options);
+    let promise = this._buildSettingsPromises.get(cacheKey);
+    if (!promise) {
+      promise = this.fetchBuildSettings(options);
+      this._buildSettingsPromises.set(cacheKey, promise);
+    }
+    return await promise;
+  }
+
+  /**
    * @returns The derived data path, or `undefined` if it cannot be determined
    */
   async retrieveDerivedDataPath(): Promise<string | undefined> {
     if (this.derivedDataPath) {
       return this.derivedDataPath;
     }
 
-    // avoid race conditions
-    if (this._derivedDataPathPromise) {
-      return await this._derivedDataPathPromise;
+    const buildSettings = await this.retrieveBuildSettings();
+    const buildDir = buildSettings?.BUILD_DIR;
+    if (!buildDir) {
+      this.log.warn('Cannot parse WDA BUILD_DIR from build settings');
+      return;
     }
 
-    this._derivedDataPathPromise = (async () => {
-      let stdout: string;
-      try {
-        ({stdout} = await exec('xcodebuild', ['-project', this.agentPath, '-showBuildSettings']));
-      } catch (err: any) {
-        this.log.warn(`Cannot retrieve WDA build settings. Original error: ${err.message}`);
-        return;
-      }
-
-      const pattern = /^\s*BUILD_DIR\s+=\s+(\/.*)/m;
-      const match = pattern.exec(stdout);
-      if (!match) {
-        this.log.warn(`Cannot parse WDA build dir from ${truncateString(stdout, 300)}`);
-        return;
-      }
-      this.log.debug(`Parsed BUILD_DIR configuration value: '${match[1]}'`);
-      // Derived data root is two levels higher over the build dir
-      this.derivedDataPath = path.dirname(path.dirname(path.normalize(match[1])));
-      this.log.debug(`Got derived data root: '${this.derivedDataPath}'`);
-      return this.derivedDataPath;
-    })();
-    return await this._derivedDataPathPromise;
+    this.log.debug(`Parsed BUILD_DIR configuration value: '${buildDir}'`);
+    // Derived data root is two levels higher over the build dir
+    this.derivedDataPath = path.dirname(path.dirname(path.normalize(buildDir)));
+    this.log.debug(`Got derived data root: '${this.derivedDataPath}'`);
+    return this.derivedDataPath;
   }
 
   /**
@@ -297,6 +305,45 @@ export class XcodeBuild {
     await killProcess('xcodebuild', this.xcodebuild);
   }
 
+  private async fetchBuildSettings(
+    options?: RetrieveBuildSettingsOptions,
+  ): Promise<XcodeBuildSettings | undefined> {
+    const schemeLabel = options?.scheme ?? 'default';
+    let stdout: string;
+    try {
+      ({stdout} = await exec('xcodebuild', [
+        '-project',
+        this.agentPath,
+        '-showBuildSettings',
+        '-json',
+        ...buildSettingsArgsFromOptions(options),
+      ]));
+    } catch (err: any) {
+      this.log.warn(
+        `Cannot retrieve WDA build settings for scheme '${schemeLabel}'. Original error: ${err.message}`,
+      );
+      return;
+    }
+
+    let entries: XcodeShowBuildSettingsEntry[];
+    try {
+      entries = JSON.parse(stdout) as XcodeShowBuildSettingsEntry[];
+    } catch (err: any) {
+      this.log.warn(
+        `Cannot parse WDA build settings for scheme '${schemeLabel}' from ${truncateString(stdout, 300)}. ` +
+          `Original error: ${err.message}`,
+      );
+      return;
+    }
+
+    const entry = entries.find(({action}) => action === 'build') ?? entries[0];
+    if (!entry?.buildSettings) {
+      this.log.warn(`Cannot find build settings for scheme '${schemeLabel}'`);
+      return;
+    }
+    return entry.buildSettings;
+  }
+
   private getCommand(buildOnly: boolean = false): {cmd: string; args: string[]} {
     const cmd = 'xcodebuild';
     const args: string[] = [];
@@ -465,9 +512,6 @@ export class XcodeBuild {
         (noSessionProxy as any).timeout = 1000;
         try {
           currentStatus = (await noSessionProxy.command('/status', 'GET')) as StringRecord;
-          if (currentStatus?.ios?.ip) {
-            this.agentUrl = currentStatus.ios.ip as string;
-          }
           this.log.debug(`WebDriverAgent information:`);
           this.log.debug(JSON.stringify(currentStatus, null, 2));
         } catch (err: any) {
@@ -498,3 +542,27 @@ export class XcodeBuild {
     return currentStatus;
   }
 }
+
+function buildSettingsArgsFromOptions(options?: RetrieveBuildSettingsOptions): string[] {
+  const args: string[] = [];
+  if (!options) {
+    return args;
+  }
+  if (options.scheme) {
+    args.push('-scheme', options.scheme);
+  }
+  if (options.sdk) {
+    args.push('-sdk', options.sdk);
+  }
+  if (options.configuration) {
+    args.push('-configuration', options.configuration);
+  }
+  if (options.destination) {
+    args.push('-destination', options.destination);
+  }
+  return args;
+}
+
+function buildSettingsCacheKey(options?: RetrieveBuildSettingsOptions): string {
+  return buildSettingsArgsFromOptions(options).join('\0');
+}

test/unit/webdriveragent-specs.ts

@@ -51,13 +51,13 @@ describe('WebDriverAgent', function () {
       expect(agent.bootstrapPath).to.eql(customBootstrapPath);
       expect(agent.agentPath).to.eql(customAgentPath);
     });
-    it('should have custom derivedDataPath if specified', function () {
+    it('should have custom derivedDataPath if specified', async function () {
       const agent = new WebDriverAgent({
         ...fakeConstructorArgs,
         derivedDataPath: customDerivedDataPath,
       });
       if (agent.xcodebuild) {
-        expect(agent.xcodebuild.derivedDataPath).to.eql(customDerivedDataPath);
+        expect(await agent.retrieveDerivedDataPath()).to.eql(customDerivedDataPath);
       }
     });
   });