Skip to content

Commit 03b666b

Browse files
authored
feat: actionable hint for adb timeouts (callstack#1090)
A timed-out adb invocation has no stderr for the failure classifier to match, so it fell through to the generic retry hint — retrying a wedged adb server times out identically. Classify exec-layer timeouts on the structured timeoutMs detail (the signal createTimeoutError sets) as a 'timeout' family with a kill-server/start-server hint, winning over untrustworthy partial stderr and losing to site hints as before. Doctor's android inventory sweep already routes adb failures through attachAdbFailureHint via listAndroidDeviceEntries, so the device-android check now surfaces the wedged-server hint; a regression test locks that path. Closes callstack#1079
1 parent e031a5c commit 03b666b

4 files changed

Lines changed: 146 additions & 6 deletions

File tree

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
import assert from 'node:assert/strict';
2+
import { test } from 'vitest';
3+
import { withDeviceInventoryProvider } from '../../../core/dispatch-resolve.ts';
4+
import { AppError } from '../../../kernel/errors.ts';
5+
import type { DeviceInfo } from '../../../kernel/device.ts';
6+
import { attachAdbFailureHint } from '../../../platforms/android/adb-executor.ts';
7+
import type { DaemonRequest } from '../../types.ts';
8+
import { appendDeviceInventoryCheck } from '../session-doctor-device.ts';
9+
import type { DoctorCheck } from '../session-doctor-types.ts';
10+
11+
const BOOTED_IOS_SIMULATOR: DeviceInfo = {
12+
platform: 'apple',
13+
appleOs: 'ios',
14+
id: 'SIM-UDID-1',
15+
name: 'iPhone 16',
16+
kind: 'simulator',
17+
booted: true,
18+
};
19+
20+
// Issue #1079 repro: a wedged adb makes `adb devices -l` time out during the
21+
// unscoped doctor inventory sweep. The Android listing routes that failure
22+
// through the adb classifier, and doctor must surface the classified hint on
23+
// the device-android check instead of the generic toolchain fallback.
24+
test('doctor android inventory timeout surfaces the wedged-adb-server hint', async () => {
25+
const checks: DoctorCheck[] = [];
26+
const req = { token: 't', session: 'default', command: 'doctor' } as DaemonRequest;
27+
28+
await withDeviceInventoryProvider(
29+
async (request) => {
30+
if (request.platform === 'android') {
31+
// Same classified error listAndroidDeviceEntries throws when the
32+
// exec layer times out an adb invocation.
33+
throw attachAdbFailureHint(
34+
new AppError('COMMAND_FAILED', 'adb timed out after 10000ms', {
35+
cmd: 'adb',
36+
args: ['devices', '-l'],
37+
stdout: '',
38+
stderr: '',
39+
exitCode: -1,
40+
timeoutMs: 10000,
41+
}),
42+
);
43+
}
44+
if (request.platform === 'apple') return [BOOTED_IOS_SIMULATOR];
45+
return [];
46+
},
47+
async () => {
48+
await appendDeviceInventoryCheck(checks, req, undefined);
49+
},
50+
);
51+
52+
const deviceCheck = checks.find((check) => check.id === 'device');
53+
assert.equal(deviceCheck?.status, 'pass');
54+
55+
const androidCheck = checks.find((check) => check.id === 'device-android');
56+
assert.equal(androidCheck?.status, 'warn');
57+
assert.match(androidCheck?.summary ?? '', /Android device inventory could not be read/);
58+
assert.match(androidCheck?.summary ?? '', /timed out after 10000ms/);
59+
assert.match(androidCheck?.hint ?? '', /adb kill-server && adb start-server/);
60+
});

‎src/platforms/android/__tests__/adb-executor.test.ts‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -429,6 +429,62 @@ test('the local adb executor flags transient transport failures retriable', asyn
429429
assert.equal(error.details?.retriable, true);
430430
});
431431

432+
test('the local adb executor classifies exec-layer timeouts as a wedged adb server', async () => {
433+
mockRunCmd.mockClear();
434+
// Shape of createTimeoutError in utils/exec.ts: no stderr to classify, the
435+
// structured `timeoutMs` detail is the signal.
436+
mockRunCmd.mockRejectedValueOnce(
437+
new AppError('COMMAND_FAILED', 'adb timed out after 10000ms', {
438+
cmd: 'adb',
439+
args: ['-s', 'emulator-5554', 'devices', '-l'],
440+
stdout: '',
441+
stderr: '',
442+
exitCode: -1,
443+
timeoutMs: 10000,
444+
}),
445+
);
446+
const adb = createDeviceAdbExecutor({
447+
platform: 'android',
448+
id: 'emulator-5554',
449+
name: 'Pixel Emulator',
450+
kind: 'emulator',
451+
booted: true,
452+
});
453+
454+
const error = await adb(['devices', '-l']).then(
455+
() => assert.fail('expected the adb call to reject'),
456+
(err: unknown) => err,
457+
);
458+
459+
assert.ok(error instanceof AppError);
460+
assert.equal(error.details?.adbFailure, 'timeout');
461+
assert.match(String(error.details?.hint), /adb kill-server && adb start-server/);
462+
// A wedged adb server times out identically on an unchanged retry.
463+
assert.equal(Object.hasOwn(error.details ?? {}, 'retriable'), false);
464+
});
465+
466+
test('attachAdbFailureHint classifies timeouts over partial stderr and keeps site hints winning', () => {
467+
// Partial output from the killed process must not reclassify the timeout
468+
// (transport-error stderr would otherwise flag it retriable).
469+
const timedOutWithPartialStderr = new AppError('COMMAND_FAILED', 'adb timed out after 5000ms', {
470+
stderr: 'error: transport error',
471+
timeoutMs: 5000,
472+
});
473+
attachAdbFailureHint(timedOutWithPartialStderr);
474+
assert.equal(timedOutWithPartialStderr.details?.adbFailure, 'timeout');
475+
assert.match(String(timedOutWithPartialStderr.details?.hint), /kill-server/);
476+
assert.equal(Object.hasOwn(timedOutWithPartialStderr.details ?? {}, 'retriable'), false);
477+
478+
const withSiteHint = new AppError('COMMAND_FAILED', 'adb timed out after 5000ms', {
479+
stderr: '',
480+
timeoutMs: 5000,
481+
hint: 'site-specific hint',
482+
});
483+
attachAdbFailureHint(withSiteHint);
484+
assert.equal(withSiteHint.details?.hint, 'site-specific hint');
485+
assert.equal(withSiteHint.details?.adbFailure, 'timeout');
486+
});
487+
432488
test('attachAdbFailureHint preserves existing hints and ignores non-adb errors', () => {
433489
const withHint = new AppError('COMMAND_FAILED', 'adb exited with code 1', {
434490
stderr: 'adb: device offline',

‎src/platforms/android/__tests__/snapshot.test.ts‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1418,7 +1418,10 @@ test('dumpUiHierarchy does not attach animation hint to non-dump timeouts', asyn
14181418
(error: unknown) =>
14191419
error instanceof AppError &&
14201420
error.message === 'adb timed out after 8000ms' &&
1421-
typeof error.details?.hint === 'undefined',
1421+
// Non-dump timeouts keep the generic classified adb-timeout hint instead
1422+
// of the looping-animation explanation reserved for uiautomator dump.
1423+
!String(error.details?.hint).includes('Android accessibility snapshots can be blocked') &&
1424+
error.details?.adbFailure === 'timeout',
14221425
);
14231426
});
14241427

‎src/platforms/android/adb-executor.ts‎

Lines changed: 26 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -190,6 +190,7 @@ const androidAdbProviderScope = new AsyncLocalStorage<AndroidAdbProviderScope>()
190190
export type AdbFailureClassification = {
191191
/** Machine-readable failure family, attached to error details as `adbFailure`. */
192192
reason:
193+
| 'timeout'
193194
| 'device_offline'
194195
| 'device_unauthorized'
195196
| 'device_not_found'
@@ -284,6 +285,16 @@ const ADB_FAILURE_MATCHERS: readonly AdbFailureMatcher[] = [
284285
},
285286
];
286287

288+
// A timed-out adb invocation leaves no failure output to key on — the exec
289+
// layer kills the process and rejects with COMMAND_FAILED carrying `timeoutMs`
290+
// in details (see createTimeoutError in utils/exec.ts), so timeouts classify on
291+
// that structured signal instead of a stderr matcher. Not marked retriable: an
292+
// unchanged retry against a wedged adb server times out identically.
293+
const ADB_TIMEOUT_CLASSIFICATION: AdbFailureClassification = {
294+
reason: 'timeout',
295+
hint: 'adb timed out — the adb server may be wedged. Run adb kill-server && adb start-server, check adb devices, then retry.',
296+
};
297+
287298
/**
288299
* Maps well-known adb failure output to an actionable hint (and a `retriable`
289300
* flag for clearly transient families). Matches stderr; install verdicts also
@@ -306,15 +317,14 @@ export function classifyAdbFailure(
306317
/**
307318
* Enriches a failed adb command error in place with the classified hint,
308319
* `retriable` flag, and machine-readable `adbFailure` family, so every adb call
309-
* site surfaces guidance without per-site classification. No-op for errors that
310-
* are not adb command failures or that carry no recognized failure output; an
320+
* site surfaces guidance without per-site classification. Exec-layer timeouts
321+
* classify as `timeout` even though they leave no stderr. No-op for errors that
322+
* are not adb command failures or that carry no recognized failure signal; an
311323
* existing hint or retriable verdict is never overwritten.
312324
*/
313325
export function attachAdbFailureHint<T>(error: T): T {
314326
if (!(error instanceof AppError) || error.code !== 'COMMAND_FAILED') return error;
315-
const stderr = typeof error.details?.stderr === 'string' ? error.details.stderr : '';
316-
const stdout = typeof error.details?.stdout === 'string' ? error.details.stdout : '';
317-
const classification = classifyAdbFailure(stderr, stdout);
327+
const classification = classifyAdbCommandError(error);
318328
if (!classification) return error;
319329
error.details = {
320330
...error.details,
@@ -327,6 +337,17 @@ export function attachAdbFailureHint<T>(error: T): T {
327337
return error;
328338
}
329339

340+
// Timeout wins over text matchers: the exec layer deliberately builds timeout
341+
// errors around "timed out after Nms" because partial output from the killed
342+
// process is untrustworthy — classifying that partial stderr (e.g. flagging a
343+
// half-written transport line retriable) would point away from the real fix.
344+
function classifyAdbCommandError(error: AppError): AdbFailureClassification | undefined {
345+
if (typeof error.details?.timeoutMs === 'number') return ADB_TIMEOUT_CLASSIFICATION;
346+
const stderr = typeof error.details?.stderr === 'string' ? error.details.stderr : '';
347+
const stdout = typeof error.details?.stdout === 'string' ? error.details.stdout : '';
348+
return classifyAdbFailure(stderr, stdout);
349+
}
350+
330351
/**
331352
* Builds the COMMAND_FAILED AppError for a failed `allowFailure` adb result and
332353
* runs it through the failure classifier. This is the shared construction point

0 commit comments

Comments
 (0)