Skip to content

Commit e2c8b9b

Browse files
committed
fix(apple): read the launch confirmation only when the launched app itself is unreadable
The Simulator launch observation now reports probe-failed, with its typed failure, for an unresolvable target, an open bridge circuit, or a bridge failure that is not a launch transition. Only an app with no running process or an expired launch-transition window stays unobservable, so only those opens read the alert. An open that reads it records runner demand 'required'.
1 parent ffc1150 commit e2c8b9b

8 files changed

Lines changed: 173 additions & 81 deletions

File tree

‎packages/contracts/src/application-lifecycle-runtime.ts‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -140,8 +140,9 @@ export type OpenApplicationTiming = Readonly<{
140140
* or AX-server state that did not clear, a system surface over the app, a content verdict after
141141
* the capture's own re-captures, or the window ran out.
142142
* - `probe-failed`: the observation could not run (Android: the helper is not installed at the
143-
* current version, or adb or the accessibility service failed). `postOpenObservationFailure`
144-
* carries the typed failure.
143+
* current version, or adb or the accessibility service failed; iOS Simulator: the app's target
144+
* could not be resolved, the bridge circuit is open, or the bridge failed with a code that is not
145+
* a launch transition). `postOpenObservationFailure` carries the typed failure.
145146
* - `app-unidentified`: the open targeted an app, but the owner could not read which package it
146147
* launched, so nothing was observed.
147148
* - `not-eligible`: the device has no observation path.
@@ -153,7 +154,10 @@ export type PostOpenObservation =
153154
| 'app-unidentified'
154155
| 'not-eligible';
155156

156-
/** The typed failure of a `probe-failed` observation: the error code and its typed reason. */
157+
/**
158+
* The typed failure of a `probe-failed` observation: the error code and its typed reason. An iOS
159+
* Simulator bridge failure carries the bridge failure kind as `code` and its code as `reason`.
160+
*/
157161
export type PostOpenObservationFailure = Readonly<{
158162
code: string;
159163
reason?: string;

‎packages/platform-apple/src/lifecycle.test.ts‎

Lines changed: 41 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -608,7 +608,7 @@ test('a Simulator open lets the launched app become observable instead of sleepi
608608
});
609609
const awaitObservable = vi.fn(async () => {
610610
events.push('observe');
611-
return 'observable' as const;
611+
return { observation: 'observable' } as const;
612612
});
613613
const signal = new AbortController().signal;
614614
const lifecycle = bindAppleApplicationLifecycle({
@@ -638,7 +638,7 @@ test('a Simulator whose bridge cannot answer keeps the fixed settle', async () =
638638
host: { ...host, clock: { ...host.clock, sleep } } as unknown as PlatformRuntimeHost,
639639
device: simulator,
640640
signal: new AbortController().signal,
641-
observation: { awaitObservable: async () => 'unobservable' as const },
641+
observation: { awaitObservable: async () => ({ observation: 'unobservable' }) as const },
642642
});
643643

644644
const outcome = await lifecycle.openApplication({
@@ -653,7 +653,7 @@ test('a Simulator whose bridge cannot answer keeps the fixed settle', async () =
653653
test('a tvOS Simulator relaunch keeps the awaited prewarm and asks for no observation', async () => {
654654
const events: string[] = [];
655655
const { host, prewarmRunnerSession, notifyRunnerAppRelaunched } = simulatorHost({ events });
656-
const awaitObservable = vi.fn(async () => 'observable' as const);
656+
const awaitObservable = vi.fn(async () => ({ observation: 'observable' }) as const);
657657
const tvos = { ...simulator, appleOs: 'tvos', target: 'tv' } as const satisfies DeviceInfo;
658658
const lifecycle = bindAppleApplicationLifecycle({
659659
host,
@@ -676,13 +676,15 @@ test('a tvOS Simulator relaunch keeps the awaited prewarm and asks for no observ
676676
expect(notifyRunnerAppRelaunched).not.toHaveBeenCalled();
677677
});
678678

679+
const OBSERVABLE: LaunchObservation = { observation: 'observable' };
680+
679681
/**
680682
* A Simulator whose host AX bridge reports `observations` in turn after each settle, and whose
681683
* runner answers the alert read with `readAlert`.
682684
*/
683685
function launchUrlSimulator(
684686
readAlert: () => Promise<Record<string, unknown>>,
685-
observations: readonly LaunchObservation[] = ['observable'],
687+
observations: readonly LaunchObservation[] = [OBSERVABLE],
686688
) {
687689
const events: string[] = [];
688690
const pending = [...observations];
@@ -706,16 +708,17 @@ function launchUrlSimulator(
706708
signal: new AbortController().signal,
707709
observation: {
708710
awaitObservable: async () => {
709-
const observed = pending.length > 1 ? pending.shift() : pending[0];
710-
events.push(`observe ${observed}`);
711-
return observed ?? 'observable';
711+
const observed = (pending.length > 1 ? pending.shift() : pending[0]) ?? OBSERVABLE;
712+
events.push(`observe ${observed.observation}`);
713+
return observed;
712714
},
713715
},
714716
});
715717
return { lifecycle, events, interactor, releaseSpeculativeRunner, prewarmRunnerSession };
716718
}
717719

718720
const LAUNCH_URL = 'example://automation';
721+
const UNOBSERVABLE: LaunchObservation = { observation: 'unobservable' };
719722

720723
function launchUrlInput(): OpenApplicationInput {
721724
return {
@@ -747,16 +750,40 @@ test('a launch URL the bridge sees land in the app never reaches the runner', as
747750
expect(events).toEqual(['release', `open ${LAUNCH_URL}`, 'observe observable']);
748751
});
749752

753+
test('a launch URL whose bridge probe failed never reaches the runner', async () => {
754+
const { lifecycle, events, interactor } = launchUrlSimulator(
755+
async () => ({ message: 'Open in “Example App”?', items: ['Cancel', 'Open'] }),
756+
[
757+
{
758+
observation: 'probe-failed',
759+
failure: { code: 'bridge-disabled', reason: 'circuit-disabled' },
760+
},
761+
],
762+
);
763+
764+
const outcome = await lifecycle.openApplication(launchUrlInput());
765+
766+
expect(outcome.launchConfirmation).toBeUndefined();
767+
expect(outcome.timing.runnerDemand).toBe('none');
768+
expect(outcome.timing.postOpenObservation).toBe('probe-failed');
769+
expect(outcome.timing.postOpenObservationFailure).toEqual({
770+
code: 'bridge-disabled',
771+
reason: 'circuit-disabled',
772+
});
773+
expect(interactor.readAlert).not.toHaveBeenCalled();
774+
expect(events).toEqual(['release', `open ${LAUNCH_URL}`, 'observe probe-failed']);
775+
});
776+
750777
test('a launch URL held behind a confirmation naming the session app is accepted and reported', async () => {
751778
const { lifecycle, events } = launchUrlSimulator(
752779
async () => ({ message: 'Open in “Example App”?', items: ['Cancel', 'Open'] }),
753-
['unobservable', 'observable'],
780+
[UNOBSERVABLE, OBSERVABLE],
754781
);
755782

756783
const outcome = await lifecycle.openApplication(launchUrlInput());
757784

758785
expect(outcome.launchConfirmation).toBe('accepted');
759-
expect(outcome.timing.runnerDemand).toBe('none');
786+
expect(outcome.timing.runnerDemand).toBe('required');
760787
expect(outcome.timing.postOpenObservation).toBe('observable');
761788
expect(events).toEqual([
762789
'release',
@@ -779,12 +806,12 @@ test.each([
779806
async (_case, failure) => {
780807
const { lifecycle, events } = launchUrlSimulator(async () => {
781808
throw failure;
782-
}, ['unobservable']);
809+
}, [UNOBSERVABLE]);
783810

784811
const outcome = await lifecycle.openApplication(launchUrlInput());
785812

786813
expect(outcome.launchConfirmation).toBeUndefined();
787-
expect(outcome.timing.runnerDemand).toBe('none');
814+
expect(outcome.timing.runnerDemand).toBe('required');
788815
expect(outcome.timing.postOpenObservation).toBe('unobservable');
789816
expect(events).toEqual(['release', `open ${LAUNCH_URL}`, 'observe unobservable', 'alert get']);
790817
},
@@ -793,7 +820,7 @@ test.each([
793820
test('a launch URL confirmation naming another app fails the open without accepting it', async () => {
794821
const { lifecycle, interactor } = launchUrlSimulator(
795822
async () => ({ message: 'Open in “Other App”?', items: ['Cancel', 'Open'] }),
796-
['unobservable'],
823+
[UNOBSERVABLE],
797824
);
798825

799826
const failure = await lifecycle
@@ -814,7 +841,7 @@ test.each([
814841
['no launch URL', undefined],
815842
['a web launch URL', 'https://example.com/automation'],
816843
])('a Simulator open with %s never reads an alert', async (_name, runtimeLaunchUrl) => {
817-
const { lifecycle, interactor } = launchUrlSimulator(async () => ({}), ['unobservable']);
844+
const { lifecycle, interactor } = launchUrlSimulator(async () => ({}), [UNOBSERVABLE]);
818845

819846
const outcome = await lifecycle.openApplication({ ...launchUrlInput(), runtimeLaunchUrl });
820847

@@ -824,7 +851,7 @@ test.each([
824851
});
825852

826853
test('a physical iOS launch URL never reads an alert', async () => {
827-
const { interactor } = launchUrlSimulator(async () => ({}), ['unobservable']);
854+
const { interactor } = launchUrlSimulator(async () => ({}), [UNOBSERVABLE]);
828855
const lifecycle = bindAppleApplicationLifecycle({
829856
host: {
830857
...platformRuntimeHostFixture(),

‎packages/platform-apple/src/lifecycle.ts‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -256,9 +256,10 @@ async function dispatchAppleLaunchUrl(
256256

257257
/**
258258
* One alert read, spent only when the launch handed SpringBoard a URL it may hold behind a
259-
* confirmation and the host AX bridge then could not observe the launched app, the state a system
260-
* surface over the app leaves. An observed app is not covered, so its open never reaches the
261-
* runner. The read runs within what is left of the launch budget.
259+
* confirmation and the host AX bridge then read the launched app as unobservable, the state a
260+
* system surface over the app leaves. An observed app, or a bridge that could not observe at all,
261+
* is not covered, so its open never reaches the runner. The read runs within what is left of the
262+
* launch budget, and the runner it needs is recorded as the open's demand.
262263
*/
263264
async function answerAppleLaunchConfirmation(
264265
binding: BoundAppleInteractor,
@@ -271,6 +272,7 @@ async function answerAppleLaunchConfirmation(
271272
if (timing.postOpenObservation !== 'unobservable') return undefined;
272273
const budgetMs = IOS_APP_LAUNCH_TIMEOUT_MS - (Date.now() - launchStartedAtMs);
273274
if (budgetMs <= 0) return undefined;
275+
timing.runnerDemand = 'required';
274276
const { answerLaunchConfirmation, createLaunchConfirmationPort } = await loadLaunchConfirmation();
275277
const interactor = await binding.resolveInteractor(input.execution, input.appBundleId);
276278
return await answerLaunchConfirmation(

‎packages/platform-apple/src/open-policy.ts‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -84,11 +84,15 @@ export async function settleAppleOpen(
8484
): Promise<void> {
8585
const startedAtMs = Date.now();
8686
if (localIosSimulator && hasSimulatorBridge(binding.device) && observation && input.appBundleId) {
87-
timing.postOpenObservation = await observation.awaitObservable(
87+
const observed = await observation.awaitObservable(
8888
binding.device,
8989
input.appBundleId,
9090
binding.signal,
9191
);
92+
timing.postOpenObservation = observed.observation;
93+
if (observed.observation === 'probe-failed')
94+
timing.postOpenObservationFailure = observed.failure;
95+
else delete timing.postOpenObservationFailure;
9296
}
9397
if (localIosSimulator && timing.postOpenObservation !== 'observable') {
9498
await host.clock.sleep(POST_OPEN_SETTLE_MS, binding.signal);

‎packages/platform-apple/src/snapshot-observability.test.ts‎

Lines changed: 47 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -66,9 +66,9 @@ function probe(
6666

6767
test('a launched app is observable as soon as the bridge publishes it', async () => {
6868
const { observe, acquire, sleep } = probe([acquired()], { now: () => 0, sleep: async () => {} });
69-
await expect(observe.awaitObservable(simulator, 'com.example.app', signal())).resolves.toBe(
70-
'observable',
71-
);
69+
await expect(observe.awaitObservable(simulator, 'com.example.app', signal())).resolves.toEqual({
70+
observation: 'observable',
71+
});
7272
expect(acquire).toHaveBeenCalledOnce();
7373
expect(sleep).not.toHaveBeenCalled();
7474
});
@@ -88,9 +88,9 @@ test('a missing AX server is re-read inside its window until it registers', asyn
8888
},
8989
},
9090
);
91-
await expect(observe.awaitObservable(simulator, 'com.example.app', signal())).resolves.toBe(
92-
'observable',
93-
);
91+
await expect(observe.awaitObservable(simulator, 'com.example.app', signal())).resolves.toEqual({
92+
observation: 'observable',
93+
});
9494
expect(acquire).toHaveBeenCalledTimes(3);
9595
});
9696

@@ -113,9 +113,9 @@ test('an ownership miss after an AX-server miss shrinks the deadline to the owne
113113
},
114114
},
115115
);
116-
await expect(observe.awaitObservable(simulator, 'com.example.app', signal())).resolves.toBe(
117-
'unobservable',
118-
);
116+
await expect(observe.awaitObservable(simulator, 'com.example.app', signal())).resolves.toEqual({
117+
observation: 'unobservable',
118+
});
119119
expect(now).toBeGreaterThanOrEqual(3_000);
120120
expect(now).toBeLessThanOrEqual(3_150);
121121
expect(acquire.mock.calls.length).toBeGreaterThan(2);
@@ -137,37 +137,37 @@ test('the last poll is capped to the remaining window', async () => {
137137
});
138138

139139
test.each(['bridge-disconnected', 'continuation-budget-exhausted', 'snapshot-tree-malformed'])(
140-
'a %s failure ends the launch wait at once',
140+
'a %s failure ends the launch wait at once as a failed probe, not an unreadable app',
141141
async (code) => {
142142
const { observe, acquire, sleep } = probe([failed(code, 'transport-failure'), acquired()], {
143143
now: () => 0,
144144
sleep: async () => {},
145145
});
146-
await expect(observe.awaitObservable(simulator, 'com.example.app', signal())).resolves.toBe(
147-
'unobservable',
148-
);
146+
await expect(observe.awaitObservable(simulator, 'com.example.app', signal())).resolves.toEqual({
147+
observation: 'probe-failed',
148+
failure: { code: 'transport-failure', reason: code },
149+
});
149150
expect(acquire).toHaveBeenCalledOnce();
150151
expect(sleep).not.toHaveBeenCalled();
151152
},
152153
);
153154

154-
test('a generation whose bridge circuit is open is unobservable without a bridge round trip', async () => {
155+
test('a generation whose bridge circuit is open is a failed probe without a bridge round trip', async () => {
155156
const { observe, acquire, sleep, gate } = probe(
156157
[acquired()],
157158
{ now: () => 0, sleep: async () => {} },
158159
() => true,
159160
);
160-
await expect(observe.awaitObservable(simulator, 'com.example.app', signal())).resolves.toBe(
161-
'unobservable',
162-
);
161+
await expect(observe.awaitObservable(simulator, 'com.example.app', signal())).resolves.toEqual({
162+
observation: 'probe-failed',
163+
failure: { code: 'bridge-disabled', reason: 'circuit-disabled' },
164+
});
163165
expect(gate).toHaveBeenCalledWith(target);
164166
expect(acquire).not.toHaveBeenCalled();
165167
expect(sleep).not.toHaveBeenCalled();
166168
});
167169

168170
test('the skip is reported, so a live run can tell it from an unresolvable target', async () => {
169-
// Both verdicts are `unobservable` with zero acquisitions; only the diagnostic separates a
170-
// circuit skip from a target that never resolved.
171171
await withDiagnosticsScope({ command: 'open' }, async () => {
172172
const skipped = probe([acquired()], { now: () => 0, sleep: async () => {} }, () => true);
173173
await skipped.observe.awaitObservable(simulator, 'com.example.app', signal());
@@ -184,15 +184,34 @@ test('the skip is reported, so a live run can tell it from an unresolvable targe
184184
});
185185
await expect(
186186
unresolvable.awaitObservable(simulator, 'com.example.app', signal()),
187-
).resolves.toBe('unobservable');
187+
).resolves.toMatchObject({ observation: 'probe-failed' });
188188
expect(countDiagnosticEventsByPhase(['ios_launch_observation_skipped'])).toBe(0);
189189
});
190190
});
191191

192192
test.each([
193-
['a discovery still running is joined until it answers', 'simulator-target-discovery-pending', 3],
194-
['any other resolution failure is unobservable at once', 'simulator-target-unavailable', 1],
195-
])('%s', async (_name, reason, expectedResolutions) => {
193+
[
194+
'a discovery still running is joined until it answers',
195+
'simulator-target-discovery-pending',
196+
3,
197+
{ observation: 'observable' },
198+
],
199+
[
200+
'an app with no running process is unobservable at once',
201+
'simulator-target-unavailable',
202+
1,
203+
{ observation: 'unobservable' },
204+
],
205+
[
206+
'any other resolution failure is a failed probe at once',
207+
'simulator-target-probe-failed',
208+
1,
209+
{
210+
observation: 'probe-failed',
211+
failure: { code: 'COMMAND_FAILED', reason: 'simulator-target-probe-failed' },
212+
},
213+
],
214+
])('%s', async (_name, reason, expectedResolutions, verdict) => {
196215
let resolutions = 0;
197216
const acquire = vi.fn(async () => acquired());
198217
const observe = createLaunchObservationProbe({
@@ -209,8 +228,8 @@ test.each([
209228
clock: { now: () => 0, sleep: async () => {} },
210229
isBridgeDisabled: () => false,
211230
});
212-
await expect(observe.awaitObservable(simulator, 'com.example.app', signal())).resolves.toBe(
213-
expectedResolutions === 3 ? 'observable' : 'unobservable',
231+
await expect(observe.awaitObservable(simulator, 'com.example.app', signal())).resolves.toEqual(
232+
verdict,
214233
);
215234
expect(resolutions).toBe(expectedResolutions);
216235
});
@@ -220,9 +239,9 @@ test.each([
220239
['a tvOS Simulator', { ...simulator, appleOs: 'tvos' as const, target: 'tv' as const }],
221240
])('%s has no bridge and is not eligible', async (_name, device) => {
222241
const { observe, acquire, gate } = probe([acquired()], { now: () => 0, sleep: async () => {} });
223-
await expect(observe.awaitObservable(device, 'com.example.app', signal())).resolves.toBe(
224-
'not-eligible',
225-
);
242+
await expect(observe.awaitObservable(device, 'com.example.app', signal())).resolves.toEqual({
243+
observation: 'not-eligible',
244+
});
226245
expect(acquire).not.toHaveBeenCalled();
227246
expect(gate).not.toHaveBeenCalled();
228247
});

0 commit comments

Comments
 (0)