Skip to content

Commit 957bb81

Browse files
committed
docs(ios): document the xctest_device_set_cleanup_armed refusal for scoped simulator sets
Refs #2935
1 parent 44f7f70 commit 957bb81

3 files changed

Lines changed: 5 additions & 2 deletions

File tree

‎src/commands/schema/cli-help.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -690,7 +690,7 @@ iOS physical-device prerequisites:
690690
If Xcode cannot choose a profile, set AGENT_DEVICE_IOS_PROVISIONING_PROFILE to the profile name/specifier, not a file path.
691691
AGENT_DEVICE_IOS_SIGNING_IDENTITY is optional; omit it unless xcodebuild asks for a specific identity.
692692
The profile/team must allow AGENT_DEVICE_IOS_BUNDLE_ID and <id>.uitests.
693-
A runner startup failure names its class in error details.reason rather than only in prose: signing_no_development_team, signing_provisioning_profile_missing, bundle_identifier_already_registered, signing_unspecified, devtools_security_developer_mode_disabled (the Mac's DevToolsSecurity setting, which says nothing about the device's Developer Mode toggle), device_developer_mode_disabled (read from an iPhone's own report before the runner builds, and the only device state that stops a run up front), device_developer_disk_image_unavailable (also read from the device, and published on a startup failure that named no cause of its own, since iOS 17+ mounts the developer disk image on demand during build and launch rather than gating the build), or build_failed_unclassified when nothing proved a cause. The two device reasons are never inferred from tool output or from each other. Branch on details.reason and follow hint; the message is for humans.
693+
A runner startup failure names its class in error details.reason rather than only in prose: signing_no_development_team, signing_provisioning_profile_missing, bundle_identifier_already_registered, signing_unspecified, devtools_security_developer_mode_disabled (the Mac's DevToolsSecurity setting, which says nothing about the device's Developer Mode toggle), xctest_device_set_cleanup_armed (a simulator in a --ios-simulator-device-set set, refused before the runner builds or launches; see Runner and daemon lifecycle), device_developer_mode_disabled (read from an iPhone's own report before the runner builds, and the only device state that stops a run up front), device_developer_disk_image_unavailable (also read from the device, and published on a startup failure that named no cause of its own, since iOS 17+ mounts the developer disk image on demand during build and launch rather than gating the build), or build_failed_unclassified when nothing proved a cause. The two device reasons are never inferred from tool output or from each other. Branch on details.reason and follow hint; the message is for humans.
694694
First-run XCTest setup/build can take longer than normal commands; keep the device connected and use --debug to inspect signing/build diagnostics if setup times out.
695695
696696
Android physical-device prerequisites:
@@ -701,6 +701,7 @@ Runner and daemon lifecycle (applies to simulators too):
701701
open without --relaunch is idempotent-foreground for an already-running app (it brings the process forward; it does not restart it). open --relaunch restarts the app; on iOS simulators this collapses to one simctl launch --terminate-running-process call instead of a separate terminate-then-launch.
702702
No runner read launches a session app that is not running: snapshot, wait, is, get, a reading find, and an interaction's leading reads (a gesture's viewport read, the capture that resolves a selector click/fill) answer the retriable APP_NOT_RUNNING instead of bare-launching over a launch SpringBoard still holds behind its deep-link confirmation. Only open, activate, and a command that mutates without a leading read bring a stopped app up.
703703
close keeps a healthy iOS simulator XCTest runner warm by default so the next open on that device skips the runner build, unless --shutdown was requested, the session was recording, the session held a device lease, or the device used a scoped (non-default) simulator set. A retained runner auto-stops after an idle window (default 5 minutes); set AGENT_DEVICE_IOS_RUNNER_IDLE_STOP_MS to override, or 0 to disable idle stop and retain until daemon exit.
704+
With --ios-simulator-device-set, runner-backed commands refuse with COMMAND_FAILED and reason xctest_device_set_cleanup_armed when the selected Xcode does not match the installed CoreSimulator or CoreDevice framework, because that Xcode's simctl and devicectl shims run xcodebuild -runFirstLaunch, which deletes every device in ~/Library/Developer/XCTestDevices, and the runner points that path at the scoped set; details.xcrunShims names each expected and installed version. A scoped set is not protected from a first-launch cleanup that starts outside agent-device (a newly opened Xcode, a manual xcodebuild -runFirstLaunch) while a runner session holds that redirect.
704705
Each AGENT_DEVICE_STATE_DIR runs its own daemon. It self-exits after an idle window (default 5 minutes, matching the runner idle-stop default) once it has no open sessions, no in-flight requests, and no active recording; set AGENT_DEVICE_DAEMON_IDLE_TIMEOUT_MS to override, or 0 to disable idle reap.
705706
A stale iOS runner lease — its owner process dead, or its AGENT_DEVICE_STATE_DIR deleted — is reclaimed automatically instead of failing with "is already owned by another agent-device daemon". A live owner's runner is also reclaimed when the requesting daemon holds the host-global device claim for that device: claims are exclusive, so holding one proves the runner's owner released the device and merely kept the runner warm. The error remains only for owners outside claim arbitration (a pre-claims build, or daemons pointed at different claim stores).
706707

‎website/docs/docs/commands.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -204,6 +204,8 @@ agent-device devices --platform android --android-device-allowlist emulator-5554
204204
```
205205

206206
- `--ios-simulator-device-set <path>` constrains simulator discovery and simulator command execution via `xcrun simctl --set <path> ...`.
207+
- Runner-backed commands on a scoped set fail with `COMMAND_FAILED` and `details.reason: "xctest_device_set_cleanup_armed"` when the selected Xcode does not match the installed CoreSimulator or CoreDevice framework: that Xcode's `simctl` and `devicectl` shims then run `xcodebuild -runFirstLaunch`, which deletes every device in `~/Library/Developer/XCTestDevices`, where the runner points the scoped set. Select the matching Xcode with `xcode-select -s` or `DEVELOPER_DIR`; `details.xcrunShims` names each expected and installed version.
208+
- A scoped set is not protected from a first-launch cleanup that starts outside agent-device (opening a newly installed Xcode, or running `xcodebuild -runFirstLaunch` by hand) while a runner session holds that redirect.
207209
- `--android-device-allowlist <serials>` constrains Android discovery/selection to comma or space separated serials.
208210
- Scope is applied before selectors (`--device`, `--udid`, `--serial`), so out-of-scope selectors fail with `DEVICE_NOT_FOUND`.
209211
- With iOS simulator-set scope enabled, iOS physical devices are not enumerated.

‎website/docs/docs/installation.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -108,7 +108,7 @@ vega device list
108108
- `AGENT_DEVICE_IOS_PROVISIONING_PROFILE`
109109
- `AGENT_DEVICE_IOS_BUNDLE_ID` (optional runner bundle-id base override)
110110
- Free Apple Developer (Personal Team) accounts can fail with "bundle identifier is not available" for generic IDs; set `AGENT_DEVICE_IOS_BUNDLE_ID` to a unique reverse-DNS value (for example `com.yourname.agentdevice.runner`).
111-
- A runner startup failure is typed, not prose: `error.details.reason` is one of `signing_no_development_team`, `signing_provisioning_profile_missing`, `bundle_identifier_already_registered`, `signing_unspecified`, `devtools_security_developer_mode_disabled` (the Mac's `DevToolsSecurity` setting, which says nothing about the device's Developer Mode toggle), `device_developer_mode_disabled`, `device_developer_disk_image_unavailable`, or `build_failed_unclassified` when nothing proved a cause. Branch on `details.reason` and follow `hint`; the code stays `COMMAND_FAILED` for every reason.
111+
- A runner startup failure is typed, not prose: `error.details.reason` is one of `signing_no_development_team`, `signing_provisioning_profile_missing`, `bundle_identifier_already_registered`, `signing_unspecified`, `devtools_security_developer_mode_disabled` (the Mac's `DevToolsSecurity` setting, which says nothing about the device's Developer Mode toggle), `xctest_device_set_cleanup_armed` (a simulator in an `--ios-simulator-device-set` set whose selected Xcode does not match the installed CoreSimulator or CoreDevice framework), `device_developer_mode_disabled`, `device_developer_disk_image_unavailable`, or `build_failed_unclassified` when nothing proved a cause. Branch on `details.reason` and follow `hint`; the code stays `COMMAND_FAILED` for every reason.
112112
- The two `device_*` reasons come from the iPhone itself, read over `xcrun devicectl device info details` before the runner builds: `developerModeStatus` for the Settings toggle and `ddiServicesAvailable` for the developer disk image. They are reported apart on purpose. A phone with Developer Mode off cannot serve its disk image either, so it gets the toggle reason; a phone with the toggle on and only the image down gets the disk-image reason, which is a device-support install that has not finished rather than a setting anyone turned off.
113113
- If device setup is slow, keep the device connected and inspect daemon diagnostics after retrying.
114114
- If daemon startup reports stale metadata, remove stale files and retry:

0 commit comments

Comments
 (0)