@limrun/api 0.48.1 → 0.48.3

package/src/exec-client.ts

@@ -48,9 +48,31 @@ export type XcodeBuildExecRequest = {
     workspace?: string;
     project?: string;
     scheme?: string;
-    sdk?: 'iphonesimulator' | 'iphoneos' | 'watchsimulator' | 'watchos';
+    sdk?: 'iphonesimulator' | 'iphoneos' | 'watchsimulator' | 'watchos' | 'appletvos' | 'xros';
     configuration?: 'Debug' | 'Release';
     artifactName?: string;
+    /**
+     * xcodebuild action. 'build' (default) produces one .app; with a
+     * simulator attached it is installed there. 'build-for-testing' compiles
+     * the scheme's test targets and, with a simulator attached, runs them
+     * there, streaming per-case results as 'xctest' events; the exec exits
+     * non-zero when tests fail. Requires the iphonesimulator sdk.
+     */
+    action?: 'build' | 'build-for-testing';
+    /**
+     * Run only these tests, in xcodebuild's -only-testing format:
+     * Target[/Class[/method]]. Mutually exclusive with skipTesting; only
+     * valid with action 'build-for-testing'.
+     */
+    onlyTesting?: string[];
+    /** Skip these tests, in xcodebuild's -skip-testing format. */
+    skipTesting?: string[];
+    /**
+     * When false, 'build-for-testing' compiles the test targets but does not
+     * run them even when a simulator is attached. Servers without support
+     * ignore the field and still run the tests.
+     */
+    runTests?: boolean;
   };
   xcodegen?: {
     spec?: string;
@@ -85,6 +107,8 @@ export type XcodeBuildExecRequest = {
    */
   env?: string[];
   gitInit?: boolean;
+  /** How xcodebuild stdout is processed before streaming. Defaults to 'xcbeautify'. */
+  logProcessor?: 'xcbeautify' | 'none';
   signedUploadUrl?: string;
   /**
    * ID of the Limrun asset signedUploadUrl targets, when it was minted from
@@ -234,6 +258,12 @@ export type ExecOptions = {
   apiUrl: string;
   token: string;
   log?: (level: 'debug' | 'info' | 'warn' | 'error', msg: string) => void;
+  /**
+   * Called for each XCTest event as it streams from a build-for-testing run:
+   * one per finished test case, then the terminal summary. The same data
+   * lands accumulated on ExecResult.xctest.
+   */
+  onXctestEvent?: (event: XctestEvent) => void;
 };
 
 export type ExecResult = {
@@ -252,6 +282,13 @@ export type ExecResult = {
    * without a playstore request, or when the server predates the feature.
    */
   playstore?: PlaystoreEvent;
+  /**
+   * XCTest results streamed by a build-for-testing run: every finished case
+   * plus the terminal summary. Absent for plain builds and servers that
+   * predate the feature. A missing summary means the run died partway; the
+   * cases already streamed still stand.
+   */
+  xctest?: { cases: XctestCaseEvent[]; summary?: XctestSummaryEvent };
   /**
    * True when the client gave up waiting for the build's event stream. The
    * exit code is fabricated in that case; the remote build may still be
@@ -268,6 +305,32 @@ export type ExecResult = {
   incomplete?: { reason: 'timeout' | 'stream-lost' | 'stream-closed'; message: string };
 };
 
+export type XctestCaseEvent = {
+  type: 'case';
+  /**
+   * The test class as XCTest reports it: module-qualified for Swift
+   * ('AppTests.LoginTests'), bare for Objective-C.
+   */
+  testClass: string;
+  method: string;
+  passed: boolean;
+  durationMs: number;
+  /** First failure message of a failed case. */
+  failureMessage?: string;
+};
+
+export type XctestSummaryEvent = {
+  type: 'summary';
+  passed: number;
+  failed: number;
+  /** True only once every test in scope ran to completion. */
+  planFinished: boolean;
+  /** Crash or per-target failure detail when the run degraded. */
+  error?: string;
+};
+
+export type XctestEvent = XctestCaseEvent | XctestSummaryEvent;
+
 export type AppStoreEvent = {
   /** 'unknown' means an App Store upload event arrived but its payload was unreadable. */
   state: 'uploading' | 'processing' | 'accepted' | 'failed' | 'unknown';
@@ -389,6 +452,13 @@ export class ExecChildProcess implements PromiseLike<ExecResult> {
   private detached = false;
   private appStoreEvent: AppStoreEvent | null = null;
   private playstoreEvent: PlaystoreEvent | null = null;
+  private xctestCases: XctestCaseEvent[] = [];
+  private xctestSummary: XctestSummaryEvent | null = null;
+  // Highest server-assigned event id already dispatched. The server numbers
+  // every frame and replays the stream from the start on reconnect; skipping
+  // ids at or below this mark drops the replayed prefix for every event type
+  // at once, and stays correct if the server ever honors Last-Event-ID.
+  private lastSeenEventId = -1;
   private readonly options: ExecOptions;
   private readonly log: (level: 'debug' | 'info' | 'warn' | 'error', msg: string) => void;
 
@@ -555,7 +625,18 @@ export class ExecChildProcess implements PromiseLike<ExecResult> {
     let timeoutMs = 3600 * 1000;
     if (request.command === 'xcodebuild' && request.testflight) {
       timeoutMs += (Math.max(0, request.testflight.waitTimeoutSeconds ?? 0) + 900) * 1000;
-    } else if (request.command === 'run') {
+    }
+    if (request.command === 'xcodebuild' && request.xcodebuild?.action === 'build-for-testing') {
+      // The test run happens after the build: products sync plus the suite,
+      // which the server caps at an hour per target. Two hours cover the
+      // common unit-plus-UI shape; the client cannot know the target count, so
+      // schemes with more targets may need a liveness-based deadline instead.
+      // Kept even with runTests: false: servers without run suppression still
+      // execute the suite, and the cap is an upper bound so a pure build
+      // finishes early regardless.
+      timeoutMs += 2 * 3600 * 1000;
+    }
+    if (request.command === 'run') {
       timeoutMs = (Math.max(1, request.timeoutSeconds ?? 3600) + 60) * 1000;
     }
     let exitCode: number;
@@ -629,6 +710,14 @@ export class ExecChildProcess implements PromiseLike<ExecResult> {
       ...('additionalMetadata' in request ? request.additionalMetadata ?? {} : {}),
       ...(this.appStoreEvent ? { appstore: this.appStoreEvent } : {}),
       ...(this.playstoreEvent ? { playstore: this.playstoreEvent } : {}),
+      ...(this.xctestCases.length > 0 || this.xctestSummary ?
+        {
+          xctest: {
+            cases: this.xctestCases,
+            ...(this.xctestSummary ? { summary: this.xctestSummary } : {}),
+          },
+        }
+      : {}),
       ...(timedOut ? { timedOut } : {}),
       ...(incomplete ? { incomplete } : {}),
     };
@@ -768,6 +857,15 @@ export class ExecChildProcess implements PromiseLike<ExecResult> {
           this.streamDeadSince = 0;
           proofOfLifeThisCycle = true;
           lastStreamError = undefined;
+          const eventId = message.id !== undefined ? parseInt(message.id, 10) : NaN;
+          if (!Number.isNaN(eventId)) {
+            if (eventId <= this.lastSeenEventId) {
+              // A reconnect replays the stream from the start; this frame was
+              // already dispatched on an earlier connection.
+              return;
+            }
+            this.lastSeenEventId = eventId;
+          }
           const data = typeof message.data === 'string' ? message.data : String(message.data ?? '');
           const eventType = message.event;
           if (eventType === 'command') {
@@ -795,6 +893,33 @@ export class ExecChildProcess implements PromiseLike<ExecResult> {
               this.playstoreEvent = { state: 'unknown' };
               this.log('warn', `SSE playstore event has invalid data: ${data}`);
             }
+          } else if (eventType === 'xctest') {
+            let event: XctestEvent | undefined;
+            try {
+              const parsed = JSON.parse(data) as XctestEvent;
+              if (parsed?.type === 'case') {
+                this.xctestCases.push(parsed);
+                event = parsed;
+              } else if (parsed?.type === 'summary') {
+                this.xctestSummary = parsed;
+                event = parsed;
+              } else {
+                // The simulator owns the frame vocabulary and may grow it; the
+                // callback's contract is cases and summaries only.
+                this.log('debug', `SSE xctest event of unknown type ignored: ${data}`);
+              }
+            } catch {
+              this.log('warn', `SSE xctest event has invalid data: ${data}`);
+            }
+            if (event) {
+              try {
+                this.options.onXctestEvent?.(event);
+              } catch (err) {
+                // The consumer's callback, not the frame: the run must not be
+                // derailed and the log must not blame the payload.
+                this.log('warn', `onXctestEvent callback threw: ${String(err)}`);
+              }
+            }
           } else if (eventType === 'exitCode') {
             const exitCode = parseInt(data, 10);
             if (Number.isNaN(exitCode)) {

package/src/index.ts

@@ -41,6 +41,9 @@ export {
   type AppStoreUploadConfig,
   type PlaystoreEvent,
   type WebhookConfig,
+  type XctestCaseEvent,
+  type XctestEvent,
+  type XctestSummaryEvent,
 } from './exec-client';
 export {
   type XcodeCreateClientParams,

package/src/instance-client.ts

@@ -73,7 +73,7 @@ export type InstanceClient = {
   /**
    * Fetch Android UI hierarchy from UIAutomator.
    */
-  getElementTree: () => Promise<ElementTreeData>;
+  getElementTree: (options?: AndroidElementTreeOptions) => Promise<ElementTreeData>;
   /**
    * Find matching elements by Android-native selector.
    */
@@ -368,6 +368,10 @@ export type AndroidElementNode = {
   };
 };
 
+export type AndroidElementTreeOptions = {
+  waitForIdleTimeoutMs?: number;
+};
+
 /**
  * Configuration options for creating an Instance API client
  */
@@ -796,7 +800,7 @@ type ServerMessage =
 
 type CommandRequestMap = {
   screenshot: {};
-  getElementTree: {};
+  getElementTree: AndroidElementTreeOptions;
   findElement: { selector: AndroidSelector; limit?: number };
   tap: AndroidElementTarget;
   setText: { text: string } & AndroidElementTarget;
@@ -1309,8 +1313,12 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
       return sendRequest('screenshot', {});
     };
 
-    const getElementTree = async (): Promise<ElementTreeData> => {
-      const result = await sendRequest('getElementTree', {});
+    const getElementTree = async (options?: AndroidElementTreeOptions): Promise<ElementTreeData> => {
+      const result = await sendRequest(
+        'getElementTree',
+        options ?? {},
+        30_000 + (options?.waitForIdleTimeoutMs ?? 0),
+      );
       return {
         xml: typeof result.xml === 'string' ? result.xml : '',
         nodes: Array.isArray(result.nodes) ? result.nodes : [],

package/src/resources/xcode-instances-helpers.ts

@@ -20,6 +20,7 @@ import {
   type ExecChildProcess,
   type ExecRequest,
   type WebhookConfig,
+  type XctestEvent,
 } from '../exec-client';
 
 export type { AppStoreUploadConfig, WebhookConfig } from '../exec-client';
@@ -103,7 +104,7 @@ export type XcodeProjectConfig = {
   workspace?: string;
   project?: string;
   scheme?: string;
-  sdk?: 'iphonesimulator' | 'iphoneos' | 'watchsimulator' | 'watchos';
+  sdk?: 'iphonesimulator' | 'iphoneos' | 'watchsimulator' | 'watchos' | 'appletvos' | 'xros';
   /**
    * xcodebuild configuration. Omit to use limbuild's project-type default:
    * Debug for native Xcode builds and Release for React Native / Expo builds.
@@ -117,6 +118,33 @@ export type XcodeProjectConfig = {
    * discovery picks the wrong bundle.
    */
   artifactName?: string;
+  /**
+   * xcodebuild action. 'build' (default) produces one .app; with a simulator
+   * attached it is installed there. 'build-for-testing' compiles the scheme's
+   * test targets and, with a simulator attached, runs them there: per-case
+   * results stream through XcodeBuildOptions.onXctestEvent and accumulate on
+   * ExecResult.xctest, and the exec exits non-zero when tests fail. Requires
+   * the iphonesimulator sdk. Older limbuild servers reject the field.
+   */
+  action?: 'build' | 'build-for-testing';
+  /**
+   * Run only these tests, in xcodebuild's -only-testing format:
+   * Target[/Class[/method]]. A bare target runs that target unfiltered;
+   * targets named by no entry are skipped. Mutually exclusive with
+   * skipTesting; only valid with action 'build-for-testing'.
+   */
+  onlyTesting?: string[];
+  /**
+   * Skip these tests, in xcodebuild's -skip-testing format. A bare target
+   * skips that whole target.
+   */
+  skipTesting?: string[];
+  /**
+   * When false, 'build-for-testing' compiles the test targets but does not
+   * run them even when a simulator is attached. Servers without support
+   * ignore the field and still run the tests.
+   */
+  runTests?: boolean;
 };
 
 export type XcodeGenConfig = {
@@ -251,6 +279,8 @@ export type XcodeBuildOptions = {
    * dependency resolution, and xcodebuild.
    */
   gitInit?: boolean;
+  /** How xcodebuild stdout is processed before streaming. Defaults to 'xcbeautify'. */
+  logProcessor?: 'xcbeautify' | 'none';
   /**
    * HTTP callback fired once the build reaches a terminal state (SUCCEEDED,
    * FAILED, or CANCELLED). The payload carries the result (execId, status,
@@ -260,6 +290,12 @@ export type XcodeBuildOptions = {
    * build. Older limbuild servers silently ignore this option.
    */
   webhook?: WebhookConfig;
+  /**
+   * Called for each XCTest event streamed by a build-for-testing run: one per
+   * finished test case, then the terminal summary. The same data accumulates
+   * on ExecResult.xctest.
+   */
+  onXctestEvent?: (event: XctestEvent) => void;
 };
 
 export type SimulatorInstallState =
@@ -843,6 +879,25 @@ export class XcodeInstances extends GeneratedXcodeInstances {
         if (options?.reactNative?.devServerURL && settings?.configuration === 'Release') {
           throw new Error('reactNative.devServerURL is only supported for Debug builds');
         }
+        if (settings?.onlyTesting?.length && settings?.skipTesting?.length) {
+          throw new Error('onlyTesting and skipTesting are mutually exclusive; pass one');
+        }
+        if (
+          (settings?.onlyTesting?.length || settings?.skipTesting?.length) &&
+          settings?.action !== 'build-for-testing'
+        ) {
+          throw new Error("onlyTesting/skipTesting require action: 'build-for-testing'");
+        }
+        if (settings?.runTests === false && settings?.action !== 'build-for-testing') {
+          throw new Error("runTests: false requires action: 'build-for-testing'");
+        }
+        if (
+          settings?.action === 'build-for-testing' &&
+          settings.sdk !== undefined &&
+          settings.sdk !== 'iphonesimulator'
+        ) {
+          throw new Error("action: 'build-for-testing' requires the iphonesimulator sdk");
+        }
         if (options?.buildSettings) {
           validateBuildSettings(options.buildSettings);
         }
@@ -859,9 +914,20 @@ export class XcodeInstances extends GeneratedXcodeInstances {
           ...(options?.buildSettings && { buildSettings: options.buildSettings }),
           ...(options?.env?.length && { env: options.env }),
           ...(options?.gitInit !== undefined && { gitInit: options.gitInit }),
+          ...(options?.logProcessor && { logProcessor: options.logProcessor }),
           ...(options?.webhook && { webhook: options.webhook }),
         };
 
+        // One options object for both exec call sites, so a future per-exec
+        // option cannot be added to one branch and silently dropped from the
+        // other.
+        const execOptions = {
+          apiUrl,
+          token,
+          log,
+          ...(options?.onXctestEvent && { onXctestEvent: options.onXctestEvent }),
+        };
+
         if (options?.upload && 'assetName' in options.upload) {
           const requestPromise = mintAssetUploadUrls(
             client.assets,
@@ -875,14 +941,14 @@ export class XcodeInstances extends GeneratedXcodeInstances {
             request.additionalMetadata = { signedDownloadUrl: asset.signedDownloadUrl };
             return request;
           });
-          return exec(requestPromise, { apiUrl, token, log });
+          return exec(requestPromise, execOptions);
         }
 
         if (options?.upload && 'signedUploadUrl' in options.upload) {
           request.signedUploadUrl = options.upload.signedUploadUrl;
         }
 
-        return exec(request, { apiUrl, token, log });
+        return exec(request, execOptions);
       },
 
       run(commandLine: string, options?: XcodeRunOptions): ExecChildProcess {

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '0.48.1'; // x-release-please-version
+export const VERSION = '0.48.3'; // x-release-please-version

package/version.d.mts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.48.1";
+export declare const VERSION = "0.48.3";
 //# sourceMappingURL=version.d.mts.map

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.48.1";
+export declare const VERSION = "0.48.3";
 //# sourceMappingURL=version.d.ts.map

package/version.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = '0.48.1'; // x-release-please-version
+exports.VERSION = '0.48.3'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

@@ -1,2 +1,2 @@
-export const VERSION = '0.48.1'; // x-release-please-version
+export const VERSION = '0.48.3'; // x-release-please-version
 //# sourceMappingURL=version.mjs.map