Skip to content

Commit 8bf8695

Browse files
committed
test(utils): pin the recovery hints the AppError conversion added
The tightened assertions supplied only code and message, and the helper did not look at the hint, so deleting either hint constant left every targeted test green — vacuous for the half of #1792 that ADR 0010 actually cares about. assertThrowsAppError/assertRejectsAppError now accept a hint, checked against normalizeError's view so a dropped hint surfaces as the misleading per-code default rather than passing, and each guard pins its exact text as a literal (importing the constant would compare it to itself).
1 parent 1c1130e commit 8bf8695

4 files changed

Lines changed: 54 additions & 28 deletions

File tree

Lines changed: 33 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,43 +1,50 @@
11
import assert from 'node:assert/strict';
2-
import { AppError } from '@agent-device/kernel/errors';
2+
import { AppError, normalizeError } from '@agent-device/kernel/errors';
3+
4+
/**
5+
* What an {@link AppError} assertion may pin. `hint` is checked against the
6+
* hint a caller actually reads — `normalizeError`'s, not `details.hint` — so a
7+
* throw site that drops its hint and silently inherits `defaultHintForCode`
8+
* fails the assertion instead of passing on the default (ADR 0010: a hint is
9+
* required wherever the per-code default would mislead).
10+
*/
11+
type ExpectedAppError = { code: string; message?: RegExp; hint?: string | RegExp };
12+
13+
function assertAppError(error: unknown, expected: ExpectedAppError): true {
14+
assert.ok(
15+
error instanceof AppError,
16+
`expected AppError, got ${error?.constructor?.name ?? typeof error}: ${String(error)}`,
17+
);
18+
assert.equal(error.code, expected.code);
19+
if (expected.message) assert.match(error.message, expected.message);
20+
if (expected.hint !== undefined) {
21+
const { hint } = normalizeError(error);
22+
assert.ok(typeof hint === 'string', `expected a hint on ${error.code}, got ${String(hint)}`);
23+
if (typeof expected.hint === 'string') assert.equal(hint, expected.hint);
24+
else assert.match(hint, expected.hint);
25+
}
26+
return true;
27+
}
328

429
/**
530
* Asserts that `run` rejects with an {@link AppError} carrying `code` and,
6-
* when given, a message matching `message`. Replaces the hand-rolled
31+
* when given, a message matching `message` and the exact `hint` a caller
32+
* reads. Replaces the hand-rolled
733
* `assert.rejects(..., error instanceof AppError + code + match)` validator
834
* repeated across platform tests.
935
*/
1036
export async function assertRejectsAppError(
1137
run: () => Promise<unknown>,
12-
expected: { code: string; message?: RegExp },
38+
expected: ExpectedAppError,
1339
): Promise<void> {
14-
await assert.rejects(run, (error: unknown) => {
15-
assert.ok(
16-
error instanceof AppError,
17-
`expected AppError, got ${error?.constructor?.name ?? typeof error}: ${String(error)}`,
18-
);
19-
assert.equal(error.code, expected.code);
20-
if (expected.message) assert.match(error.message, expected.message);
21-
return true;
22-
});
40+
await assert.rejects(run, (error: unknown) => assertAppError(error, expected));
2341
}
2442

2543
/**
2644
* Synchronous sibling of {@link assertRejectsAppError}: asserts that `fn`
2745
* throws an {@link AppError} carrying `code` and, when given, a message
28-
* matching `message`.
46+
* matching `message` and the exact `hint`.
2947
*/
30-
export function assertThrowsAppError(
31-
fn: () => unknown,
32-
expected: { code: string; message?: RegExp },
33-
): void {
34-
assert.throws(fn, (error: unknown) => {
35-
assert.ok(
36-
error instanceof AppError,
37-
`expected AppError, got ${error?.constructor?.name ?? typeof error}: ${String(error)}`,
38-
);
39-
assert.equal(error.code, expected.code);
40-
if (expected.message) assert.match(error.message, expected.message);
41-
return true;
42-
});
48+
export function assertThrowsAppError(fn: () => unknown, expected: ExpectedAppError): void {
49+
assert.throws(fn, (error: unknown) => assertAppError(error, expected));
4350
}

‎src/daemon/__tests__/app-log.test.ts‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,10 @@ import { assertThrowsAppError } from '../../__tests__/test-utils/index.ts';
55
import { mkdtempForTestSync } from '../../__tests__/test-utils/tmp-dir.ts';
66
import { appendAppLogMarker, clearAppLogFiles, getAppLogPathMetadata } from '../app-log.ts';
77

8+
// Pinned as a literal on purpose — see the note in src/utils/__tests__/verified-file.test.ts.
9+
const NOT_REGULAR_FILE_HINT =
10+
'agent-device only reads and writes regular files at this path. Remove the symbolic link or special file there and retry.';
11+
812
test('marker and clear operations keep app-log file ownership in the daemon', () => {
913
const root = mkdtempForTestSync('agent-device-app-log-files-');
1014
const outPath = path.join(root, 'session', 'app.log');
@@ -44,7 +48,7 @@ test.each(['metadata', 'mark', 'clear'] as const)(
4448
else if (operation === 'mark') appendAppLogMarker(outPath, 'checkpoint');
4549
else clearAppLogFiles(outPath);
4650
},
47-
{ code: 'COMMAND_FAILED', message: expectedMessage },
51+
{ code: 'COMMAND_FAILED', message: expectedMessage, hint: NOT_REGULAR_FILE_HINT },
4852
);
4953
expect(fs.readFileSync(outsidePath, 'utf8')).toBe('outside');
5054
expect(fs.lstatSync(outPath).isSymbolicLink()).toBe(true);

‎src/utils/__tests__/app-log-files.test.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,10 @@ import { assertThrowsAppError } from '../../__tests__/test-utils/index.ts';
55
import { mkdtempForTestSync } from '../../__tests__/test-utils/tmp-dir.ts';
66
import { ensureAppLogPath, rotateAppLogIfNeeded } from '../app-log-files.ts';
77

8+
// Pinned as a literal on purpose — see the note in verified-file.test.ts.
9+
const NOT_REGULAR_FILE_HINT =
10+
'agent-device only reads and writes regular files at this path. Remove the symbolic link or special file there and retry.';
11+
812
test('rotateAppLogIfNeeded rotates files and discards the oldest generation', () => {
913
const root = mkdtempForTestSync('agent-device-app-log-rotate-');
1014
const outPath = path.join(root, 'app.log');
@@ -43,6 +47,7 @@ test('rotation rejects a final app.log symlink without touching its target', ()
4347
assertThrowsAppError(() => rotateAppLogIfNeeded(outPath, { maxBytes: 1, maxRotatedFiles: 1 }), {
4448
code: 'COMMAND_FAILED',
4549
message: /must not be a symbolic link/,
50+
hint: NOT_REGULAR_FILE_HINT,
4651
});
4752
expect(fs.readFileSync(outsidePath, 'utf8')).toBe('outside');
4853
expect(fs.lstatSync(outPath).isSymbolicLink()).toBe(true);

‎src/utils/__tests__/verified-file.test.ts‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,14 @@ import os from 'node:os';
33
import path from 'node:path';
44
import { afterEach, expect, test, vi } from 'vitest';
55
import { assertThrowsAppError } from '../../__tests__/test-utils/index.ts';
6+
7+
// The recovery hints are pinned as literals, not imported from the module under test: an
8+
// assertion that compares the constant to itself stays green when the constant is deleted or
9+
// reworded, which is the whole behaviour #1792 adds (ADR 0010 — errors say how to recover).
10+
const NOT_REGULAR_FILE_HINT =
11+
'agent-device only reads and writes regular files at this path. Remove the symbolic link or special file there and retry.';
12+
const CONCURRENT_REPLACEMENT_HINT =
13+
'Another process replaced the file at this path while it was being opened. Stop the concurrent writer, then retry.';
614
import {
715
openVerifiedFileForAppend,
816
openVerifiedFileForRead,
@@ -51,7 +59,7 @@ test.each(['read', 'append', 'truncate'] as const)(
5159
: openVerifiedFileForTruncate(pathname);
5260
if (descriptor !== undefined) fs.closeSync(descriptor);
5361
},
54-
{ code: 'COMMAND_FAILED', message: /must be a regular file/ },
62+
{ code: 'COMMAND_FAILED', message: /must be a regular file/, hint: NOT_REGULAR_FILE_HINT },
5563
);
5664
expect(fs.readFileSync(outside, 'utf8')).toBe('outside');
5765
},
@@ -77,6 +85,7 @@ test('reports a typed failure when the file is swapped while it is being opened'
7785
assertThrowsAppError(() => openVerifiedFileForRead(pathname), {
7886
code: 'COMMAND_FAILED',
7987
message: /identity changed while it was opened/,
88+
hint: CONCURRENT_REPLACEMENT_HINT,
8089
});
8190
});
8291

@@ -90,6 +99,7 @@ test('reports a typed failure when a create keeps losing the identity race', ()
9099
assertThrowsAppError(() => openVerifiedFileForAppend(pathname), {
91100
code: 'COMMAND_FAILED',
92101
message: /could not be opened without an identity race/,
102+
hint: CONCURRENT_REPLACEMENT_HINT,
93103
});
94104
});
95105

0 commit comments

Comments
 (0)