fix: harden maestro ci diagnostics and ios prepare

Author: thymikee

src/compat/maestro/__tests__/runtime-assertions.test.ts

@@ -1,4 +1,7 @@
 import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
 import { afterEach, test, vi } from 'vitest';
 import {
   invokeMaestroAssertNotVisible,
@@ -230,6 +233,46 @@ test('invokeMaestroAssertVisible does not use Android raw fallback for generated
   assert.equal(snapshotFlags.some((flags) => flags?.snapshotRaw === true), false);
 });
 
+test('invokeMaestroAssertVisible writes terminal snapshot artifacts for failed attempts', async () => {
+  const artifactsDir = fs.mkdtempSync(path.join(os.tmpdir(), 'maestro-assert-artifacts-'));
+  try {
+    const response = await invokeMaestroAssertVisible({
+      baseReq: {
+        token: 't',
+        session: 's',
+        flags: { platform: 'android', artifactsDir },
+      },
+      positionals: ['id="album-0"', '0'],
+      invoke: async (): Promise<DaemonResponse> => ({
+        ok: true,
+        data: snapshot([
+          node('Chat', { identifier: 'chat-tab', type: 'android.widget.Button' }),
+          node('Contacts', { identifier: 'contacts-tab', type: 'android.widget.Button' }),
+        ]),
+      }),
+    });
+
+    assert.equal(response.ok, false);
+    if (!response.ok) {
+      const artifactPaths = response.error.details?.artifactPaths;
+      assert.deepEqual(artifactPaths, [
+        path.join(artifactsDir, 'failure-snapshot.json'),
+        path.join(artifactsDir, 'failure-snapshot.txt'),
+      ]);
+    }
+    assert.match(
+      fs.readFileSync(path.join(artifactsDir, 'failure-snapshot.txt'), 'utf8'),
+      /@e1 \[button\] "Chat"/,
+    );
+    assert.match(
+      fs.readFileSync(path.join(artifactsDir, 'failure-snapshot.json'), 'utf8'),
+      /"identifier": "chat-tab"/,
+    );
+  } finally {
+    fs.rmSync(artifactsDir, { recursive: true, force: true });
+  }
+});
+
 test('invokeMaestroAssertVisible treats an elapsed ellipsis loading gate as already past loading', async () => {
   vi.spyOn(Date, 'now').mockReturnValueOnce(0).mockReturnValueOnce(0).mockReturnValueOnce(250);
 

src/compat/maestro/runtime-assertions.ts

@@ -1,7 +1,10 @@
+import fs from 'node:fs';
+import path from 'node:path';
 import { getSnapshotReferenceFrame } from '../../daemon/touch-reference-frame.ts';
 import type { DaemonResponse } from '../../daemon/types.ts';
 import type { ReplayVarScope } from '../../replay/vars.ts';
 import type { SnapshotState } from '../../utils/snapshot.ts';
+import { buildSnapshotDisplayLines } from '../../utils/snapshot-lines.ts';
 import { sleep } from '../../utils/timeouts.ts';
 import {
   captureMaestroSnapshot,
@@ -116,6 +119,7 @@ async function invokeSnapshotMaestroAssertVisible(
   const startedAt = Date.now();
   const deadlineMs = args.timeoutMs + MAESTRO_ASSERTION_POLICY.assertVisibleGraceMs;
   let lastResponse: DaemonResponse | undefined;
+  let lastSnapshot: SnapshotState | undefined;
   let capturedAfterDeadline = false;
   while (true) {
     const captureStartedAt = Date.now();
@@ -124,6 +128,7 @@ async function invokeSnapshotMaestroAssertVisible(
     });
     if (sample.visible) return visibleAssertionResponse(sample.response, args.selector, startedAt);
     lastResponse = sample.response;
+    lastSnapshot = sample.snapshot ?? lastSnapshot;
     const failedSample = handleFailedVisibleSample(params.baseReq, args, sample, startedAt);
     if (failedSample.kind === 'return') return failedSample.response;
 
@@ -141,13 +146,13 @@ async function invokeSnapshotMaestroAssertVisible(
     await sleep(MAESTRO_ASSERTION_POLICY.assertVisiblePollMs);
   }
 
-  return (
+  const response =
     lastResponse ??
     errorResponse('COMMAND_FAILED', `Expected visible but did not match: ${args.selector}`, {
       selector: args.selector,
       timeoutMs: args.timeoutMs,
-    })
-  );
+    });
+  return withMaestroFailureSnapshotArtifacts(response, lastSnapshot, params.baseReq);
 }
 
 function handleFailedVisibleSample(
@@ -378,6 +383,62 @@ function visibleAssertionResponse(
   };
 }
 
+function withMaestroFailureSnapshotArtifacts(
+  response: DaemonResponse,
+  snapshot: SnapshotState | undefined,
+  baseReq: ReplayBaseRequest,
+): DaemonResponse {
+  if (response.ok || !snapshot) return response;
+  const artifactsDir =
+    typeof baseReq.flags?.artifactsDir === 'string' ? baseReq.flags.artifactsDir : undefined;
+  if (!artifactsDir) return response;
+
+  const artifactPaths = writeMaestroFailureSnapshotArtifacts(snapshot, artifactsDir);
+  if (artifactPaths.length === 0) return response;
+  return {
+    ok: false,
+    error: {
+      ...response.error,
+      details: {
+        ...(response.error.details ?? {}),
+        artifactPaths: uniqueStrings([
+          ...readExistingArtifactPaths(response.error.details?.artifactPaths),
+          ...artifactPaths,
+        ]),
+      },
+    },
+  };
+}
+
+function writeMaestroFailureSnapshotArtifacts(
+  snapshot: SnapshotState,
+  artifactsDir: string,
+): string[] {
+  try {
+    fs.mkdirSync(artifactsDir, { recursive: true });
+    const jsonPath = path.join(artifactsDir, 'failure-snapshot.json');
+    const textPath = path.join(artifactsDir, 'failure-snapshot.txt');
+    fs.writeFileSync(jsonPath, `${JSON.stringify(snapshot, null, 2)}\n`);
+    const lines = buildSnapshotDisplayLines(snapshot.nodes, {
+      summarizeTextSurfaces: true,
+    }).map((line) => line.text);
+    fs.writeFileSync(textPath, `${lines.join('\n')}\n`);
+    return [jsonPath, textPath];
+  } catch {
+    return [];
+  }
+}
+
+function readExistingArtifactPaths(value: unknown): string[] {
+  return Array.isArray(value)
+    ? value.filter((entry): entry is string => typeof entry === 'string')
+    : [];
+}
+
+function uniqueStrings(values: string[]): string[] {
+  return [...new Set(values)];
+}
+
 function shouldCaptureOnceAfterDeadline(
   capturedAfterDeadline: boolean,
   captureStartedAt: number,

src/daemon/handlers/__tests__/session.test.ts

@@ -2138,6 +2138,7 @@ test('prepare ios-runner starts the XCTest runner on an explicit iOS selector',
       cleanStaleBundles: true,
       logPath: expect.stringMatching(/daemon\.log$/),
       requestId: 'prepare-request',
+      startupTimeoutMs: 240000,
     }),
   );
   expect((response as any).data).toMatchObject({

src/daemon/handlers/session.ts

@@ -41,6 +41,7 @@ const INVENTORY_COMMANDS = DAEMON_COMMAND_GROUPS.inventory;
 const STATE_COMMANDS = DAEMON_COMMAND_GROUPS.state;
 const OBSERVABILITY_COMMANDS = DAEMON_COMMAND_GROUPS.observability;
 const REPLAY_COMMANDS = DAEMON_COMMAND_GROUPS.replay;
+const PREPARE_IOS_RUNNER_MIN_STARTUP_TIMEOUT_MS = 45_000;
 
 export const SESSION_COMMAND_HANDLERS = {
   ...Object.fromEntries([...INVENTORY_COMMANDS].map((command) => [command, true] as const)),
@@ -111,10 +112,18 @@ function buildPrepareIosRunnerOptions(
     logPath,
     traceLogPath: session?.trace?.outPath,
     cleanStaleBundles: true,
+    startupTimeoutMs: resolvePrepareIosRunnerStartupTimeoutMs(req.flags?.timeoutMs),
     requestId: req.meta?.requestId,
   };
 }
 
+function resolvePrepareIosRunnerStartupTimeoutMs(timeoutMs: unknown): number | undefined {
+  if (typeof timeoutMs !== 'number' || !Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    return undefined;
+  }
+  return Math.max(PREPARE_IOS_RUNNER_MIN_STARTUP_TIMEOUT_MS, Math.floor(timeoutMs));
+}
+
 function prepareIosRunnerResponseData(
   action: string,
   device: DeviceInfo,

src/platforms/ios/__tests__/runner-command-retry.test.ts

@@ -350,6 +350,26 @@ test('read-only commands retry when completed status has no retained response',
   });
 });
 
+test('read-only startup commands use the session startup timeout override', async () => {
+  const session = makeRunnerSession({
+    port: 8100,
+    ready: false,
+    startupTimeoutMs: 240_000,
+  });
+
+  mockEnsureRunnerSession.mockResolvedValue(session);
+  mockExecuteRunnerCommandWithSession.mockResolvedValue({ currentUptimeMs: 42 });
+
+  const result = await runIosRunnerCommand(
+    IOS_SIMULATOR,
+    { command: 'uptime' },
+    { startupTimeoutMs: 240_000 },
+  );
+
+  assert.deepEqual(result, { currentUptimeMs: 42 });
+  assert.equal(mockExecuteRunnerCommandWithSession.mock.calls[0]?.[4], 240_000);
+});
+
 test('read-only commands retry when status shows in-flight work', async () => {
   const session = makeRunnerSession({ port: 8100, ready: true });
 

src/platforms/ios/runner-client.ts

@@ -135,7 +135,9 @@ async function executeRunnerCommand(
   let session: RunnerSession | undefined;
   try {
     session = await ensureRunnerSession(device, options);
-    const timeoutMs = session.ready ? RUNNER_COMMAND_TIMEOUT_MS : RUNNER_STARTUP_TIMEOUT_MS;
+    const timeoutMs = session.ready
+      ? RUNNER_COMMAND_TIMEOUT_MS
+      : readRunnerStartupTimeoutMs(session);
     return await executeRunnerCommandWithSession(
       device,
       session,
@@ -162,7 +164,7 @@ async function executeRunnerCommand(
           session,
           command,
           options.logPath,
-          RUNNER_STARTUP_TIMEOUT_MS,
+          readRunnerStartupTimeoutMs(session),
           signal,
         );
       } catch (retryErr) {
@@ -197,7 +199,7 @@ async function executeRunnerCommand(
           session,
           command,
           options.logPath,
-          RUNNER_STARTUP_TIMEOUT_MS,
+          readRunnerStartupTimeoutMs(session),
           signal,
         );
         emitDiagnostic({
@@ -248,6 +250,10 @@ async function executeRunnerCommand(
   }
 }
 
+function readRunnerStartupTimeoutMs(session: Pick<RunnerSession, 'startupTimeoutMs'>): number {
+  return session.startupTimeoutMs ?? RUNNER_STARTUP_TIMEOUT_MS;
+}
+
 async function handleRunnerTransportErrorAfterCommandSend(
   device: DeviceInfo,
   session: RunnerSession,

src/platforms/ios/runner-provider.ts

@@ -7,6 +7,7 @@ export type AppleRunnerCommandOptions = {
   logPath?: string;
   traceLogPath?: string;
   cleanStaleBundles?: boolean;
+  startupTimeoutMs?: number;
   requestId?: string;
 };
 

src/platforms/ios/runner-session-types.ts

@@ -11,6 +11,7 @@ export type RunnerSession = {
   testPromise: Promise<ExecResult>;
   child: ExecBackgroundResult['child'];
   ready: boolean;
+  startupTimeoutMs?: number;
   lastSuccessfulRunnerResponseAtMs?: number;
   startupTimings?: Record<string, number>;
   startupTimingsReported?: boolean;

src/platforms/ios/runner-session.ts

@@ -39,6 +39,7 @@ export type RunnerSessionOptions = {
   logPath?: string;
   traceLogPath?: string;
   cleanStaleBundles?: boolean;
+  startupTimeoutMs?: number;
   requestId?: string;
 };
 
@@ -191,6 +192,7 @@ export async function ensureRunnerSession(
       testPromise,
       child,
       ready: false,
+      startupTimeoutMs: normalizeRunnerStartupTimeoutMs(options.startupTimeoutMs),
       startupTimings,
       simulatorSetRedirect: simulatorSetRedirect ?? undefined,
     };
@@ -504,7 +506,7 @@ export async function executeRunnerCommandWithSession(
   if (preflightDecision.action === 'run') {
     const readinessTimeoutMs = session.ready
       ? Math.min(RUNNER_READY_PREFLIGHT_TIMEOUT_MS, deadline.remainingMs())
-      : Math.min(RUNNER_STARTUP_TIMEOUT_MS, deadline.remainingMs());
+      : Math.min(readRunnerStartupTimeoutMs(session), deadline.remainingMs());
     try {
       const readinessResponse = await withDiagnosticTimer(
         'ios_runner_readiness_preflight',
@@ -701,6 +703,16 @@ function markRunnerPreflightError(error: unknown, details: Record<string, unknow
   );
 }
 
+function readRunnerStartupTimeoutMs(session: Pick<RunnerSession, 'startupTimeoutMs'>): number {
+  return session.startupTimeoutMs ?? RUNNER_STARTUP_TIMEOUT_MS;
+}
+
+function normalizeRunnerStartupTimeoutMs(value: number | undefined): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0
+    ? Math.floor(value)
+    : undefined;
+}
+
 async function measureRunnerStartupStep<T>(
   timings: Record<string, number>,
   phase: string,