Skip to content

Commit ec311d0

Browse files
committed
fix: route physical iOS operations through device control
1 parent 9f52c6a commit ec311d0

22 files changed

Lines changed: 561 additions & 295 deletions

‎src/cli/parser/__tests__/cli-help-topics.test.ts‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -473,7 +473,10 @@ test('usageForCommand resolves physical-device help topic', async () => {
473473
assert.match(help, /profile name\/specifier, not a file path/);
474474
assert.match(help, /Older devices visible only to xctrace use the XCTest backend automatically/);
475475
assert.match(help, /runner commands travel through macOS usbmuxd/);
476-
assert.match(help, /app inventory, install\/reinstall, deep links, and launch arguments/);
476+
assert.match(
477+
help,
478+
/app inventory, install\/reinstall, logs, performance sampling, recording, deep links, and launch arguments/,
479+
);
477480
});
478481

479482
test('usageForCommand resolves manual QA help topic', async () => {

‎src/cli/parser/cli-help.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -806,7 +806,7 @@ iOS physical-device prerequisites:
806806
Xcode, xcrun xcdevice, and xcrun xctrace must be available from the selected Xcode.
807807
The device must be paired/trusted, connected, unlocked when needed, and have Developer Mode enabled.
808808
Modern devices visible to devicectl use CoreDevice. Older devices visible only to xctrace use the XCTest backend automatically.
809-
XCTest-backed devices must already have the target app installed and should be opened by bundle ID; app inventory, install/reinstall, deep links, and launch arguments require CoreDevice.
809+
XCTest-backed devices must already have the target app installed and should be opened by bundle ID; app inventory, install/reinstall, logs, performance sampling, recording, deep links, and launch arguments require CoreDevice.
810810
XCTest-backed runner commands travel through macOS usbmuxd; keep the trusted device connected by cable.
811811
The AgentDeviceRunner XCTest host must be signed before commands can run on a physical device.
812812
Start with Automatic Signing and only these env vars:

‎src/core/__tests__/capabilities.test.ts‎

Lines changed: 30 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
import { test } from 'vitest';
22
import assert from 'node:assert/strict';
3-
import { isCommandSupportedOnDevice } from '../capabilities.ts';
3+
import { isCommandSupportedOnDevice, unsupportedHintForDevice } from '../capabilities.ts';
44
import { matchesPlatformSelector, type DeviceInfo } from '../../kernel/device.ts';
55
import { WEB_DESKTOP_DEVICE } from '../../__tests__/test-utils/index.ts';
66

@@ -18,6 +18,12 @@ const iosDevice: DeviceInfo = {
1818
kind: 'device',
1919
};
2020

21+
const xctestIosDevice: DeviceInfo = {
22+
...iosDevice,
23+
id: 'xctest-dev-1',
24+
iosPhysicalDeviceBackend: 'xctest',
25+
};
26+
2127
const iPadOsDevice: DeviceInfo = {
2228
platform: 'apple',
2329
appleOs: 'ipados',
@@ -215,6 +221,29 @@ test('core commands support iOS simulator, iOS device, and Android', () => {
215221
);
216222
});
217223

224+
test('capabilities reject CoreDevice-only commands for XCTest-backed devices', () => {
225+
const coreDeviceOnlyCommands = [
226+
'apps',
227+
'install',
228+
'install-from-source',
229+
'logs',
230+
'perf',
231+
'record',
232+
'reinstall',
233+
];
234+
assertCommandSupport(coreDeviceOnlyCommands, [
235+
{ device: iosDevice, expected: true, label: 'on CoreDevice' },
236+
{ device: xctestIosDevice, expected: false, label: 'on XCTest backend' },
237+
]);
238+
for (const command of coreDeviceOnlyCommands) {
239+
assert.match(unsupportedHintForDevice(command, xctestIosDevice) ?? '', /CoreDevice-backed/);
240+
}
241+
assertCommandSupport(
242+
['close', 'open', 'screenshot', 'snapshot'],
243+
[{ device: xctestIosDevice, expected: true, label: 'on XCTest backend' }],
244+
);
245+
});
246+
218247
test('macOS supports the Apple runner interaction core but excludes mobile-only commands', () => {
219248
assertCommandSupport(
220249
[

‎src/daemon/app-log-doctor.ts‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ import {
77
IOS_DEVICE_CONSOLE_CAPTURE_PROBE_FAILED_NOTE,
88
IOS_DEVICE_CONSOLE_CAPTURE_UNSUPPORTED_NOTE,
99
} from './app-log-ios.ts';
10+
import { checkCoreDeviceAvailable } from '../platforms/apple/core/physical-device-console.ts';
1011

1112
export type AppLogDoctorResult = {
1213
checks: Record<string, boolean>;
@@ -77,10 +78,7 @@ async function runIosSimulatorAppLogDoctor(): Promise<Record<string, boolean>> {
7778
async function runIosDeviceAppLogDoctor(): Promise<AppLogDoctorResult> {
7879
const checks: Record<string, boolean> = {};
7980
const notes: string[] = [];
80-
checks.devicectlAvailable = await safeCheck(async () => {
81-
const devicectl = await runXcrun(['devicectl', '--version'], { allowFailure: true });
82-
return devicectl.exitCode === 0;
83-
});
81+
checks.devicectlAvailable = await safeCheck(checkCoreDeviceAvailable);
8482
if (!checks.devicectlAvailable) return { checks, notes };
8583

8684
const consoleCapture = await checkIosDeviceConsoleCaptureSupport();

‎src/daemon/app-log-ios.ts‎

Lines changed: 9 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,13 @@ import fs from 'node:fs';
22
import path from 'node:path';
33
import { buildSimctlArgs } from '../platforms/apple/core/simctl.ts';
44
import { AppError } from '../kernel/errors.ts';
5-
import { runCmd, runCmdBackground, type ExecResult } from '../utils/exec.ts';
5+
import { runCmd, runCmdBackground } from '../utils/exec.ts';
66
import { runXcrun } from '../platforms/apple/core/tool-provider.ts';
7+
import {
8+
buildCoreDeviceConsoleLaunchArgs,
9+
checkCoreDeviceConsoleCaptureSupport,
10+
type CoreDeviceConsoleCaptureSupport,
11+
} from '../platforms/apple/core/physical-device-console.ts';
712
import {
813
clearPidFile,
914
writePidFile,
@@ -27,11 +32,7 @@ export const IOS_DEVICE_CONSOLE_CAPTURE_PROBE_FAILED_NOTE = formatIosDeviceConso
2732
IOS_DEVICE_CONSOLE_CAPTURE_PROBE_FAILED,
2833
);
2934

30-
export type IosDeviceConsoleCaptureSupport =
31-
| { supported: true; stderr?: string }
32-
| { supported: false; reason: 'unsupported' | 'probe-failed'; stderr?: string };
33-
34-
let cachedSupportedIosDeviceConsoleCapture: IosDeviceConsoleCaptureSupport | undefined;
35+
export type IosDeviceConsoleCaptureSupport = CoreDeviceConsoleCaptureSupport;
3536

3637
export function buildAppleLogPredicate(
3738
appBundleId: string,
@@ -83,62 +84,17 @@ export function buildIosSimulatorLogStreamArgs(params: {
8384
}
8485

8586
export function buildIosDeviceConsoleLaunchArgs(deviceId: string, appBundleId: string): string[] {
86-
return [
87-
'devicectl',
88-
'device',
89-
'process',
90-
'launch',
91-
'--device',
92-
deviceId,
93-
'--console',
94-
'--terminate-existing',
95-
appBundleId,
96-
];
87+
return buildCoreDeviceConsoleLaunchArgs(deviceId, appBundleId);
9788
}
9889

9990
export async function checkIosDeviceConsoleCaptureSupport(): Promise<IosDeviceConsoleCaptureSupport> {
100-
if (cachedSupportedIosDeviceConsoleCapture) return cachedSupportedIosDeviceConsoleCapture;
101-
try {
102-
const result = await runXcrun(['devicectl', 'device', 'process', 'launch', '--help'], {
103-
allowFailure: true,
104-
timeoutMs: 5_000,
105-
});
106-
const support = readIosDeviceConsoleCaptureSupport(result);
107-
if (support.supported) cachedSupportedIosDeviceConsoleCapture = support;
108-
return support;
109-
} catch (error) {
110-
return {
111-
supported: false,
112-
reason: 'probe-failed',
113-
stderr: error instanceof Error ? error.message : undefined,
114-
};
115-
}
116-
}
117-
118-
function readIosDeviceConsoleCaptureSupport(result: ExecResult): IosDeviceConsoleCaptureSupport {
119-
const stderr = result.stderr.trim() || undefined;
120-
if (result.exitCode !== 0) {
121-
return { supported: false, reason: 'probe-failed', stderr };
122-
}
123-
if (!isIosDeviceConsoleCaptureHelp(result.stdout, result.stderr)) {
124-
return { supported: false, reason: 'unsupported', stderr };
125-
}
126-
return { supported: true, stderr };
91+
return await checkCoreDeviceConsoleCaptureSupport();
12792
}
12893

12994
function formatIosDeviceConsoleCaptureNote(message: { message: string; hint: string }): string {
13095
return `${message.message} ${message.hint}`;
13196
}
13297

133-
function isIosDeviceConsoleCaptureHelp(stdout: string, stderr: string): boolean {
134-
const help = `${stdout}\n${stderr}`;
135-
return (
136-
/\bUSAGE:\s+devicectl device process launch\b/i.test(help) &&
137-
/--console\b/.test(help) &&
138-
/--terminate-existing\b/.test(help)
139-
);
140-
}
141-
14298
export async function readRecentIosSimulatorLogShowForBundle(params: {
14399
deviceId: string;
144100
appBundleId: string;

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

Lines changed: 11 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ import { isIosFamily } from '../../kernel/device.ts';
22
import { SessionStore } from '../session-store.ts';
33
import type { DaemonRequest, DaemonResponse, SessionState } from '../types.ts';
44
import { emitDiagnostic } from '../../utils/diagnostics.ts';
5-
import { IOS_RUNNER_CONTAINER_BUNDLE_IDS } from '../../platforms/apple/core/runner/runner-client.ts';
5+
import { resolveIosPhysicalDeviceControl } from '../../platforms/apple/core/physical-device-control.ts';
66
import { formatRecordTraceError } from '../record-trace-errors.ts';
77
import { buildAppleRunnerRequestOptions } from '../apple-runner-options.ts';
88
import type { RecordTraceDeps, RecordingBase } from './record-trace-types.ts';
@@ -328,39 +328,17 @@ export async function stopIosDeviceRecording(params: {
328328
deps,
329329
});
330330

331-
let copyResult = { stdout: '', stderr: '', exitCode: 1 };
332-
for (const bundleId of IOS_RUNNER_CONTAINER_BUNDLE_IDS) {
333-
copyResult = await deps.runCmd(
334-
'xcrun',
335-
[
336-
'devicectl',
337-
'device',
338-
'copy',
339-
'from',
340-
'--device',
341-
device.id,
342-
'--source',
343-
recording.remotePath,
344-
'--destination',
345-
recording.outPath,
346-
'--domain-type',
347-
'appDataContainer',
348-
'--domain-identifier',
349-
bundleId,
350-
],
351-
{ allowFailure: true },
331+
try {
332+
await resolveIosPhysicalDeviceControl(device).copyRunnerFile(
333+
device,
334+
recording.remotePath,
335+
recording.outPath,
336+
);
337+
} catch (error) {
338+
return errorResponse(
339+
'COMMAND_FAILED',
340+
`failed to copy recording from device: ${formatRecordTraceError(error)}`,
352341
);
353-
if (copyResult.exitCode === 0) {
354-
break;
355-
}
356-
}
357-
358-
if (copyResult.exitCode !== 0) {
359-
const copyError =
360-
copyResult.stderr.trim() ||
361-
copyResult.stdout.trim() ||
362-
`devicectl exited with code ${copyResult.exitCode}`;
363-
return errorResponse('COMMAND_FAILED', `failed to copy recording from device: ${copyError}`);
364342
}
365343

366344
await deps.waitForStableFile(recording.outPath);

‎src/platforms/apple/core/__tests__/index.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -66,9 +66,9 @@ import {
6666
captureSimulatorScreenshotWithRetry,
6767
captureScreenshotViaRunner,
6868
resolveSimulatorRunnerScreenshotCandidatePaths,
69-
shouldFallbackToRunnerForIosScreenshot,
7069
shouldRetryIosSimulatorScreenshot,
7170
} from '../screenshot.ts';
71+
import { shouldFallbackToRunnerForIosScreenshot } from '../physical-device-screenshot.ts';
7272
import { ensureBootedSimulator, openIosSimulatorApp } from '../simulator.ts';
7373
import {
7474
invalidateSimulatorStatusBarOverrideCache,

‎src/platforms/apple/core/__tests__/physical-device-control.test.ts‎

Lines changed: 22 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -5,12 +5,12 @@ import path from 'node:path';
55
import { test } from 'vitest';
66
import { IOS_DEVICE as SHARED_IOS_DEVICE } from '../../../../__tests__/test-utils/index.ts';
77
import type { DeviceInfo } from '../../../../kernel/device.ts';
8+
import { createAppleInteractor } from '../../interactor.ts';
89
import { installIosApp } from '../app-install.ts';
910
import { closeIosApp, openIosApp } from '../app-launch.ts';
1011
import { listIosApps } from '../app-resolution.ts';
1112
import { resolveIosPhysicalDeviceControl } from '../physical-device-control.ts';
1213
import { withAppleRunnerProvider } from '../runner/runner-provider.ts';
13-
import { captureScreenshotViaRunner } from '../screenshot.ts';
1414
import { withAppleToolProvider } from '../tool-provider.ts';
1515

1616
const IOS_DEVICE: DeviceInfo = {
@@ -85,23 +85,37 @@ test('app lifecycle uses runner commands for an xctrace-only physical device', a
8585
);
8686
});
8787

88-
test('runner screenshots stay in-band when CoreDevice file copy is unavailable', async () => {
88+
test('default interactor screenshots stay in-band without invoking devicectl', async () => {
8989
const outPath = path.join(
9090
await fs.mkdtemp(path.join(os.tmpdir(), 'agent-device-xctest-screenshot-')),
9191
'screen.png',
9292
);
93+
const toolCalls: string[][] = [];
9394
try {
94-
await withAppleRunnerProvider(
95-
async (_device, command) => {
96-
assert.equal(command.inlineScreenshot, true);
97-
return { imageBase64: Buffer.from('png-bytes').toString('base64') };
95+
await withAppleToolProvider(
96+
async (_cmd, args) => {
97+
toolCalls.push(args);
98+
return { exitCode: 0, stdout: '', stderr: '' };
9899
},
99-
{ deviceId: XCTEST_IOS_DEVICE.id },
100100
async () =>
101-
await captureScreenshotViaRunner(XCTEST_IOS_DEVICE, outPath, 'com.example.app', undefined),
101+
await withAppleRunnerProvider(
102+
async (_device, command) => {
103+
assert.equal(command.inlineScreenshot, true);
104+
return { imageBase64: Buffer.from('png-bytes').toString('base64') };
105+
},
106+
{ deviceId: XCTEST_IOS_DEVICE.id },
107+
async () =>
108+
await createAppleInteractor(XCTEST_IOS_DEVICE, {
109+
appBundleId: 'com.example.app',
110+
}).screenshot(outPath),
111+
),
102112
);
103113

104114
assert.equal(await fs.readFile(outPath, 'utf8'), 'png-bytes');
115+
assert.equal(
116+
toolCalls.some((args) => args[0] === 'devicectl'),
117+
false,
118+
);
105119
} finally {
106120
await fs.rm(path.dirname(outPath), { recursive: true, force: true });
107121
}

‎src/platforms/apple/core/app-info.ts‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,3 +3,13 @@ export type IosAppInfo = {
33
name: string;
44
url?: string;
55
};
6+
7+
export type IosDeviceProcessInfo = {
8+
executable: string;
9+
pid: number;
10+
};
11+
12+
export type IosDeviceAppProcesses = {
13+
appBundleUrl: string;
14+
processes: IosDeviceProcessInfo[];
15+
};

0 commit comments

Comments
 (0)