Skip to content

Commit d6d2e09

Browse files
thymikeeclaude
andauthored
test(kernel): cover all six errors.ts exports, kernel-errors mutation 55.19% → 86.26% (#1475)
* test(kernel): cover all six errors.ts exports with table-driven cases (#1456) Extends errors.test.ts beyond normalizeError/toAppErrorCode: - AppError construction and NormalizedError/AppError instanceof contract - asAppError identity/wrap/duck-typing behavior (cross-realm errors, non-Error throws, fallback code precedence) - isAgentDeviceError real-instance-only contract - retriableForErrorCode and defaultHintForCode, table-driven over KNOWN_APP_ERROR_CODES (the module's own source of truth) rather than a hand-copied code subset - normalizeAgentDeviceError delegation to normalizeError - a cross-cutting composition test asserting the retriable/hint contract request-router.ts's enrichDaemonError and the CLI's printHumanError actually rely on No production changes; mutation re-run and PR to follow. * test(kernel): pin maybeEnrichCommandFailedMessage gating and regex boundaries (#1456) Adds targeted cases for branches the table-driven/contract tests didn't reach: the COMMAND_FAILED/processExitError/string-stderr gating in maybeEnrichCommandFailedMessage, GENERIC_EXIT_MESSAGE's `-?\d+$` boundary (negative code, trailing text, non-numeric code, whitespace in the tool token), and STDERR_NOISE_PREFIX's zero-or-more-whitespace semantics for both the adb/xcrun/simctl and "error:" groups. * test(kernel): close remaining mutation gaps in firstStderrLine/detail helpers (#1456) Each addition here was verified against a hand-applied mutation (matching Stryker's actual survivor diffs) before landing, confirming it fails on the mutant and passes on the original: - firstStderrLine: line-trim-before-prefix-match (a real skip-pattern line ahead of the leading-whitespace one is required, since redactDiagnosticData already .trim()s the whole stderr string once before firstStderrLine ever sees it), and the >200-char truncation branch (both sides of the boundary: 200 exact vs 201+). - stringDetail/booleanDetail: reject a wrong-typed diagnosticId/logPath/ hint/retriable instead of surfacing it. - stripDiagnosticMeta: details drops to undefined once stripping the known meta keys leaves nothing behind. * style(kernel): apply oxfmt to errors.test.ts Fixes the Lint & Format CI failure on PR #1456 — format:check flagged this file, oxfmt --write resolves it with no behavior change. * test(kernel): split errors.test.ts into focused sibling suites (#1456) Per review feedback: the growing errors.test.ts hit 601 lines, past AGENTS.md's extract-before-500 threshold (tests are not exempt). Splits along the reviewer's requested seams, moving tests verbatim with no assertion changes: - errors-message.test.ts (234 lines) — stderr/message normalization: maybeEnrichCommandFailedMessage, firstStderrLine, the GENERIC_EXIT_MESSAGE/STDERR_NOISE_PREFIX regex boundaries. - errors-metadata.test.ts (157 lines) — hint/diagnosticId/logPath/ retriable/supportedOn lifting and stripping, divergence passthrough, the stringDetail/booleanDetail/stripDiagnosticMeta type-guard contracts, and the normalizeError/retriableForErrorCode/ defaultHintForCode cross-cutting contract. - errors-code-policy.test.ts (228 lines) — AppError construction, asAppError/isAgentDeviceError duck-typing contract, toAppErrorCode, the retriableForErrorCode/defaultHintForCode table-driven policy tests, and normalizeAgentDeviceError. Also repoints scripts/mutation/ownership.test.ts's two references to the deleted errors.test.ts path at errors-code-policy.test.ts — the mutation ownership deriver reads the file from disk to follow its import graph, so a stale path silently resolves to "owns nothing" instead of failing loudly. --------- Co-authored-by: Claude <[email protected]>
1 parent ce7b7a9 commit d6d2e09

5 files changed

Lines changed: 623 additions & 173 deletions

File tree

‎scripts/mutation/ownership.test.ts‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,9 @@ const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../
1616

1717
test('a kernel is owned by the mirrored test that imports it directly', () => {
1818
const deriver = ownershipDeriver(repoRoot);
19-
assert.deepEqual(deriver.ownersOf('src/kernel/__tests__/errors.test.ts'), ['kernel-errors']);
19+
assert.deepEqual(deriver.ownersOf('src/kernel/__tests__/errors-code-policy.test.ts'), [
20+
'kernel-errors',
21+
]);
2022
assert.ok(
2123
deriver.ownersOf('src/daemon/__tests__/ref-frame.test.ts').includes('daemon-ref-frame'),
2224
);
@@ -72,7 +74,7 @@ test('non-kernel sources and non-tests are not owned', () => {
7274
assert.deepEqual(derivedAffectedModules(['README.md', 'src/kernel/rect.ts'], repoRoot), []);
7375
assert.ok(!isTestFile('src/kernel/errors.ts'));
7476
assert.ok(!isTestFile('scripts/mutation/ownership.test.ts'));
75-
assert.ok(isTestFile('src/kernel/__tests__/errors.test.ts'));
77+
assert.ok(isTestFile('src/kernel/__tests__/errors-code-policy.test.ts'));
7678
});
7779

7880
test('derived selection unions source ownership with test reachability', () => {
Lines changed: 228 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,228 @@
1+
import { test } from 'vitest';
2+
import assert from 'node:assert/strict';
3+
import {
4+
AppError,
5+
asAppError,
6+
defaultHintForCode,
7+
isAgentDeviceError,
8+
KNOWN_APP_ERROR_CODES,
9+
normalizeAgentDeviceError,
10+
normalizeError,
11+
retriableForErrorCode,
12+
toAppErrorCode,
13+
type KnownAppErrorCode,
14+
} from '../errors.ts';
15+
16+
test('toAppErrorCode falls back when code is missing or empty', () => {
17+
assert.equal(toAppErrorCode(undefined), 'COMMAND_FAILED');
18+
assert.equal(toAppErrorCode(''), 'COMMAND_FAILED');
19+
assert.equal(toAppErrorCode(undefined, 'UNAUTHORIZED'), 'UNAUTHORIZED');
20+
});
21+
22+
// --- AppError: construction contract ---
23+
24+
test('AppError is a real Error carrying code/message/details/cause', () => {
25+
const cause = new Error('root cause');
26+
const err = new AppError('DEVICE_NOT_FOUND', 'no device', { hint: 'custom' }, cause);
27+
assert.ok(err instanceof Error);
28+
assert.ok(err instanceof AppError);
29+
assert.equal(err.name, 'Error'); // AppError does not override `name`.
30+
assert.equal(err.code, 'DEVICE_NOT_FOUND');
31+
assert.equal(err.message, 'no device');
32+
assert.deepEqual(err.details, { hint: 'custom' });
33+
assert.equal(err.cause, cause);
34+
});
35+
36+
test('AppError leaves details and cause undefined when the constructor omits them', () => {
37+
const err = new AppError('UNKNOWN', 'plain');
38+
assert.equal(err.details, undefined);
39+
assert.equal(err.cause, undefined);
40+
});
41+
42+
// --- asAppError: identity, wrapping, and duck-typing contract ---
43+
//
44+
// Every catch site that normalizes a thrown value (src/cli.ts, src/daemon.ts,
45+
// src/daemon/server/daemon-runtime.ts, the platform runners) funnels through
46+
// `asAppError`, so its branch selection is load-bearing: get it wrong and a
47+
// caller silently loses a real error's message/stack.
48+
49+
test('asAppError returns an AppError input unchanged — no re-wrap, same instance', () => {
50+
const original = new AppError('TOOL_MISSING', 'missing tool');
51+
assert.equal(asAppError(original), original);
52+
});
53+
54+
test('asAppError wraps a plain Error under the fallback code, preserving its message and chaining it as cause', () => {
55+
const original = new Error('boom');
56+
const wrapped = asAppError(original);
57+
assert.ok(wrapped instanceof AppError);
58+
assert.notEqual(wrapped, original);
59+
assert.equal(wrapped.code, 'UNKNOWN');
60+
assert.equal(wrapped.message, 'boom');
61+
assert.equal(wrapped.details, undefined);
62+
assert.equal(wrapped.cause, original);
63+
});
64+
65+
test('asAppError honors an explicit fallback code when wrapping a plain Error', () => {
66+
const wrapped = asAppError(new Error('boom'), 'COMMAND_FAILED');
67+
assert.equal(wrapped.code, 'COMMAND_FAILED');
68+
assert.equal(wrapped.message, 'boom');
69+
});
70+
71+
test('asAppError wraps a non-Error throw as "Unknown error" and preserves the raw value in details.err', () => {
72+
const wrapped = asAppError('a raw string throw');
73+
assert.equal(wrapped.code, 'UNKNOWN');
74+
assert.equal(wrapped.message, 'Unknown error');
75+
assert.equal(wrapped.details?.err, 'a raw string throw');
76+
assert.equal(wrapped.cause, undefined);
77+
});
78+
79+
test('asAppError applies the fallback code to non-Error throws too, not just Error instances', () => {
80+
const wrapped = asAppError({ some: 'object' }, 'INVALID_ARGS');
81+
assert.equal(wrapped.code, 'INVALID_ARGS');
82+
assert.equal(wrapped.message, 'Unknown error');
83+
assert.deepEqual(wrapped.details?.err, { some: 'object' });
84+
});
85+
86+
test('asAppError wraps null/undefined the same as any other non-Error value, keeping the raw value in details.err', () => {
87+
const wrappedNull = asAppError(null);
88+
assert.equal(wrappedNull.code, 'UNKNOWN');
89+
assert.equal(wrappedNull.message, 'Unknown error');
90+
assert.equal(wrappedNull.details?.err, null);
91+
assert.ok(Object.hasOwn(wrappedNull.details ?? {}, 'err'));
92+
93+
const wrappedUndefined = asAppError(undefined);
94+
assert.equal(wrappedUndefined.message, 'Unknown error');
95+
assert.ok(Object.hasOwn(wrappedUndefined.details ?? {}, 'err'));
96+
assert.equal(wrappedUndefined.details?.err, undefined);
97+
});
98+
99+
test('asAppError does not special-case a duck-typed, cross-realm-style Error lookalike — it falls through the non-Error branch', () => {
100+
// `instanceof Error` fails for a cross-realm Error (different VM context) and
101+
// for any plain object shaped like one. `asAppError` has no fallback for that
102+
// case: it treats the value as an opaque non-Error and drops its message and
103+
// stack into details.err instead of preserving them as `.message`/`.cause`.
104+
// Every catch-site caller relies on exactly this fallthrough, not a smarter
105+
// duck-typed detection, so pin it as the contract rather than an accident.
106+
const duckTypedError = { name: 'Error', message: 'looks like an error', stack: 'fake stack' };
107+
const wrapped = asAppError(duckTypedError);
108+
assert.equal(wrapped.code, 'UNKNOWN');
109+
assert.equal(wrapped.message, 'Unknown error');
110+
assert.equal(wrapped.details?.err, duckTypedError);
111+
assert.notEqual(wrapped.message, duckTypedError.message);
112+
});
113+
114+
// --- isAgentDeviceError: real instances only, no duck-typing ---
115+
116+
test('isAgentDeviceError is true only for a real AppError instance', () => {
117+
assert.equal(isAgentDeviceError(new AppError('UNKNOWN', 'x')), true);
118+
});
119+
120+
test('isAgentDeviceError is false for a plain Error', () => {
121+
assert.equal(isAgentDeviceError(new Error('plain error')), false);
122+
});
123+
124+
test('isAgentDeviceError is false for an object that merely duck-types the AppError shape', () => {
125+
const lookalike = { code: 'UNKNOWN', message: 'x', name: 'AppError', details: undefined };
126+
assert.equal(isAgentDeviceError(lookalike), false);
127+
});
128+
129+
test('isAgentDeviceError is false for nullish and primitive values', () => {
130+
assert.equal(isAgentDeviceError(null), false);
131+
assert.equal(isAgentDeviceError(undefined), false);
132+
assert.equal(isAgentDeviceError('not an error'), false);
133+
assert.equal(isAgentDeviceError(42), false);
134+
});
135+
136+
// --- retriableForErrorCode: table-driven over the module's own code registry ---
137+
//
138+
// The enumeration comes from `KNOWN_APP_ERROR_CODES` itself (the module's
139+
// documented source of truth for "every code that must resolve a verdict"),
140+
// never a hand-copied subset — a code added to the registry without a matching
141+
// verdict decision automatically gets a test case here.
142+
143+
/** The only code with a confident retriability verdict today (see RETRIABILITY_BY_CODE in errors.ts). */
144+
const RETRIABLE_TRUE_CODES: readonly KnownAppErrorCode[] = ['DEVICE_IN_USE'];
145+
146+
for (const code of KNOWN_APP_ERROR_CODES) {
147+
const expected = RETRIABLE_TRUE_CODES.includes(code) ? true : undefined;
148+
test(`retriableForErrorCode('${code}') is ${expected}`, () => {
149+
assert.equal(retriableForErrorCode(code), expected);
150+
});
151+
}
152+
153+
test('retriableForErrorCode returns undefined for a daemon/runner-originated code outside the known registry', () => {
154+
assert.equal(retriableForErrorCode('SOME_DAEMON_ONLY_CODE'), undefined);
155+
assert.equal(retriableForErrorCode(''), undefined);
156+
});
157+
158+
// --- defaultHintForCode: table-driven over the module's own code registry ---
159+
160+
/** Mirrors the switch in `defaultHintForCode` — one entry per `KNOWN_APP_ERROR_CODES` member. */
161+
const EXPECTED_HINT_BY_CODE: Record<KnownAppErrorCode, string> = {
162+
INVALID_ARGS: 'Check command arguments and run --help for usage examples.',
163+
DEVICE_NOT_FOUND: 'Verify the target device is booted/connected and selectors match.',
164+
DEVICE_IN_USE: 'The device is busy with another agent-device request; retry once it frees up.',
165+
TOOL_MISSING: 'Install required platform tooling and ensure it is available in PATH.',
166+
APP_NOT_INSTALLED:
167+
'Run apps to discover the exact installed package or bundle id, or install the app before open.',
168+
UNSUPPORTED_PLATFORM:
169+
'This platform is not supported for the requested operation; run devices to inspect available targets.',
170+
UNSUPPORTED_OPERATION: 'This command is not available for the selected platform/device.',
171+
NOT_IMPLEMENTED: 'This command is part of the planned API but is not implemented yet.',
172+
COMMAND_FAILED: 'Retry with --debug and inspect diagnostics log for details.',
173+
SESSION_NOT_FOUND: 'Run open first or pass an explicit device selector.',
174+
UNAUTHORIZED: 'Refresh daemon metadata and retry the command.',
175+
AMBIGUOUS_MATCH: 'Multiple candidates matched. Narrow the query or pass an exact identifier.',
176+
REPLAY_DIVERGENCE:
177+
'Read details.divergence (screen/suggestions) for repair context, or rerun with --json for the full report.',
178+
REPAIR_SESSION_EXPIRED:
179+
'The --save-script repair session was reaped before it was finalized; re-run replay <script> --save-script from the start.',
180+
REPAIR_COMMIT_FAILED:
181+
'The repair transaction completed, but committing its healed script failed at teardown (no-clobber refusal or a filesystem error); inspect the target path/permissions, then re-run replay <script> --save-script to retry.',
182+
UNKNOWN:
183+
'Unexpected internal error. Retry with --debug and report the diagnostics log if it persists.',
184+
};
185+
186+
for (const code of KNOWN_APP_ERROR_CODES) {
187+
test(`defaultHintForCode('${code}') matches the documented hint`, () => {
188+
assert.equal(defaultHintForCode(code), EXPECTED_HINT_BY_CODE[code]);
189+
});
190+
}
191+
192+
test('EXPECTED_HINT_BY_CODE covers every known code — a registry addition without a hint decision fails loudly', () => {
193+
assert.deepEqual(Object.keys(EXPECTED_HINT_BY_CODE).sort(), [...KNOWN_APP_ERROR_CODES].sort());
194+
});
195+
196+
test('defaultHintForCode falls back to the generic retry hint for a daemon/runner-originated code outside the registry', () => {
197+
assert.equal(
198+
defaultHintForCode('SOME_DAEMON_ONLY_CODE'),
199+
'Retry with --debug and inspect diagnostics log for details.',
200+
);
201+
});
202+
203+
test('defaultHintForCode never returns a falsy hint for any known code — printHumanError silently drops a falsy hint', () => {
204+
// src/utils/output.ts's printHumanError only prints "Hint: ..." when
205+
// `normalized.hint` is truthy, so an empty-string hint would silently vanish
206+
// from CLI output rather than fail loudly.
207+
for (const code of KNOWN_APP_ERROR_CODES) {
208+
const hint = defaultHintForCode(code);
209+
assert.ok(hint, `expected a non-empty hint for ${code}`);
210+
}
211+
});
212+
213+
// --- normalizeAgentDeviceError: the SDK-facing name for normalizeError ---
214+
// (src/sdk/index.ts re-exports it under this name for public consumers.)
215+
216+
test('normalizeAgentDeviceError delegates to normalizeError, including the context argument', () => {
217+
const err = new AppError('SESSION_NOT_FOUND', 'gone');
218+
const normalized = normalizeAgentDeviceError(err, {
219+
diagnosticId: 'diag-9',
220+
logPath: '/tmp/9.log',
221+
});
222+
assert.deepEqual(
223+
normalized,
224+
normalizeError(err, { diagnosticId: 'diag-9', logPath: '/tmp/9.log' }),
225+
);
226+
assert.equal(normalized.diagnosticId, 'diag-9');
227+
assert.equal(normalized.logPath, '/tmp/9.log');
228+
});

0 commit comments

Comments
 (0)