Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -16,14 +16,11 @@ import {
isMacOs,
matchesPlatformSelector,
publicPlatformString,
resolveAppleSimulatorSetPathForSelector,
resolveRequestAppleSimulatorSetPath,
type DeviceInfo,
type PlatformSelector,
} from '@agent-device/kernel/device';
import {
resolveAndroidSerialAllowlist,
resolveIosSimulatorDeviceSetPath,
} from '@agent-device/kernel/device-isolation';
import { resolveAndroidSerialAllowlist } from '@agent-device/kernel/device-isolation';
import {
deviceClaimOwnerCannotRelease,
inspectDeviceClaims,
Expand Down Expand Up @@ -215,8 +212,8 @@ function inventoryIosSimulatorSetPath(
platform: PlatformSelector | undefined,
target: DeviceInfo['target'],
) {
return resolveAppleSimulatorSetPathForSelector({
simulatorSetPath: resolveIosSimulatorDeviceSetPath(configuredPath),
return resolveRequestAppleSimulatorSetPath({
requestedSetPath: configuredPath,
platform,
target,
});
Expand Down
66 changes: 65 additions & 1 deletion packages/device-selection/src/__tests__/dispatch-resolve.test.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
import { beforeEach, test, vi } from 'vitest';
import { afterEach, beforeEach, test, vi } from 'vitest';
import assert from 'node:assert/strict';

const mockFindIosSimulatorInstalledApp = vi.fn();
Expand Down Expand Up @@ -96,6 +96,10 @@ async function resolveTargetDevice(
);
}

afterEach(() => {
vi.unstubAllEnvs();
});

beforeEach(() => {
mockFindIosSimulatorInstalledApp.mockReset();
mockFindIosSimulatorInstalledApp.mockResolvedValue(undefined);
Expand Down Expand Up @@ -595,6 +599,66 @@ test('resolveTargetDevice keeps simulator-set scope separate from the macOS host
assert.equal(requests[1]?.iosSimulatorSetPath, undefined);
});

test('resolveTargetDevice discovers simulators in the daemon operator set when the request names none', async () => {
vi.stubEnv('AGENT_DEVICE_IOS_SIMULATOR_DEVICE_SET', '/tmp/operator-set');
const requests: DeviceInventoryRequest[] = [];
await withTestDeviceInventory(
{
local: async (request) => {
requests.push(request);
return [simulator];
},
},
async () => {
const result = await resolveTargetDeviceInContext({ platform: 'ios' });
assert.equal(result.id, simulator.id);
},
);

assert.equal(requests[0]?.iosSimulatorSetPath, '/tmp/operator-set');
});

test('resolveTargetDevice refuses a request naming another set than the daemon operator set before discovery', async () => {
vi.stubEnv('AGENT_DEVICE_IOS_SIMULATOR_DEVICE_SET', '/tmp/operator-set');

const err = await resolveTargetDevice({
platform: 'ios',
iosSimulatorDeviceSet: '/tmp/other-set',
}).catch((error) => error);

assert.ok(err instanceof AppError);
assert.equal(err.code, 'INVALID_ARGS');
assert.equal(err.details?.reason, 'ios_simulator_device_set_outside_daemon_set');
assert.equal(mockListAppleDevices.mock.calls.length, 0);
});

test('resolveTargetDevice serves macOS and Android requests naming another set on a daemon scoped to an operator set', async () => {
vi.stubEnv('AGENT_DEVICE_IOS_SIMULATOR_DEVICE_SET', '/tmp/operator-set');
const requests: DeviceInventoryRequest[] = [];
await withTestDeviceInventory(
{
local: async (request) => {
requests.push(request);
return request.platform === 'macos' ? [macDesktop] : [androidEmulator];
},
},
async () => {
const macResult = await resolveTargetDeviceInContext({
platform: 'macos',
iosSimulatorDeviceSet: '/tmp/other-set',
});
const androidResult = await resolveTargetDeviceInContext({
platform: 'android',
iosSimulatorDeviceSet: '/tmp/other-set',
});
assert.equal(macResult.id, macDesktop.id);
assert.equal(androidResult.id, androidEmulator.id);
},
);

assert.equal(requests[0]?.iosSimulatorSetPath, undefined);
});

async function expectDeviceNotFound(action: () => Promise<unknown>): Promise<void> {
const err = await action().catch((error) => error);

Expand Down
11 changes: 4 additions & 7 deletions packages/device-selection/src/dispatch-resolve.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,16 +3,13 @@ import type { DeviceInventoryRequest } from '@agent-device/contracts/device';
import {
hasExplicitDeviceIdentitySelector,
isApplePlatform,
resolveAppleSimulatorSetPathForSelector,
resolveRequestAppleSimulatorSetPath,
type DeviceInfo,
type DeviceTarget,
} from '@agent-device/kernel/device';
import { AppError } from '@agent-device/kernel/errors';
import { AsyncLocalStorage } from 'node:async_hooks';
import {
resolveAndroidSerialAllowlist,
resolveIosSimulatorDeviceSetPath,
} from '@agent-device/kernel/device-isolation';
import { resolveAndroidSerialAllowlist } from '@agent-device/kernel/device-isolation';
import { withDiagnosticTimer } from '@agent-device/host-kit/diagnostics';
import {
listLocalDeviceInventory,
Expand Down Expand Up @@ -209,8 +206,8 @@ export function buildDeviceInventoryRequestFromFlags(
'Device target selector requires --platform. Use --platform ios|macos|android|vega|linux|apple with --target mobile|tv|desktop.',
);
}
const iosSimulatorSetPath = resolveAppleSimulatorSetPathForSelector({
simulatorSetPath: resolveIosSimulatorDeviceSetPath(flags.iosSimulatorDeviceSet),
const iosSimulatorSetPath = resolveRequestAppleSimulatorSetPath({
requestedSetPath: flags.iosSimulatorDeviceSet,
platform,
target: flags.target,
});
Expand Down
34 changes: 27 additions & 7 deletions packages/kernel/src/device.ts
Original file line number Diff line number Diff line change
Expand Up @@ -321,17 +321,37 @@ function resolveRunnerPlatformNameForAppleOs(
}
}

export function resolveAppleSimulatorSetPathForSelector(params: {
simulatorSetPath?: string;
const DAEMON_IOS_SIMULATOR_DEVICE_SET_ENV = 'AGENT_DEVICE_IOS_SIMULATOR_DEVICE_SET';

/**
* The simulator set a daemon request's device inventory reaches. macOS and desktop selectors
* never reach a simulator set. For selectors that can reach simulators,
* `AGENT_DEVICE_IOS_SIMULATOR_DEVICE_SET` in the daemon's environment is the operator's set: it
* applies when the request names no set, and a request naming another set is refused.
*/
export function resolveRequestAppleSimulatorSetPath(params: {
requestedSetPath?: string;
platform?: PlatformSelector;
target?: DeviceTarget;
env?: NodeJS.ProcessEnv;
}): string | undefined {
const { simulatorSetPath, platform, target } = params;
if (!simulatorSetPath) return undefined;
if (platform === 'macos' || target === 'desktop') {
return undefined;
const { platform, target, env = process.env } = params;
if (platform === 'macos' || target === 'desktop') return undefined;
const requested = params.requestedSetPath?.trim() || undefined;
if (!supportsAppleSimulatorSelection(platform)) return requested;
const operatorSet = env[DAEMON_IOS_SIMULATOR_DEVICE_SET_ENV]?.trim() || undefined;
if (!operatorSet) return requested;
if (requested && requested !== operatorSet) {
throw new AppError(
'INVALID_ARGS',
`This daemon only reaches iOS simulators in the set "${operatorSet}" (${DAEMON_IOS_SIMULATOR_DEVICE_SET_ENV}), but the request named --ios-simulator-device-set "${requested}".`,
{
reason: 'ios_simulator_device_set_outside_daemon_set',
hint: `Omit --ios-simulator-device-set, or pass exactly "${operatorSet}".`,
},
);
}
return simulatorSetPath;
return operatorSet;
}

export function sortAppleDevicesForSelection<TDevice extends DeviceInfo>(
Expand Down
Original file line number Diff line number Diff line change
@@ -1,14 +1,11 @@
import type { CommandFlags } from '@agent-device/contracts/command';
import type { DeviceInventoryRequest } from '@agent-device/contracts/device';
import { listDeviceInventory } from '@agent-device/device-selection/device-inventory-context';
import {
resolveAndroidSerialAllowlist,
resolveIosSimulatorDeviceSetPath,
} from '@agent-device/kernel/device-isolation';
import { resolveAndroidSerialAllowlist } from '@agent-device/kernel/device-isolation';
import {
isMobilePlatform,
matchesPlatformSelector,
resolveAppleSimulatorSetPathForSelector,
resolveRequestAppleSimulatorSetPath,
type DeviceInfo,
} from '@agent-device/kernel/device';
import { AppError } from '@agent-device/kernel/errors';
Expand Down Expand Up @@ -99,8 +96,8 @@ function buildReplayTestShardInventoryRequest(
return {
platform: flags?.platform,
target: flags?.target,
iosSimulatorSetPath: resolveAppleSimulatorSetPathForSelector({
simulatorSetPath: resolveIosSimulatorDeviceSetPath(flags?.iosSimulatorDeviceSet),
iosSimulatorSetPath: resolveRequestAppleSimulatorSetPath({
requestedSetPath: flags?.iosSimulatorDeviceSet,
platform: flags?.platform,
target: flags?.target,
}),
Expand Down
93 changes: 79 additions & 14 deletions src/core/__tests__/device.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ import {
platformSelectorsConflict,
PLATFORMS,
resolveApplePlatformName,
resolveAppleSimulatorSetPathForSelector,
resolveRequestAppleSimulatorSetPath,
resolveDevice,
runnerSynthesizesTap,
} from '@agent-device/kernel/device';
Expand Down Expand Up @@ -186,29 +186,94 @@ test('resolveApplePlatformName falls back to target inference for legacy records
assert.equal(resolveApplePlatformName('macos', undefined), 'macOS');
});

test('resolveAppleSimulatorSetPathForSelector ignores simulator scoping for desktop selectors', () => {
const NO_OPERATOR_SET: NodeJS.ProcessEnv = {};
const OPERATOR_SET_ENV: NodeJS.ProcessEnv = {
AGENT_DEVICE_IOS_SIMULATOR_DEVICE_SET: ' /tmp/operator-set ',
};

test('resolveRequestAppleSimulatorSetPath ignores simulator scoping for desktop selectors', () => {
for (const env of [NO_OPERATOR_SET, OPERATOR_SET_ENV]) {
assert.equal(
resolveRequestAppleSimulatorSetPath({
requestedSetPath: '/tmp/other-set',
platform: 'macos',
env,
}),
undefined,
);
assert.equal(
resolveRequestAppleSimulatorSetPath({
requestedSetPath: '/tmp/other-set',
platform: 'apple',
target: 'desktop',
env,
}),
undefined,
);
}
});

test('resolveRequestAppleSimulatorSetPath without an operator set reaches the requested set or the default set', () => {
assert.equal(
resolveAppleSimulatorSetPathForSelector({
simulatorSetPath: '/tmp/scoped',
platform: 'macos',
resolveRequestAppleSimulatorSetPath({
requestedSetPath: ' /tmp/scoped ',
platform: 'ios',
target: 'mobile',
env: NO_OPERATOR_SET,
}),
'/tmp/scoped',
);
assert.equal(
resolveRequestAppleSimulatorSetPath({ platform: 'ios', env: NO_OPERATOR_SET }),
undefined,
);
});

test('resolveRequestAppleSimulatorSetPath applies the operator set to a simulator request that names none', () => {
assert.equal(
resolveRequestAppleSimulatorSetPath({ platform: 'ios', env: OPERATOR_SET_ENV }),
'/tmp/operator-set',
);
assert.equal(
resolveRequestAppleSimulatorSetPath({ requestedSetPath: ' ', env: OPERATOR_SET_ENV }),
'/tmp/operator-set',
);
assert.equal(
resolveAppleSimulatorSetPathForSelector({
simulatorSetPath: '/tmp/scoped',
resolveRequestAppleSimulatorSetPath({
requestedSetPath: '/tmp/operator-set',
platform: 'apple',
target: 'desktop',
target: 'tv',
env: OPERATOR_SET_ENV,
}),
undefined,
'/tmp/operator-set',
);
});

test('resolveRequestAppleSimulatorSetPath refuses a simulator request naming another set than the operator set', () => {
for (const requestedSetPath of ['/tmp/other-set', '/tmp/operator-set/']) {
assert.throws(
() =>
resolveRequestAppleSimulatorSetPath({
requestedSetPath,
platform: 'ios',
env: OPERATOR_SET_ENV,
}),
(error: unknown) =>
error instanceof AppError &&
error.code === 'INVALID_ARGS' &&
error.details?.reason === 'ios_simulator_device_set_outside_daemon_set',
);
}
});

test('resolveRequestAppleSimulatorSetPath leaves the operator set out of platforms without simulator sets', () => {
assert.equal(
resolveAppleSimulatorSetPathForSelector({
simulatorSetPath: '/tmp/scoped',
platform: 'ios',
target: 'mobile',
resolveRequestAppleSimulatorSetPath({
requestedSetPath: '/tmp/other-set',
platform: 'android',
env: OPERATOR_SET_ENV,
}),
'/tmp/scoped',
'/tmp/other-set',
);
});

Expand Down
1 change: 1 addition & 0 deletions website/docs/docs/commands.md
Original file line number Diff line number Diff line change
Expand Up @@ -197,6 +197,7 @@ agent-device devices --platform android --android-device-allowlist emulator-5554
- If the selected Xcode can't resolve a scoped simulator for the Apple runner, the runner start fails with `details.reason: "simulator_set_destination_not_found"`, naming the set and, when known, the Xcode version.
- `--android-device-allowlist <serials>` limits Android discovery and selection to comma- or space-separated serials.
- Set the same scopes with the `iosSimulatorDeviceSet` and `androidDeviceAllowlist` config keys, or `AGENT_DEVICE_ANDROID_DEVICE_ALLOWLIST`. CLI flags override environment values, except under a `strip` session lock, which ignores conflicting per-call selectors.
- Start the daemon with `AGENT_DEVICE_IOS_SIMULATOR_DEVICE_SET=<path>` to scope every iOS simulator request to one simulator set. A request without `--ios-simulator-device-set` uses that set, so iOS physical devices are not listed on that daemon. A request naming a different path string, including the same path with a trailing slash, fails with `INVALID_ARGS` and `details.reason: "ios_simulator_device_set_outside_daemon_set"`. macOS and other non-iOS requests ignore the set, and the host Mac stays listed. A daemon that the CLI starts inherits the CLI's environment, so later CLI calls with a different value still use the first value until the daemon restarts.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3: The “other non-iOS requests ignore the set” clause is incorrect for --platform apple --target tv: Apple simulator requests use the daemon set, while only macOS desktop requests bypass it. Update this wording in both documentation pages.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At website/docs/docs/commands.md, line 200:

<comment>The “other non-iOS requests ignore the set” clause is incorrect for `--platform apple --target tv`: Apple simulator requests use the daemon set, while only macOS desktop requests bypass it. Update this wording in both documentation pages.</comment>

<file context>
@@ -197,6 +197,7 @@ agent-device devices --platform android --android-device-allowlist emulator-5554
 - If the selected Xcode can't resolve a scoped simulator for the Apple runner, the runner start fails with `details.reason: "simulator_set_destination_not_found"`, naming the set and, when known, the Xcode version.
 - `--android-device-allowlist <serials>` limits Android discovery and selection to comma- or space-separated serials.
 - Set the same scopes with the `iosSimulatorDeviceSet` and `androidDeviceAllowlist` config keys, or `AGENT_DEVICE_ANDROID_DEVICE_ALLOWLIST`. CLI flags override environment values, except under a `strip` session lock, which ignores conflicting per-call selectors.
+- Start the daemon with `AGENT_DEVICE_IOS_SIMULATOR_DEVICE_SET=<path>` to scope every iOS simulator request to one simulator set. A request without `--ios-simulator-device-set` uses that set, so iOS physical devices are not listed on that daemon. A request naming a different path string, including the same path with a trailing slash, fails with `INVALID_ARGS` and `details.reason: "ios_simulator_device_set_outside_daemon_set"`. macOS and other non-iOS requests ignore the set, and the host Mac stays listed. A daemon that the CLI starts inherits the CLI's environment, so later CLI calls with a different value still use the first value until the daemon restarts.
 - Scope applies before `--device`, `--udid`, and `--serial`, so an out-of-scope selector fails with `DEVICE_NOT_FOUND`.
 - On macOS, daemon startup removes any symlink at `~/Library/Developer/XCTestDevices`, including one you made yourself (for example to move it to another volume), and restores `XCTestDevices.agent-device-backup` when it exists. A symlinked `XCTestDevices` is not supported. Only the link is removed, never the directory it points to; `daemon.log` records each step and any failed restore, which doesn't stop the daemon.
</file context>
Suggested change
- Start the daemon with `AGENT_DEVICE_IOS_SIMULATOR_DEVICE_SET=<path>` to scope every iOS simulator request to one simulator set. A request without `--ios-simulator-device-set` uses that set, so iOS physical devices are not listed on that daemon. A request naming a different path string, including the same path with a trailing slash, fails with `INVALID_ARGS` and `details.reason: "ios_simulator_device_set_outside_daemon_set"`. macOS and other non-iOS requests ignore the set, and the host Mac stays listed. A daemon that the CLI starts inherits the CLI's environment, so later CLI calls with a different value still use the first value until the daemon restarts.
- Start the daemon with `AGENT_DEVICE_IOS_SIMULATOR_DEVICE_SET=<path>` to scope every Apple simulator request to one simulator set. A request without `--ios-simulator-device-set` uses that set, so iOS physical devices are not listed on that daemon. A request naming a different path string, including the same path with a trailing slash, fails with `INVALID_ARGS` and `details.reason: "ios_simulator_device_set_outside_daemon_set"`. macOS requests and other non-Apple requests ignore the set, and the host Mac stays listed. A daemon that the CLI starts inherits the CLI's environment, so later CLI calls with a different value still use the first value until the daemon restarts.

- Scope applies before `--device`, `--udid`, and `--serial`, so an out-of-scope selector fails with `DEVICE_NOT_FOUND`.
- On macOS, daemon startup removes any symlink at `~/Library/Developer/XCTestDevices`, including one you made yourself (for example to move it to another volume), and restores `XCTestDevices.agent-device-backup` when it exists. A symlinked `XCTestDevices` is not supported. Only the link is removed, never the directory it points to; `daemon.log` records each step and any failed restore, which doesn't stop the daemon.

Expand Down
2 changes: 1 addition & 1 deletion website/docs/docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -122,7 +122,7 @@ Only the variables below, and those documented on command pages, are supported.
| Category | Env vars | Decision |
| --- | --- | --- |
| CLI defaults and config | `AGENT_DEVICE_HOME`, `AGENT_DEVICE_CONFIG`, `AGENT_DEVICE_SESSION`, `AGENT_DEVICE_PLATFORM`, `AGENT_DEVICE_SCREENSHOT_SCALE`, `AGENT_DEVICE_SESSION_LOCK`, `AGENT_DEVICE_DAEMON_BASE_URL`, `AGENT_DEVICE_DAEMON_AUTH_TOKEN`, `AGENT_DEVICE_CLOUD_BASE_URL` | Public |
| Device scoping | `AGENT_DEVICE_ANDROID_DEVICE_ALLOWLIST` | Public |
| Device scoping | `AGENT_DEVICE_ANDROID_DEVICE_ALLOWLIST`, `AGENT_DEVICE_IOS_SIMULATOR_DEVICE_SET` | Public. `AGENT_DEVICE_IOS_SIMULATOR_DEVICE_SET` is read by the daemon: every iOS simulator request that names no `--ios-simulator-device-set` uses that set, so iOS physical devices are not listed, and a request naming a different path string fails with `INVALID_ARGS` (`details.reason: "ios_simulator_device_set_outside_daemon_set"`). macOS and non-iOS requests ignore it. A daemon started by the CLI inherits the CLI's value; restart the daemon after changing it. |
| Android test IME | `AGENT_DEVICE_TEST_IME` | Public. Same setting as `--test-ime` / `--no-test-ime` on `open`, `test`, and `replay`; see known limitations. |
| Local daemon storage | `AGENT_DEVICE_STATE_DIR` | Public |
| Metro and install helpers | `AGENT_DEVICE_METRO_BEARER_TOKEN`, `AGENT_DEVICE_BUNDLETOOL_JAR` | Public |
Expand Down
Loading