Skip to content

Commit a0975db

Browse files
committed
refactor(readiness): one boot_timeout reason and hint for every boot deadline
1 parent ed604d9 commit a0975db

4 files changed

Lines changed: 39 additions & 11 deletions

File tree

‎packages/contracts/src/device-readiness-runtime.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,9 @@
11
import type { DeviceInfo } from '@agent-device/kernel/device';
22
import type { DeviceInventoryRequest } from './device-inventory.ts';
33

4+
/** Typed `details.reason` every platform reports when the boot deadline expires. */
5+
export const BOOT_TIMEOUT_REASON = 'boot_timeout';
6+
47
export type EnsureReadyInput = Readonly<{
58
serial?: string;
69
androidSerialAllowlist?: readonly string[];

‎packages/platform-android/src/readiness/runtime.test.ts‎

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -93,7 +93,10 @@ test('a startup deadline bounds the emulator boot wait and expiry reports boot_t
9393
});
9494

9595
test('a startup deadline also bounds waiting for a launched emulator to appear', async () => {
96-
const { host, elapsed } = timedHost({ bootCompleted: '1', discover: () => [stoppedAvd()] });
96+
const { host, elapsed, terminate } = timedHost({
97+
bootCompleted: '1',
98+
discover: () => [stoppedAvd()],
99+
});
97100

98101
await expect(
99102
ensureAndroidReady(
@@ -104,6 +107,25 @@ test('a startup deadline also bounds waiting for a launched emulator to appear',
104107
),
105108
).rejects.toMatchObject({ details: { reason: 'boot_timeout' } });
106109
expect(elapsed()).toBeLessThan(5_000);
110+
expect(terminate).not.toHaveBeenCalled();
111+
});
112+
113+
test('expiry of a launched emulator that never reports boot_completed leaves it running', async () => {
114+
let discoveries = 0;
115+
const { host, terminate } = timedHost({
116+
bootCompleted: '0',
117+
discover: () => (++discoveries === 1 ? [stoppedAvd()] : [runningEmulator()]),
118+
});
119+
120+
await expect(
121+
ensureAndroidReady(
122+
host,
123+
stoppedAvd(),
124+
{ headless: true, deadlineAtMs: 3_000 },
125+
new AbortController().signal,
126+
),
127+
).rejects.toMatchObject({ details: { reason: 'boot_timeout', serial: 'emulator-5554' } });
128+
expect(terminate).not.toHaveBeenCalled();
107129
});
108130

109131
test('without a deadline the default 120s boot wait applies', async () => {

‎packages/platform-android/src/readiness/runtime.ts‎

Lines changed: 11 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,7 @@
1-
import type { EnsureReadyInput } from '@agent-device/contracts/device-readiness-runtime';
1+
import {
2+
BOOT_TIMEOUT_REASON,
3+
type EnsureReadyInput,
4+
} from '@agent-device/contracts/device-readiness-runtime';
25
import type { PlatformRuntimeHost } from '@agent-device/contracts/platform-runtime-operations';
36

47
/** Readiness reads exactly these host ports; the lifecycle binding composes the same subset. */
@@ -13,7 +16,6 @@ import { delegateManagedDeviceReadiness } from '@agent-device/provision-kit/mana
1316

1417
const BOOT_TIMEOUT_MS = 120_000;
1518
const POLL_MS = 1_000;
16-
const BOOT_TIMEOUT_REASON = 'boot_timeout';
1719

1820
export async function ensureAndroidReady(
1921
host: AndroidReadinessHost,
@@ -104,11 +106,7 @@ async function waitForDiscovery(
104106
if (device && isRunningEmulator(device)) return device;
105107
await host.clock.sleep(POLL_MS, signal);
106108
}
107-
throw new AppError('COMMAND_FAILED', 'Android emulator did not appear in time', {
108-
avdName,
109-
serial,
110-
reason: BOOT_TIMEOUT_REASON,
111-
});
109+
throw bootTimeoutError('Android emulator did not appear in time', { avdName, serial });
112110
}
113111

114112
async function waitForBoot(
@@ -130,8 +128,12 @@ async function waitForBoot(
130128
if (result.stdout.trim() === '1') return;
131129
await host.clock.sleep(POLL_MS, signal);
132130
}
133-
throw new AppError('COMMAND_FAILED', 'Android device failed to finish booting', {
134-
serial,
131+
throw bootTimeoutError('Android device failed to finish booting', { serial });
132+
}
133+
134+
function bootTimeoutError(message: string, details: Record<string, unknown>): AppError {
135+
return new AppError('COMMAND_FAILED', message, {
136+
...details,
135137
reason: BOOT_TIMEOUT_REASON,
136138
hint: 'The emulator keeps booting in the background. Retry once it is up, or pass a larger --timeout.',
137139
});

‎packages/platform-apple/src/readiness/runtime.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
import { BOOT_TIMEOUT_REASON } from '@agent-device/contracts/device-readiness-runtime';
12
import type { PlatformRuntimeHost } from '@agent-device/contracts/platform-runtime-operations';
23
import { isMacOs, type DeviceInfo } from '@agent-device/kernel/device';
34
import { AppError } from '@agent-device/kernel/errors';
@@ -170,7 +171,7 @@ function bootDeadlineError(device: DeviceInfo, cause?: unknown): AppError {
170171
'COMMAND_FAILED',
171172
'Simulator did not finish booting within the startup budget',
172173
{
173-
reason: 'boot_timeout',
174+
reason: BOOT_TIMEOUT_REASON,
174175
deviceId: device.id,
175176
hint: 'The Simulator keeps booting in the background; a first boot can take several minutes. Retry once it is up, or pass a larger --timeout.',
176177
},

0 commit comments

Comments
 (0)