@limrun/api 0.48.0 → 0.48.2

package/src/exec-client.ts

@@ -51,6 +51,28 @@ export type XcodeBuildExecRequest = {
     sdk?: 'iphonesimulator' | 'iphoneos' | 'watchsimulator' | 'watchos';
     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;
@@ -234,6 +256,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 +280,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 +303,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 +450,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 +623,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 +708,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 +855,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 +891,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/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';
@@ -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 = {
@@ -220,7 +248,8 @@ export type XcodeBuildOptions = {
   cloudSigning?: XcodeCloudSigningConfig;
   /**
    * Upload the signed device IPA to App Store Connect after the build.
-   * Requires manual or cloud signing and sdk=iphoneos. Check ExecResult.appstore on
+   * Requires manual or cloud signing; the upload itself supports only
+   * sdk=iphoneos builds. Check ExecResult.appstore on
    * completion; it is absent when the instance's limbuild predates the
    * feature (old servers silently ignore this option).
    */
@@ -259,6 +288,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 =
@@ -842,6 +877,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);
         }
@@ -861,6 +915,16 @@ export class XcodeInstances extends GeneratedXcodeInstances {
           ...(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,
@@ -874,14 +938,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.0'; // x-release-please-version
+export const VERSION = '0.48.2'; // x-release-please-version

package/version.d.mts

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

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.48.0";
+export declare const VERSION = "0.48.2";
 //# 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.0'; // x-release-please-version
+exports.VERSION = '0.48.2'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

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