Skip to content

Commit 0683a3d

Browse files
committed
refactor(ios-runner): name the runner session xctestrun as a process-identity contract
A runner launch is killed by matching `xcodebuild`'s argv with `pkill -f`, and that argv carries the per-session xctestrun's filename. The filename is therefore a process-identity contract, but it was spelled three times: inline in the session, inline in disposal, and again in the daemon-client timeout sweep. Disposal escaped the device id for regex without flattening it the way the writer's filesystem sanitization does, so a device id needing flattening built a cleanup pattern that could not match the file the writer had already written. Name it once. `runner-artifact-env.ts` now owns the stem, the suffix field order, the sanitization, and the `pkill -f` pattern derived from those same parts, and the writer, the session, and disposal all go through it. The name lives in the writer rather than a shared contracts module because the timeout sweep must not follow a rename: it ships separately, cannot know which version named a timed-out launch, and has to keep matching the names older writers used. So the sweep keeps a pinned literal, and its test proves those bytes still select both the owner-token and the pre-owner-token spelling. Placing the name in the module the Apple façades already evaluate also holds the eager-closure budget (#1960) at zero new edges. Verified byte-for-byte against the previous patterns for concrete, host-style, and flattened device ids. The only divergence is the flattened case, where the old pattern failed to match its own file. Also record three tooling constraints read from `xcodebuild(1)` and `simctl help`, and checked on Xcode 27.1: only `TEST_RUNNER_`-prefixed names cross into the test runner; `simctl launch --stdout/--stderr` resolve their paths inside the device's data container, so `--console-pty` is the console mode this host path can use; and xcodebuild re-synthesizes the attachment-lifetime keys from its own defaults, since a plan setting `keepNever` still builds an xctestrun carrying `SystemAttachmentLifetime=deleteOnSuccess`.
1 parent bce6f52 commit 0683a3d

9 files changed

Lines changed: 245 additions & 13 deletions

File tree

‎packages/platform-apple/src/core/app-launch.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -291,6 +291,10 @@ function buildIosSimulatorLaunchArgs(
291291
options?: { launchConsole?: string; launchArgs?: string[]; terminateRunningApp?: boolean },
292292
): string[] {
293293
const args = ['launch'];
294+
// `--console-pty` is the console mode this path needs: simctl writes the app's bytes to its own
295+
// stdout through a PTY, which is what the caller redirects. `--stdout=<path>`/`--stderr=<path>`
296+
// cannot substitute, because they resolve the given path inside the device's data container
297+
// rather than on the host. Verified on Xcode 27.1.
294298
if (options?.launchConsole) args.push('--console-pty');
295299
if (options?.terminateRunningApp) args.push('--terminate-running-process');
296300
args.push(deviceId, bundleId);
Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
import assert from 'node:assert/strict';
2+
import { test } from 'vitest';
3+
import {
4+
buildRunnerSessionXctestrunCleanupPattern,
5+
buildRunnerSessionXctestrunSuffix,
6+
} from '../runner-artifact-env.ts';
7+
8+
// Released daemons and clients pkill runner launches by these exact bytes, and the timeout client
9+
// pins its own copy rather than deriving it, so it survives a rename here. Each expectation below
10+
// is a literal on purpose: deriving it from this same module would survive any rename, which is
11+
// precisely the change these lines exist to catch.
12+
13+
test('the session suffix keeps the bytes and field order the matchers rely on', () => {
14+
assert.equal(
15+
buildRunnerSessionXctestrunSuffix({
16+
deviceId: 'SIM-001',
17+
ownerToken: 'owner-4242-ab12cd34',
18+
port: 8123,
19+
}),
20+
'session-SIM-001-owner-4242-ab12cd34-8123',
21+
);
22+
});
23+
24+
test('the owner cleanup pattern keeps the bytes released daemons pkilled', () => {
25+
const owned = buildRunnerSessionXctestrunCleanupPattern({
26+
deviceId: 'SIM-001',
27+
ownerToken: 'owner-4242-ab12cd34',
28+
});
29+
30+
assert.equal(owned, String.raw`AgentDeviceRunner\.env\.session-SIM-001-owner-4242-ab12cd34-`);
31+
assert.equal(
32+
new RegExp(owned).test(argvFor(sessionFileName('SIM-001', 'owner-4242-ab12cd34'))),
33+
true,
34+
);
35+
assert.equal(
36+
new RegExp(owned).test(argvFor(sessionFileName('SIM-002', 'owner-4242-ab12cd34'))),
37+
false,
38+
'another device must not match',
39+
);
40+
assert.equal(
41+
new RegExp(owned).test(argvFor(sessionFileName('SIM-001', 'owner-9999-ffee00'))),
42+
false,
43+
'another owner must not match',
44+
);
45+
});
46+
47+
test('a tokenless cleanup pattern keeps selecting the pre-owner-token name and only that', () => {
48+
// A reclaiming daemon with no lease to read knows the device but not the owner, so it sweeps by
49+
// device. The released bytes require a digit right after the device, which is the pre-owner-token
50+
// spelling; an owner-token name needs its token to be selected.
51+
const tokenless = buildRunnerSessionXctestrunCleanupPattern({ deviceId: 'SIM-002' });
52+
53+
assert.equal(tokenless, String.raw`AgentDeviceRunner\.env\.session-SIM-002-[0-9]`);
54+
assert.equal(
55+
new RegExp(tokenless).test(argvFor('AgentDeviceRunner.env.session-SIM-002-8123.xctestrun')),
56+
true,
57+
);
58+
assert.equal(
59+
new RegExp(tokenless).test(argvFor(sessionFileName('SIM-002', 'owner-1-ff'))),
60+
false,
61+
);
62+
});
63+
64+
test('a name field is sanitized the way the filesystem writer sanitizes it', () => {
65+
// A device id is caller-supplied and the writer flattens it onto disk, so the matcher has to
66+
// flatten it too or it selects a name the launch never had.
67+
const suffix = buildRunnerSessionXctestrunSuffix({
68+
deviceId: 'SIM 01/x',
69+
ownerToken: 'owner 7',
70+
port: 80,
71+
});
72+
73+
assert.equal(suffix, 'session-SIM_01_x-owner_7-80');
74+
assert.equal(
75+
new RegExp(
76+
buildRunnerSessionXctestrunCleanupPattern({ deviceId: 'SIM 01/x', ownerToken: 'owner 7' }),
77+
).test(argvFor(`AgentDeviceRunner.env.${suffix}.xctestrun`)),
78+
true,
79+
);
80+
});
81+
82+
function sessionFileName(deviceId: string, ownerToken: string): string {
83+
return `AgentDeviceRunner.env.${buildRunnerSessionXctestrunSuffix({ deviceId, ownerToken, port: 8123 })}.xctestrun`;
84+
}
85+
86+
function argvFor(fileName: string): string {
87+
return `xcodebuild test-without-building -xctestrun /derived/Build/Products/${fileName}`;
88+
}

‎packages/platform-apple/src/runner/__tests__/runner-xctestrun.test.ts‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,10 @@ import os from 'node:os';
66
import path from 'node:path';
77
import { pathToFileURL } from 'node:url';
88
import { mkdtempForTestSync } from './tmp-dir.ts';
9+
import {
10+
buildRunnerSessionXctestrunCleanupPattern,
11+
buildRunnerSessionXctestrunSuffix,
12+
} from '../runner-artifact-env.ts';
913
import { appleRunnerTestHost } from '../test-host.ts';
1014
import type { ExecOptions, ExecResult } from '@agent-device/host-kit/command';
1115

@@ -358,6 +362,42 @@ test('prepareXctestrunWithEnv writes env overlays into configured env dir', asyn
358362
});
359363
});
360364

365+
test('the session xctestrun the writer builds is found by the cleanup matcher', async () => {
366+
// The launch is killed by `pkill -f` on a pattern the writer module itself builds, and the
367+
// daemon-client sweep pins its own looser copy of these bytes. Binding writer to pattern and to
368+
// those pinned bytes here is what makes a rename that keeps each side self-consistent fail.
369+
await withTempDir('runner-xctestrun-identity-', async (root) => {
370+
const xctestrunPath = path.join(root, 'AgentDeviceRunner.xctestrun');
371+
fs.writeFileSync(
372+
xctestrunPath,
373+
JSON.stringify({
374+
TestConfigurations: [{ TestTargets: [{ TestBundlePath: 'AgentDeviceRunnerUITests' }] }],
375+
}),
376+
);
377+
appleRunnerTestHost.update({ runAppleToolCommand: fakeXctestrunPlutilToolCommand() });
378+
const suffix = buildRunnerSessionXctestrunSuffix({
379+
deviceId: 'SIM-001',
380+
ownerToken: 'owner-4242-ab12cd34',
381+
port: 8123,
382+
});
383+
384+
const prepared = await prepareXctestrunWithEnv(xctestrunPath, runnerPortEnv, suffix);
385+
const argv = `xcodebuild test-without-building -xctestrun ${prepared.xctestrunPath}`;
386+
387+
// The bytes the timeout sweep pins literally, so the sweep cannot drift off the writer's name.
388+
assert.match(argv, new RegExp(String.raw`xcodebuild .*AgentDeviceRunner\.env\.session-`));
389+
assert.match(
390+
argv,
391+
new RegExp(
392+
`xcodebuild.*test-without-building.*${buildRunnerSessionXctestrunCleanupPattern({
393+
deviceId: 'SIM-001',
394+
ownerToken: 'owner-4242-ab12cd34',
395+
})}`,
396+
),
397+
);
398+
});
399+
});
400+
361401
test('prepareXctestrunWithEnv leaves unrelated targets without capture policy', async () => {
362402
await withTempDir('runner-xctestrun-policy-', async (root) => {
363403
const xctestrunPath = path.join(root, 'AgentDeviceRunner.xctestrun');

‎packages/platform-apple/src/runner/runner-artifact-env.ts‎

Lines changed: 74 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,71 @@ import { requireExecSuccess, runAppleToolCommand } from './host.ts';
66
/** The xctestrun plist spells environment blocks as fully defined string maps. */
77
type EnvMap = Record<string, string>;
88

9+
/**
10+
* The name of the per-session `.xctestrun` a runner launch is started with, and the patterns that
11+
* find that launch again by name.
12+
*
13+
* The name reaches `xcodebuild`'s argv as `-xctestrun <dir>/<name>.xctestrun`, and runner cleanup
14+
* selects the live launch by matching that argv with `pkill -f`: a daemon kills the launches it
15+
* started itself, and a daemon reclaiming a lease kills another daemon's. The name is therefore a
16+
* durable process-identity contract, not a scratch filename: renaming it, or reordering the
17+
* suffix, orphans the xcodebuilds an earlier version started. The daemon-client timeout sweep
18+
* ships separately and cannot follow a rename, so it pins these bytes as a literal instead of
19+
* deriving them; its test proves the literal still selects both name eras.
20+
*/
21+
const RUNNER_SESSION_XCTESTRUN_STEM = 'AgentDeviceRunner.env';
22+
23+
/** First field of the session suffix; {@link prepareXctestrunWithEnv} joins it to the stem. */
24+
const SESSION_FIELD_PREFIX = 'session';
25+
26+
/**
27+
* The session-name prefix as extended-regular-expression source for `pkill -f`, including the
28+
* separator that follows it. Spelled from the same parts the writer joins, so the filename and its
29+
* matchers cannot disagree about whether a dot is literal.
30+
*/
31+
const RUNNER_SESSION_XCTESTRUN_NAME_PATTERN = `${escapeForExtendedRegex(
32+
`${RUNNER_SESSION_XCTESTRUN_STEM}.${SESSION_FIELD_PREFIX}`,
33+
)}-`;
34+
35+
/**
36+
* Builds the suffix the session writes after the stem: `session-<deviceId>-<ownerToken>-<port>`.
37+
* Cleanup matches on that exact field order, and the sanitization is what keeps a device id holding
38+
* a path separator from naming a file the matcher can never select.
39+
*/
40+
export function buildRunnerSessionXctestrunSuffix(
41+
params: Readonly<{ deviceId: string; ownerToken: string; port: number }>,
42+
): string {
43+
return sanitizeRunnerSessionNameField(
44+
`${SESSION_FIELD_PREFIX}-${params.deviceId}-${params.ownerToken}-${params.port}`,
45+
);
46+
}
47+
48+
/**
49+
* The `pkill -f` pattern selecting one device's runner launches, for a caller that knows the owner
50+
* token or does not. Without a token the device is followed by the port — the pre-owner-token
51+
* spelling, kept matchable because a released version may still hold such a launch.
52+
*/
53+
export function buildRunnerSessionXctestrunCleanupPattern(
54+
params: Readonly<{ deviceId: string; ownerToken?: string | undefined }>,
55+
): string {
56+
const deviceId = escapeForExtendedRegex(sanitizeRunnerSessionNameField(params.deviceId));
57+
const { ownerToken } = params;
58+
return ownerToken === undefined
59+
? `${RUNNER_SESSION_XCTESTRUN_NAME_PATTERN}${deviceId}-[0-9]`
60+
: `${RUNNER_SESSION_XCTESTRUN_NAME_PATTERN}${deviceId}-${escapeForExtendedRegex(
61+
sanitizeRunnerSessionNameField(ownerToken),
62+
)}-`;
63+
}
64+
65+
/** Characters a session name may carry; anything else is flattened, as the filesystem does. */
66+
function sanitizeRunnerSessionNameField(value: string): string {
67+
return value.replaceAll(/[^a-zA-Z0-9._-]/g, '_');
68+
}
69+
70+
function escapeForExtendedRegex(value: string): string {
71+
return value.replaceAll(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
72+
}
73+
974
const RUNNER_XCTESTRUN_CAPTURE_OPTIONS = {
1075
PreferredScreenCaptureFormat: 'screenshots',
1176
SystemAttachmentLifetime: 'keepNever',
@@ -44,14 +109,18 @@ export async function prepareXctestrunWithEnv(
44109
const configuredEnvDir = options.iosXctestEnvDir?.trim();
45110
const dir = configuredEnvDir ? path.resolve(configuredEnvDir) : path.dirname(xctestrunPath);
46111
fs.mkdirSync(dir, { recursive: true });
47-
const safeSuffix = suffix.replaceAll(/[^a-zA-Z0-9._-]/g, '_');
48-
const tmpJsonPath = path.join(dir, `AgentDeviceRunner.env.${safeSuffix}.json`);
49-
const tmpXctestrunPath = path.join(dir, `AgentDeviceRunner.env.${safeSuffix}.xctestrun`);
112+
const safeSuffix = sanitizeRunnerSessionNameField(suffix);
113+
const tmpJsonPath = path.join(dir, `${RUNNER_SESSION_XCTESTRUN_STEM}.${safeSuffix}.json`);
114+
const tmpXctestrunPath = path.join(
115+
dir,
116+
`${RUNNER_SESSION_XCTESTRUN_STEM}.${safeSuffix}.xctestrun`,
117+
);
50118
const parsed = await readXctestrunPlist(xctestrunPath);
51119

52120
visitXctestrunTargets(parsed, (target) => mergeEnvIntoXctestrunTarget(target, envVars));
53-
// Xcode 26.2 can emit attachment lifetime values that differ from the test plan,
54-
// so normalize the per-session xctestrun immediately before test-without-building.
121+
// Xcode re-synthesizes these keys from its own defaults, not the test plan: building this
122+
// runner's plan (which sets keepNever) still yields SystemAttachmentLifetime=deleteOnSuccess on
123+
// Xcode 26.2 and 27.1, so a launch that skipped this rewrite would keep a screenshot per test.
55124
applyRunnerXctestrunCapturePolicy(parsed);
56125
await writeXctestrunPlist(parsed, tmpJsonPath, tmpXctestrunPath);
57126

‎packages/platform-apple/src/runner/runner-disposal.ts‎

Lines changed: 4 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ import {
99
runXcrun,
1010
} from './host.ts';
1111
import type { ExecBackgroundResult } from '@agent-device/host-kit/command';
12+
import { buildRunnerSessionXctestrunCleanupPattern } from './runner-artifact-env.ts';
1213
import { isMacOs, type DeviceInfo } from '@agent-device/kernel/device';
1314
import { cleanupTempFile } from './runner-io.ts';
1415
import { waitForRunner } from './runner-startup-transport.ts';
@@ -331,9 +332,9 @@ async function killRunnerXcodebuildProcesses(
331332
deviceId: string,
332333
ownerToken: string | undefined,
333334
): Promise<void> {
334-
const pattern = ownerToken
335-
? `xcodebuild.*test-without-building.*AgentDeviceRunner\\.env\\.session-${escapeRegex(deviceId)}-${escapeRegex(ownerToken)}-`
336-
: `xcodebuild.*test-without-building.*AgentDeviceRunner\\.env\\.session-${escapeRegex(deviceId)}-[0-9]`;
335+
const pattern = `xcodebuild.*test-without-building.*${buildRunnerSessionXctestrunCleanupPattern(
336+
ownerToken === undefined ? { deviceId } : { deviceId, ownerToken },
337+
)}`;
337338
for (const signal of ['TERM', 'KILL'] as const) {
338339
try {
339340
await runAppleToolCommand('pkill', [`-${signal}`, '-f', pattern], {
@@ -353,7 +354,3 @@ async function killRunnerXcodebuildProcesses(
353354
}
354355
}
355356
}
356-
357-
function escapeRegex(value: string): string {
358-
return value.replaceAll(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
359-
}

‎packages/platform-apple/src/runner/runner-process-launch.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -85,6 +85,10 @@ export function launchRunnerProcess(input: LaunchRunnerProcessInput): LaunchedRu
8585
],
8686
{
8787
allowFailure: true,
88+
// xcodebuild does not forward its own environment to the test runner: per xcodebuild(1),
89+
// only names prefixed `TEST_RUNNER_` cross that boundary, with the prefix stripped. This
90+
// entry is visible to xcodebuild alone, and the runner reads its port from the session
91+
// xctestrun's EnvironmentVariables instead.
8892
env: { ...process.env, AGENT_DEVICE_RUNNER_PORT: String(input.port) },
8993
detached: true,
9094
signal: input.signal,

‎packages/platform-apple/src/runner/runner-session.ts‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,7 @@ import {
6060
writeRunnerLease,
6161
} from './runner-lease.ts';
6262
import { isIosRunnerDetachEnabled, tryAdoptRunnerSessionFromLease } from './runner-adoption.ts';
63+
import { buildRunnerSessionXctestrunSuffix } from './runner-artifact-env.ts';
6364
import {
6465
abortRunnerSessionsAndPrepProcesses,
6566
cleanupOwnedIosRunnerLease,
@@ -276,7 +277,11 @@ async function startRunnerSessionWithLease(
276277
await prepareXctestrunWithEnv(
277278
xctestrunArtifact.xctestrunPath,
278279
{ AGENT_DEVICE_RUNNER_PORT: String(port) },
279-
`session-${device.id}-${runnerOwnerToken()}-${port}`,
280+
buildRunnerSessionXctestrunSuffix({
281+
deviceId: device.id,
282+
ownerToken: runnerOwnerToken(),
283+
port,
284+
}),
280285
{ iosXctestEnvDir: options.iosXctestEnvDir },
281286
),
282287
));

‎src/daemon-client/__tests__/daemon-client-timeout-route.test.ts‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -154,6 +154,27 @@ test('socket timeout: pkill cleanup still runs for a declared non-Apple platform
154154
// design that skips cleanup based on the declared flag would fail this.
155155
const pkillCalls = mockRunCmdSync.mock.calls.filter(([cmd]) => cmd === 'pkill');
156156
assert.equal(pkillCalls.length, 3);
157+
158+
// The session-xctestrun pattern is pinned by bytes, not derived from the runner's writer module:
159+
// a client version in the field already pkills this exact string, and it must keep selecting
160+
// launches that older writers named, since it cannot know which version started a timed-out
161+
// launch. Deriving it would move this sweep off those names on any rename.
162+
const sessionPattern = pkillCalls
163+
.map(([, args]) => String(args?.[1]))
164+
.find((pattern) => pattern.includes('session'));
165+
assert.equal(sessionPattern, String.raw`xcodebuild .*AgentDeviceRunner\.env\.session-`);
166+
assert.equal(
167+
new RegExp(sessionPattern).test(
168+
'xcodebuild test-without-building -xctestrun /d/AgentDeviceRunner.env.session-SIM-1-owner-1-ff-8123.xctestrun',
169+
),
170+
true,
171+
);
172+
assert.equal(
173+
new RegExp(sessionPattern).test(
174+
'xcodebuild test-without-building -xctestrun /d/AgentDeviceRunner.env.session-SIM-1-8123.xctestrun',
175+
),
176+
true,
177+
);
157178
});
158179

159180
test('http timeout: pkill cleanup still runs for an undeclared platform (unknown-session case) that terminates nothing, and the hint stays platform-neutral', async () => {

‎src/daemon-client/daemon-client-timeout.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,10 @@ import {
1616

1717
const IOS_RUNNER_XCODEBUILD_KILL_PATTERNS = [
1818
'xcodebuild .*AgentDeviceRunnerUITests/RunnerTests/testCommand',
19+
// A client in the field already pkills these exact bytes. This sweep ships separately from the
20+
// runner and cannot know which version wrote a timed-out launch, so it never follows a rename:
21+
// it must keep matching the names older writers used. The literal stays pinned here rather than
22+
// derived from `runner-artifact-env.ts`, which builds only today's session name.
1923
String.raw`xcodebuild .*AgentDeviceRunner\.env\.session-`,
2024
String.raw`xcodebuild build-for-testing .*apple/runner/AgentDeviceRunner/AgentDeviceRunner\.xcodeproj`,
2125
];

0 commit comments

Comments
 (0)