Skip to content

Commit 0a4b925

Browse files
committed
test(provider-scenarios): admit open at the provider scenario seam and document the refusal
The scenario provider module resolved an interactor and opened, skipping the admission every production provider runtime runs first. Enforce it there, so a scenario cannot pass an open that production would refuse before the lifecycle touches the device. The new scenario proves the refusal on a provider-owned iOS simulator: it names the typed reason and the device, and the fake device records no open and no close. The reason was also undocumented. `open --help` and the command reference now name it, and the debugging guide says the session must own the simulator locally.
1 parent 37dc3c4 commit 0a4b925

5 files changed

Lines changed: 35 additions & 3 deletions

File tree

‎src/commands/management/app.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -199,7 +199,7 @@ export const openCommandFacet = defineCommandFacet({
199199
text: {
200200
summary: 'Open an app, deep link or URL, save replays',
201201
cliDetail:
202-
'Use --platform to bind URL/deep-link opens to the target platform. For iOS simulator initial stdout/stderr, put --launch-console <path> on this open command, for example agent-device open "Agent Device Tester" --platform ios --launch-console artifacts/launch-console.log. Expo Go/dev-client shells accept host + URL, for example agent-device open "Expo Go" exp://127.0.0.1:8081 --platform ios. macOS also supports --surface app|frontmost-app|desktop|menubar. --metro-host/--metro-port/--bundle-url choose the app\'s Metro server and save that address for later metro reload calls in the same session. A fresh open without Metro hints clears an older same-name binding; close also clears it. --launch-url supplies the app\'s launch URL; it does not select the reload server. On an iOS simulator without --launch-url, open connects a detected Expo development client through its expo-development-client URL. The app must declare a single exp+<slug> scheme that no other installed app owns. If detection is inconclusive, the app opens normally. Bare React Native apps receive their server settings before launch. On an iOS simulator, when --launch-url raises an "Open in <App>?" prompt that keeps open from seeing the app, open accepts it if the URL scheme belongs to the session app (data.launchConfirmation: "accepted"); if the scheme belongs to another installed app, the prompt stays on screen and open fails with details.reason launch_confirmation_foreign_app; if the scheme owner cannot be resolved because no single installed app owns it or the lookup failed, the prompt stays on screen and open returns with data.launchConfirmation: "unanswered", launchConfirmationReason url-owner-unresolved, and a warning; a prompt that is seen but not recognized is reported the same way with launchConfirmationReason alert-unrecognized and its own warning; in both cases inspect the warning and answer with alert get then alert accept; when agent-device cannot read whether a prompt is up at all (the alert read, the accept, or the runner itself failed, including after a re-hand of the URL), open stays green, reports no launchConfirmation plus data.launchConfirmationProbeFailure naming the failed step (alert-read, alert-accept, or runner), and appends a warning that says to check with alert get. The prompt is read whenever open cannot see the app afterwards, including on a slow host where the app\'s target discovery fails on its own deadline. When an accept leaves the app provably not running, open hands the same URL over once more and reads again; still not running, it fails with details.reason launch_confirmation_unanswered. A recognized prompt still visible after a failed accept also fails with this reason, even if the app is running behind it; answer it with alert accept or alert dismiss. A simulator openurl that CoreSimulator never answers fails within 20s with details.reason ios-simulator-openurl-timeout. Only the English prompt title with Cancel and Open buttons is recognized, so on a Simulator set to another language the prompt stays on screen. A prompt that appears after open has already seen the app is not answered; use alert accept. A device another session is holding refuses at once; add --wait <ms> to block up to that budget for it and only then fail with DEVICE_IN_USE naming the owning session.',
202+
'Use --platform to bind URL/deep-link opens to the target platform. For iOS simulator initial stdout/stderr, put --launch-console <path> on this open command, for example agent-device open "Agent Device Tester" --platform ios --launch-console artifacts/launch-console.log. --launch-console needs a session owner that runs the simulator locally, so open refuses it before it touches the device when any other owner holds the session, such as a provider-owned cloud device or another host; that refusal is UNSUPPORTED_OPERATION with details.reason launch-console-owner-unadmitted and it names the device. Expo Go/dev-client shells accept host + URL, for example agent-device open "Expo Go" exp://127.0.0.1:8081 --platform ios. macOS also supports --surface app|frontmost-app|desktop|menubar. --metro-host/--metro-port/--bundle-url choose the app\'s Metro server and save that address for later metro reload calls in the same session. A fresh open without Metro hints clears an older same-name binding; close also clears it. --launch-url supplies the app\'s launch URL; it does not select the reload server. On an iOS simulator without --launch-url, open connects a detected Expo development client through its expo-development-client URL. The app must declare a single exp+<slug> scheme that no other installed app owns. If detection is inconclusive, the app opens normally. Bare React Native apps receive their server settings before launch. On an iOS simulator, when --launch-url raises an "Open in <App>?" prompt that keeps open from seeing the app, open accepts it if the URL scheme belongs to the session app (data.launchConfirmation: "accepted"); if the scheme belongs to another installed app, the prompt stays on screen and open fails with details.reason launch_confirmation_foreign_app; if the scheme owner cannot be resolved because no single installed app owns it or the lookup failed, the prompt stays on screen and open returns with data.launchConfirmation: "unanswered", launchConfirmationReason url-owner-unresolved, and a warning; a prompt that is seen but not recognized is reported the same way with launchConfirmationReason alert-unrecognized and its own warning; in both cases inspect the warning and answer with alert get then alert accept; when agent-device cannot read whether a prompt is up at all (the alert read, the accept, or the runner itself failed, including after a re-hand of the URL), open stays green, reports no launchConfirmation plus data.launchConfirmationProbeFailure naming the failed step (alert-read, alert-accept, or runner), and appends a warning that says to check with alert get. The prompt is read whenever open cannot see the app afterwards, including on a slow host where the app\'s target discovery fails on its own deadline. When an accept leaves the app provably not running, open hands the same URL over once more and reads again; still not running, it fails with details.reason launch_confirmation_unanswered. A recognized prompt still visible after a failed accept also fails with this reason, even if the app is running behind it; answer it with alert accept or alert dismiss. A simulator openurl that CoreSimulator never answers fails within 20s with details.reason ios-simulator-openurl-timeout. Only the English prompt title with Cancel and Open buttons is recognized, so on a Simulator set to another language the prompt stays on screen. A prompt that appears after open has already seen the app is not answered; use alert accept. A device another session is holding refuses at once; add --wait <ms> to block up to that budget for it and only then fail with DEVICE_IN_USE naming the owning session.',
203203
mcpDetail:
204204
"metroHost, metroPort, and bundleUrl choose the app's Metro server and save its address for later reloads. launchUrl selects the app's launch URL and does not select the reload server. A fresh open without Metro hints clears an older same-name binding; close also clears it.",
205205
},

‎test/integration/provider-scenarios/provider-device-runtime.fixtures.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ import {
1818
type ApplicationLifecycleRuntimeOperations,
1919
} from '@agent-device/contracts/application-lifecycle-runtime';
2020
import {
21+
assertOpenAdmitted,
2122
bindProviderApplicationLifecycleInteractor,
2223
invokeApplicationClose,
2324
invokeApplicationOpen,
@@ -208,6 +209,9 @@ function providerScenarioApplicationLifecycle(
208209
}),
209210
prepareApplicationOpen: async () => undefined,
210211
openApplication: async (input) => {
212+
// The same admission the production provider runtimes run first, so a launch-only option is
213+
// refused here before any close or open traffic reaches the fake device.
214+
assertOpenAdmitted(binding, input.execution, input.positionals);
211215
if (input.relaunch && input.target) {
212216
await invokeApplicationClose({
213217
device,

‎test/integration/provider-scenarios/provider-device-runtime.test.ts‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -89,6 +89,34 @@ test('provider-owned iOS simulators relaunch without local CoreSimulator refresh
8989
);
9090
});
9191

92+
test('provider-owned open refuses --launch-console before it touches the device', async () => {
93+
await withProviderScenarioResource(
94+
async () => await createFakeProviderWorld('ios'),
95+
async ({ daemon, runtime }) => {
96+
const lease = await allocateIosFakeProviderLease(daemon);
97+
const flags = {
98+
...iosLeaseFlags(lease.leaseId),
99+
launchConsole: '/tmp/provider-scenario-launch-console.log',
100+
};
101+
const error = assertRpcError(
102+
await daemon.callCommand('open', ['com.example.demo'], flags, {
103+
meta: iosLeaseMeta(lease.leaseId),
104+
}),
105+
500,
106+
'UNSUPPORTED_OPERATION',
107+
/--launch-console is supported only for a local iOS simulator app launch/,
108+
);
109+
const details = error.details as Record<string, unknown>;
110+
assert.equal(details.reason, 'launch-console-owner-unadmitted');
111+
assert.equal(details.deviceId, runtime.deviceIdForLease(lease.leaseId));
112+
assert.deepEqual(
113+
runtime.calls.filter((call) => call.type === 'open' || call.type === 'close'),
114+
[],
115+
);
116+
},
117+
);
118+
});
119+
92120
test('provider lease allocation is refused when no registered runtime claims the provider', async () => {
93121
const daemon = await createProviderScenarioHarness({
94122
providerRuntimeIds: [FAKE_PROVIDER],

‎website/docs/docs/commands.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -98,7 +98,7 @@ Open apps and links:
9898
- `open [app|url] [url]` boots the selected device when needed and opens the target in a session. `open <url>` opens deep links on Android and iOS, and `open <app> <url>` opens a deep link in that app on iOS. See [Desktop targets](#desktop-targets) for macOS activation behavior.
9999
- On iOS devices, `http(s)://` URLs open in Safari when no app is active. Custom-scheme URLs need an active app in the session.
100100
- `open <app> --wait <ms>` waits up to that budget for a device another session holds, then fails with `DEVICE_IN_USE`. The wait extends the command's timeout, so you don't need a longer `--timeout`. A claim held by another workspace's daemon is not waited for; `open` returns its recovery command at once. Device-mutating commands like `install` and `reinstall` never wait either: a claim held by another session fails them at once, and when the caller sends a workspace, another workspace's claim under the same session name fails too. See [Sessions](/docs/sessions#wait-for-a-slow-or-busy-device).
101-
- `open <app> --launch-console <path>` captures launch-time stdout/stderr for iOS simulator app launches. It is not valid for URL opens or other targets.
101+
- `open <app> --launch-console <path>` captures launch-time stdout/stderr for iOS simulator app launches. It is not valid for URL opens or other targets. A session a provider or another host owns cannot read the simulator console, so `open` refuses the flag before it touches the device with `UNSUPPORTED_OPERATION` and `details.reason: "launch-console-owner-unadmitted"`.
102102
- `open --platform macos --surface app|frontmost-app|desktop|menubar` selects the macOS session surface; `app` is the default when you name an app. See [Desktop targets](#desktop-targets). `--save-script` records the surface so `replay` reopens it; with no surface given, replay opens an app session.
103103
- Android React Native: `open --relaunch` needs an installed package name. Install or reinstall the APK first; `open <apk|aab> --relaunch` is rejected. For Metro-backed JS changes, run `metro reload` before reaching for `open <app> --relaunch`.
104104
- Android (adb): an intent target such as `open settings` records the package that opened as `appBundleId`. `open settings --relaunch` stops and restarts that app. If the intent matches more than one activity, `--relaunch` fails.

‎website/docs/docs/debugging-profiling.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -148,7 +148,7 @@ On iOS simulators, `logs` scope by bundle id and the resolved app executable. Fo
148148
agent-device open MyApp --platform ios --relaunch --launch-console ./artifacts/app.console.log
149149
```
150150
151-
`--launch-console` is only for direct iOS simulator app launches, not URL opens.
151+
`--launch-console` is only for direct iOS simulator app launches, not URL opens. The session must own the simulator locally, so a provider-owned cloud device refuses the flag before the open reaches the device.
152152
153153
## Crash symbolication
154154

0 commit comments

Comments
 (0)