feat(ios): support external xctest runner artifact

src/client-normalizers.ts

@@ -274,6 +274,9 @@ export function buildFlags(options: InternalRequestOptions): CommandFlags {
     udid: options.udid,
     serial: options.serial,
     iosSimulatorDeviceSet: options.iosSimulatorDeviceSet,
+    iosXctestrunFile: options.iosXctestrunFile,
+    iosXctestDerivedDataPath: options.iosXctestDerivedDataPath,
+    iosXctestEnvDir: options.iosXctestEnvDir,
     androidDeviceAllowlist: options.androidDeviceAllowlist,
     surface: options.surface,
     activity: options.activity,

src/client-types.ts

@@ -74,6 +74,9 @@ export type AgentDeviceClientConfig = {
   runtime?: SessionRuntimeHints;
   cwd?: string;
   debug?: boolean;
+  iosXctestrunFile?: string;
+  iosXctestDerivedDataPath?: string;
+  iosXctestEnvDir?: string;
 };
 
 export type AgentDeviceRequestOverrides = Pick<
@@ -93,6 +96,9 @@ export type AgentDeviceRequestOverrides = Pick<
   | 'leaseBackend'
   | 'cwd'
   | 'debug'
+  | 'iosXctestrunFile'
+  | 'iosXctestDerivedDataPath'
+  | 'iosXctestEnvDir'
 >;
 
 export type AgentDeviceIdentifiers = {

src/commands/cli-grammar/common.ts

@@ -53,6 +53,9 @@ export function commonInputFromFlags(flags: CliFlags): Record<string, unknown> {
     udid: flags.udid,
     serial: flags.serial,
     iosSimulatorDeviceSet: flags.iosSimulatorDeviceSet,
+    iosXctestrunFile: flags.iosXctestrunFile,
+    iosXctestDerivedDataPath: flags.iosXctestDerivedDataPath,
+    iosXctestEnvDir: flags.iosXctestEnvDir,
     androidDeviceAllowlist: flags.androidDeviceAllowlist,
   });
 }

src/commands/command-input.ts

@@ -24,6 +24,9 @@ export type CommonCommandInput = Pick<
   udid?: string;
   serial?: string;
   iosSimulatorDeviceSet?: string;
+  iosXctestrunFile?: string;
+  iosXctestDerivedDataPath?: string;
+  iosXctestEnvDir?: string;
   androidDeviceAllowlist?: string;
 };
 
@@ -283,6 +286,9 @@ export function readCommonInput(
     udid: optionalString(record, 'udid'),
     serial: optionalString(record, 'serial'),
     iosSimulatorDeviceSet: optionalString(record, 'iosSimulatorDeviceSet'),
+    iosXctestrunFile: optionalString(record, 'iosXctestrunFile'),
+    iosXctestDerivedDataPath: optionalString(record, 'iosXctestDerivedDataPath'),
+    iosXctestEnvDir: optionalString(record, 'iosXctestEnvDir'),
     androidDeviceAllowlist: optionalString(record, 'androidDeviceAllowlist'),
     daemonBaseUrl: optionalString(record, 'daemonBaseUrl'),
     daemonAuthToken: optionalString(record, 'daemonAuthToken'),
@@ -448,6 +454,9 @@ export function commonToClientOptions(
     udid: input.udid,
     serial: input.serial,
     iosSimulatorDeviceSet: input.iosSimulatorDeviceSet,
+    iosXctestrunFile: input.iosXctestrunFile,
+    iosXctestDerivedDataPath: input.iosXctestDerivedDataPath,
+    iosXctestEnvDir: input.iosXctestEnvDir,
     androidDeviceAllowlist: input.androidDeviceAllowlist,
     daemonBaseUrl: input.daemonBaseUrl,
     daemonAuthToken: input.daemonAuthToken,
@@ -583,6 +592,18 @@ function commonProperties(): Record<string, JsonSchema> {
       type: 'string',
       description: 'iOS simulator device-set path used for device resolution.',
     },
+    iosXctestrunFile: {
+      type: 'string',
+      description: 'Externally built iOS XCTest runner .xctestrun artifact path.',
+    },
+    iosXctestDerivedDataPath: {
+      type: 'string',
+      description: 'Derived data path for external iOS XCTest runner execution.',
+    },
+    iosXctestEnvDir: {
+      type: 'string',
+      description: 'Writable directory for iOS XCTest runner env overlays.',
+    },
     androidDeviceAllowlist: {
       type: 'string',
       description: 'Android serial allowlist used for device resolution.',

src/core/dispatch-context.ts

@@ -40,6 +40,9 @@ export type DispatchContext = ScreenshotDispatchFlags & {
   verbose?: boolean;
   logPath?: string;
   traceLogPath?: string;
+  iosXctestrunFile?: string;
+  iosXctestDerivedDataPath?: string;
+  iosXctestEnvDir?: string;
   snapshotInteractiveOnly?: boolean;
   snapshotDepth?: number;
   snapshotScope?: string;

src/core/dispatch-interactions.ts

@@ -528,6 +528,9 @@ function runnerOptionsFromContext(context: DispatchContext | undefined): RunnerC
     logPath: context?.logPath,
     traceLogPath: context?.traceLogPath,
     requestId: context?.requestId,
+    iosXctestrunFile: context?.iosXctestrunFile,
+    iosXctestDerivedDataPath: context?.iosXctestDerivedDataPath,
+    iosXctestEnvDir: context?.iosXctestEnvDir,
   };
 }
 
@@ -1024,6 +1027,9 @@ export async function handleReadCommand(
       logPath: context?.logPath,
       traceLogPath: context?.traceLogPath,
       requestId: context?.requestId,
+      iosXctestrunFile: context?.iosXctestrunFile,
+      iosXctestDerivedDataPath: context?.iosXctestDerivedDataPath,
+      iosXctestEnvDir: context?.iosXctestEnvDir,
     },
   );
   const text =

src/core/dispatch.ts

@@ -51,6 +51,9 @@ export async function dispatchCommand(
     verbose: context?.verbose,
     logPath: context?.logPath,
     traceLogPath: context?.traceLogPath,
+    iosXctestrunFile: context?.iosXctestrunFile,
+    iosXctestDerivedDataPath: context?.iosXctestDerivedDataPath,
+    iosXctestEnvDir: context?.iosXctestEnvDir,
   };
   const interactor = await getInteractor(device, runnerCtx);
   emitDiagnostic({

src/core/interactor-types.ts

@@ -16,12 +16,21 @@ export type RunnerContext = {
   verbose?: boolean;
   logPath?: string;
   traceLogPath?: string;
+  iosXctestrunFile?: string;
+  iosXctestDerivedDataPath?: string;
+  iosXctestEnvDir?: string;
 };
 
 /** Subset of {@link RunnerContext} forwarded to runner command invocations. */
 export type RunnerCallOptions = Pick<
   RunnerContext,
-  'verbose' | 'logPath' | 'traceLogPath' | 'requestId'
+  | 'verbose'
+  | 'logPath'
+  | 'traceLogPath'
+  | 'requestId'
+  | 'iosXctestrunFile'
+  | 'iosXctestDerivedDataPath'
+  | 'iosXctestEnvDir'
 >;
 
 export type { BackMode };

src/daemon/context.ts

@@ -29,6 +29,9 @@ export function contextFromFlags(
     verbose: flags?.verbose,
     logPath,
     traceLogPath,
+    iosXctestrunFile: flags?.iosXctestrunFile,
+    iosXctestDerivedDataPath: flags?.iosXctestDerivedDataPath,
+    iosXctestEnvDir: flags?.iosXctestEnvDir,
     snapshotInteractiveOnly: flags?.snapshotInteractiveOnly,
     snapshotDepth: flags?.snapshotDepth,
     snapshotScope: flags?.snapshotScope,

src/daemon/handlers/record-trace-ios.ts

@@ -43,6 +43,9 @@ export function getIosRunnerOptions(
     logPath,
     traceLogPath: session.trace?.outPath,
     requestId: req.meta?.requestId,
+    iosXctestrunFile: req.flags?.iosXctestrunFile,
+    iosXctestDerivedDataPath: req.flags?.iosXctestDerivedDataPath,
+    iosXctestEnvDir: req.flags?.iosXctestEnvDir,
   };
 }
 

src/daemon/handlers/session-open.ts

@@ -188,6 +188,9 @@ async function completeOpenCommand(params: {
     logPath,
     traceLogPath,
     requestId: req.meta?.requestId,
+    iosXctestrunFile: req.flags?.iosXctestrunFile,
+    iosXctestDerivedDataPath: req.flags?.iosXctestDerivedDataPath,
+    iosXctestEnvDir: req.flags?.iosXctestEnvDir,
   };
   const shouldPrewarmRunnerBeforeOpen = req.flags?.maestro?.prewarmRunnerBeforeOpen === true;
   let runnerPrewarm: Promise<void> | undefined;

src/daemon/handlers/session.ts

@@ -97,6 +97,9 @@ function buildPrepareIosRunnerOptions(
     requestId: req.meta?.requestId,
     buildTimeoutMs,
     healthTimeoutMs: Math.min(buildTimeoutMs, PREPARE_IOS_RUNNER_HEALTH_TIMEOUT_MS),
+    iosXctestrunFile: req.flags?.iosXctestrunFile,
+    iosXctestDerivedDataPath: req.flags?.iosXctestDerivedDataPath,
+    iosXctestEnvDir: req.flags?.iosXctestEnvDir,
   };
 }
 

src/daemon/handlers/snapshot-alert.ts

@@ -68,6 +68,9 @@ export async function handleAlertCommand(
     logPath,
     traceLogPath: session?.trace?.outPath,
     requestId: req.meta?.requestId,
+    iosXctestrunFile: req.flags?.iosXctestrunFile,
+    iosXctestDerivedDataPath: req.flags?.iosXctestDerivedDataPath,
+    iosXctestEnvDir: req.flags?.iosXctestEnvDir,
   };
   const runAlert: NativeAlertRunner = async (alertAction) =>
     await runIosRunnerCommand(

src/daemon/selector-runtime.ts

@@ -392,6 +392,9 @@ async function queryDirectIosSelector(
       logPath: params.logPath,
       traceLogPath: session.trace?.outPath,
       requestId: params.req.meta?.requestId,
+      iosXctestrunFile: params.req.flags?.iosXctestrunFile,
+      iosXctestDerivedDataPath: params.req.flags?.iosXctestDerivedDataPath,
+      iosXctestEnvDir: params.req.flags?.iosXctestEnvDir,
     },
   );
   const found = data.found === true;
@@ -648,6 +651,9 @@ async function findText(
         logPath,
         traceLogPath: session?.trace?.outPath,
         requestId: req.meta?.requestId,
+        iosXctestrunFile: req.flags?.iosXctestrunFile,
+        iosXctestDerivedDataPath: req.flags?.iosXctestDerivedDataPath,
+        iosXctestEnvDir: req.flags?.iosXctestEnvDir,
       },
     )) as { found?: boolean };
     return result?.found === true;

src/platforms/ios/__tests__/runner-session.test.ts

@@ -585,6 +585,9 @@ test('runner session starts xcodebuild through provider seams and reuses an aliv
   assert.equal(session.xctestrunPath, '/tmp/session-runner.xctestrun');
   assert.equal(mockRunCmdBackground.mock.calls.length, 1);
   assert.equal(mockRunCmdBackground.mock.calls[0]?.[0], 'xcodebuild');
+  const xcodebuildArgs = mockRunCmdBackground.mock.calls[0]?.[1];
+  assert.ok(Array.isArray(xcodebuildArgs));
+  assert.equal(xcodebuildArgs[xcodebuildArgs.indexOf('-derivedDataPath') + 1], '/tmp/derived');
   assert.deepEqual(mockPrepareXctestrunWithEnv.mock.calls[0]?.[1], {
     AGENT_DEVICE_RUNNER_PORT: '8123',
   });
@@ -734,6 +737,26 @@ test('runner session restarts alive runner when expected xctestrun artifact chan
   assert.equal(mockRunCmdBackground.mock.calls.length, 2);
 });
 
+test('runner session reuses external xctestrun artifact without cache-derived comparison', async () => {
+  const device = { ...IOS_SIMULATOR, id: 'runner-session-external-artifact-sim' };
+  mockEnsureXctestrunArtifact.mockResolvedValueOnce({
+    xctestrunPath: '/tmp/aws/AgentDeviceRunner.xctestrun',
+    derived: '/tmp/aws-derived',
+    cache: 'external',
+    artifact: 'valid',
+    buildMs: 0,
+    xctestrunPathSource: 'external',
+  });
+
+  const session = await ensureRunnerSession(device, {});
+  mockResolveRunnerDerivedPath.mockReturnValue('/tmp/internal-cache-derived');
+  const reused = await ensureRunnerSession(device, {});
+
+  assert.equal(reused, session);
+  assert.equal(mockRunCmdBackground.mock.calls.length, 1);
+  assert.equal(mockEnsureXctestrunArtifact.mock.calls.length, 1);
+});
+
 test('runner session restarts dead runner without graceful shutdown', async () => {
   const device = { ...IOS_SIMULATOR, id: 'runner-session-dead-sim' };