Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Name the wait that lost instead of a bare vitest timeout (#4767)

Nick Gomez6d8a2851a129
diff --git a/packages/server/package.json b/packages/server/package.json
index 5477052f7..a0823d66b 100644
--- a/packages/server/package.json
+++ b/packages/server/package.json
@@ -73,12 +73,13 @@
"scripts": {
"build": "tsdown && pnpm run build:skill-bundles",
"build:skill-bundles": "tsx scripts/build-skill-bundles.ts",
- "typecheck": "pnpm run typecheck:bash && tsc",
+ "typecheck": "pnpm run typecheck:bash && pnpm run typecheck:test-helper-callers && tsc",
"test": "vitest run",
"test:network": "vitest run --config vitest.network.config.ts",
"measure:generated-index-sweep": "node --import tsx --conditions=development measure-generated-index-sweep.ts",
"measure:observer-a-drain": "node --import tsx --conditions=development measure-observer-a-drain.ts",
- "typecheck:bash": "tsc -p tsconfig.bash.json"
+ "typecheck:bash": "tsc -p tsconfig.bash.json",
+ "typecheck:test-helper-callers": "tsc --noEmit -p tsconfig.test-helper-callers.json"
},
"devDependencies": {
"@types/mdast": "^4.0.4",
diff --git a/packages/server/src/expect-stable.test-helper.ts b/packages/server/src/expect-stable.test-helper.ts
new file mode 100644
index 000000000..5a7d66136
--- /dev/null
+++ b/packages/server/src/expect-stable.test-helper.ts
@@ -0,0 +1,41 @@
+const PRIMITIVE_READ_TYPES = new Set(['string', 'number', 'bigint', 'boolean', 'undefined']);
+
+export interface ExpectStableOptions {
+ durationMs?: number;
+ pollMs?: number;
+}
+
+function readHeld<T>(held: string, read: () => T): T {
+ try {
+ return read();
+ } catch (thrown) {
+ const message = thrown instanceof Error ? thrown.message : String(thrown);
+ const wrapped = new Error(`while holding ${held}: ${message}`, { cause: thrown });
+ const originalStack = thrown instanceof Error ? thrown.stack : undefined;
+ if (originalStack !== undefined) {
+ wrapped.stack = originalStack.replace(message, () => wrapped.message);
+ }
+ throw wrapped;
+ }
+}
+
+export async function expectStable<T extends string | number | bigint | boolean | null | undefined>(
+ held: string,
+ read: () => T,
+ { durationMs = 600, pollMs = 50 }: ExpectStableOptions = {},
+): Promise<T> {
+ const initial = readHeld(held, read);
+ if (initial !== null && !PRIMITIVE_READ_TYPES.has(typeof initial)) {
+ throw new Error(
+ `${held} was read as ${typeof initial}, but expectStable holds a value by identity, which equals value equality only for a primitive, so read a string, number, bigint, boolean, null or undefined instead`,
+ );
+ }
+ const deadline = Date.now() + durationMs;
+ while (Date.now() < deadline) {
+ if (readHeld(held, read) !== initial) {
+ throw new Error(`${held} changed during a ${durationMs}ms stability window`);
+ }
+ await new Promise((resolve) => setTimeout(resolve, pollMs));
+ }
+ return initial;
+}
diff --git a/packages/server/src/expect-stable.test.ts b/packages/server/src/expect-stable.test.ts
new file mode 100644
index 000000000..d60549547
--- /dev/null
+++ b/packages/server/src/expect-stable.test.ts
@@ -0,0 +1,148 @@
+import { readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { describe, expect, test } from 'vitest';
+import { expectStable } from './expect-stable.test-helper.ts';
+
+describe('expectStable', () => {
+ test('names the value and the window when the value changes mid-window', async () => {
+ let reads = 0;
+ const read = () => {
+ reads += 1;
+ return reads === 1 ? 'baseline bytes' : 'clobbered bytes';
+ };
+
+ await expect(
+ expectStable('notes.md on disk', read, { durationMs: 200, pollMs: 10 }),
+ ).rejects.toThrow('notes.md on disk changed during a 200ms stability window');
+ });
+
+ test('catches a change that only surfaces several polls into the window', async () => {
+ let reads = 0;
+ let value = 'baseline bytes';
+ const clobberOnRead = 5;
+ const read = () => {
+ reads += 1;
+ if (reads === clobberOnRead) value = 'clobbered bytes';
+ return value;
+ };
+
+ await expect(
+ expectStable('notes.md on disk', read, { durationMs: 1_000, pollMs: 10 }),
+ ).rejects.toThrow('notes.md on disk changed during a 1000ms stability window');
+ expect(reads).toBe(clobberOnRead);
+ });
+
+ test('resolves with the value it read when that value holds for the whole window', async () => {
+ const held = await expectStable('notes.md on disk', () => 'baseline bytes', {
+ durationMs: 120,
+ pollMs: 10,
+ });
+
+ expect(held).toBe('baseline bytes');
+ });
+
+ test('holds a number read, the shape the fragment call sites take', async () => {
+ const held = await expectStable('the default fragment child count', () => 3, {
+ durationMs: 120,
+ pollMs: 10,
+ });
+
+ expect(held).toBe(3);
+ });
+
+ test('rejects an object read, which identity cannot hold', async () => {
+ const rejected = expectStable(
+ 'the default fragment',
+ // @ts-expect-error an object read is what the primitive constraint and the runtime guard both reject
+ () => ({ children: 1 }),
+ { durationMs: 120, pollMs: 10 },
+ );
+
+ await expect(rejected).rejects.toThrow(
+ 'the default fragment was read as object, but expectStable holds a value by identity, which equals value equality only for a primitive, so read a string, number, bigint, boolean, null or undefined instead',
+ );
+ });
+
+ test('a throwing first read names the value held and keeps the original message', async () => {
+ const read = () => {
+ throw new Error('ENOENT: no such file or directory, open notes.md');
+ };
+
+ await expect(
+ expectStable('notes.md on disk', read, { durationMs: 200, pollMs: 10 }),
+ ).rejects.toThrow(
+ 'while holding notes.md on disk: ENOENT: no such file or directory, open notes.md',
+ );
+ });
+
+ test('a read that starts throwing mid-window names the value held', async () => {
+ let reads = 0;
+ const read = () => {
+ reads += 1;
+ if (reads > 1) throw new Error('EACCES: permission denied, open notes.md');
+ return 'baseline bytes';
+ };
+
+ await expect(
+ expectStable('notes.md on disk', read, { durationMs: 1_000, pollMs: 10 }),
+ ).rejects.toThrow('while holding notes.md on disk: EACCES: permission denied, open notes.md');
+ });
+
+ test('names the value held when the read throws something that is not an Error', async () => {
+ const read = () => {
+ throw 'the watcher handle went away';
+ };
+
+ await expect(
+ expectStable('notes.md on disk', read, { durationMs: 200, pollMs: 10 }),
+ ).rejects.toThrow('while holding notes.md on disk: the watcher handle went away');
+ });
+
+ test('keeps the thrown error as the cause, so its own properties stay readable', async () => {
+ const missing = join(tmpdir(), 'expect-stable-absent-notes.md');
+
+ await expect(
+ expectStable('notes.md on disk', () => readFileSync(missing, 'utf8'), {
+ durationMs: 200,
+ pollMs: 10,
+ }),
+ ).rejects.toHaveProperty('cause.code', 'ENOENT');
+ });
+
+ test('keeps the frames of the read that threw, not the frames of the wrapper', async () => {
+ const missing = join(tmpdir(), 'expect-stable-absent-notes.md');
+
+ await expect(
+ expectStable('notes.md on disk', () => readFileSync(missing, 'utf8'), {
+ durationMs: 200,
+ pollMs: 10,
+ }),
+ ).rejects.toHaveProperty('stack', expect.stringMatching(/\n\s+at \S*readFileSync\b/));
+ });
+
+ test('keeps a cause chain deeper than one link, the way the origin stays reachable', async () => {
+ const read = () => {
+ throw new Error('the watcher could not re-open notes.md', {
+ cause: new Error('EACCES: permission denied, open notes.md'),
+ });
+ };
+
+ await expect(
+ expectStable('notes.md on disk', read, { durationMs: 200, pollMs: 10 }),
+ ).rejects.toHaveProperty('cause.cause.message', 'EACCES: permission denied, open notes.md');
+ });
+
+ test('rejects a read whose declared type lies, which the constraint cannot reach', async () => {
+ const readsAnObjectButSaysString = (() => ({ children: 1 })) as unknown as () => string;
+
+ await expect(
+ expectStable('the default fragment', readsAnObjectButSaysString, {
+ durationMs: 120,
+ pollMs: 10,
+ }),
+ ).rejects.toThrow(
+ 'the default fragment was read as object, but expectStable holds a value by identity',
+ );
+ });
+});
diff --git a/packages/server/src/file-watcher-chokidar-fallback.test.ts b/packages/server/src/file-watcher-chokidar-fallback.test.ts
index 604cd59fc..ea13bd2ed 100644
--- a/packages/server/src/file-watcher-chokidar-fallback.test.ts
+++ b/packages/server/src/file-watcher-chokidar-fallback.test.ts
@@ -11,6 +11,7 @@ import {
startWatcher,
writeTracker,
} from './file-watcher.ts';
+import { waitWithinTestBudget } from './wait-within-test-budget.test-helper.ts';
describe('isChokidarPathIgnored — stats matrix', () => {
let tmpDir: string;
@@ -82,15 +83,6 @@ describe('chokidar backend — live subfolder watching (forceBackend)', () => {
await rm(tmpDir, { recursive: true, force: true });
});
- async function until(predicate: () => boolean, timeoutMs = 15_000): Promise<boolean> {
- const deadline = Date.now() + timeoutMs;
- while (Date.now() < deadline) {
- if (predicate()) return true;
- await new Promise((r) => setTimeout(r, 40));
- }
- return predicate();
- }
-
test('edits to a pre-existing subfolder doc dispatch a DiskEvent', async () => {
const filter = createContentFilter({ projectDir: tmpDir, contentDir });
const events: DiskEvent[] = [];
@@ -99,14 +91,18 @@ describe('chokidar backend — live subfolder watching (forceBackend)', () => {
});
try {
writeFileSync(resolve(contentDir, 'root.md'), '# Root edited\n');
- expect(
- await until(() => events.some((e) => e.kind === 'update' && e.docName === 'root')),
- ).toBe(true);
+ await waitWithinTestBudget(
+ "an update DiskEvent for 'root'",
+ () => events.some((e) => e.kind === 'update' && e.docName === 'root'),
+ { timeoutMs: 15_000, pollMs: 40 },
+ );
writeFileSync(resolve(contentDir, 'sub', 'note.md'), '# Note edited\n\n[Gone](./gone)\n');
- expect(
- await until(() => events.some((e) => e.kind === 'update' && e.docName === 'sub/note')),
- ).toBe(true);
+ await waitWithinTestBudget(
+ "an update DiskEvent for 'sub/note'",
+ () => events.some((e) => e.kind === 'update' && e.docName === 'sub/note'),
+ { timeoutMs: 15_000, pollMs: 40 },
+ );
} finally {
await handle.unsubscribe();
}
@@ -120,19 +116,20 @@ describe('chokidar backend — live subfolder watching (forceBackend)', () => {
});
try {
mkdirSync(resolve(contentDir, 'fresh'));
- expect(
- await until(() =>
- events.some((e) => e.kind === 'folder-create' && e.relativePath === 'fresh'),
- ),
- ).toBe(true);
+ await waitWithinTestBudget(
+ "a folder-create DiskEvent for the new 'fresh' subfolder",
+ () => events.some((e) => e.kind === 'folder-create' && e.relativePath === 'fresh'),
+ { timeoutMs: 15_000, pollMs: 40 },
+ );
writeFileSync(resolve(contentDir, 'fresh', 'child.md'), '# Child\n');
- expect(
- await until(() =>
+ await waitWithinTestBudget(
+ "a create or update DiskEvent for 'fresh/child'",
+ () =>
events.some(
(e) => (e.kind === 'create' || e.kind === 'update') && e.docName === 'fresh/child',
),
- ),
- ).toBe(true);
+ { timeoutMs: 15_000, pollMs: 40 },
+ );
} finally {
await handle.unsubscribe();
}
@@ -148,9 +145,11 @@ describe('chokidar backend — live subfolder watching (forceBackend)', () => {
mkdirSync(resolve(contentDir, 'node_modules', 'dep'), { recursive: true });
writeFileSync(resolve(contentDir, 'node_modules', 'dep', 'readme.md'), '# Dep\n');
writeFileSync(resolve(contentDir, 'root.md'), '# Root sentinel\n');
- expect(
- await until(() => events.some((e) => e.kind === 'update' && e.docName === 'root')),
- ).toBe(true);
+ await waitWithinTestBudget(
+ "the 'root' sentinel update DiskEvent that proves the watcher is live",
+ () => events.some((e) => e.kind === 'update' && e.docName === 'root'),
+ { timeoutMs: 15_000, pollMs: 40 },
+ );
expect(
events.some((e) => 'docName' in e && String(e.docName).startsWith('node_modules')),
).toBe(false);
@@ -176,15 +175,6 @@ describe('chokidar backend — templates-as-content watching (forceBackend)', ()
await rm(tmpDir, { recursive: true, force: true });
});
- async function until(predicate: () => boolean, timeoutMs = 6000): Promise<boolean> {
- const deadline = Date.now() + timeoutMs;
- while (Date.now() < deadline) {
- if (predicate()) return true;
- await new Promise((r) => setTimeout(r, 40));
- }
- return predicate();
- }
-
test('a template created in a brand-new .ok/templates folder dispatches a DiskEvent', async () => {
const filter = createContentFilter({ projectDir: tmpDir, contentDir });
const events: DiskEvent[] = [];
@@ -195,16 +185,18 @@ describe('chokidar backend — templates-as-content watching (forceBackend)', ()
const target = resolve(contentDir, 'notes', '.ok', 'templates', 'standup.md');
mkdirSync(resolve(target, '..'), { recursive: true });
const src = '---\ntitle: Standup\ndescription: a standup template\n---\n\n# {{date}}\n';
- expect(
- await until(() => {
+ await waitWithinTestBudget(
+ "a create or update DiskEvent for 'notes/.ok/templates/standup'",
+ () => {
writeFileSync(target, src);
return events.some(
(e) =>
(e.kind === 'create' || e.kind === 'update') &&
e.docName === 'notes/.ok/templates/standup',
);
- }),
- ).toBe(true);
+ },
+ { timeoutMs: 6_000, pollMs: 40 },
+ );
} finally {
await handle.unsubscribe();
}
@@ -221,11 +213,11 @@ describe('chokidar backend — templates-as-content watching (forceBackend)', ()
const target = resolve(contentDir, '.ok', 'templates', 'daily.md');
const conflicted = '# Daily\n\n<<<<<<< HEAD\nours\n=======\ntheirs\n>>>>>>> branch\n';
writeFileSync(target, conflicted);
- expect(
- await until(() =>
- events.some((e) => e.kind === 'conflict' && e.docName === '.ok/templates/daily'),
- ),
- ).toBe(true);
+ await waitWithinTestBudget(
+ "a conflict DiskEvent for '.ok/templates/daily'",
+ () => events.some((e) => e.kind === 'conflict' && e.docName === '.ok/templates/daily'),
+ { timeoutMs: 6_000, pollMs: 40 },
+ );
} finally {
await handle.unsubscribe();
}
diff --git a/packages/server/src/managed-artifact-watcher.test.ts b/packages/server/src/managed-artifact-watcher.test.ts
index 06d80b211..5aa0232f9 100644
--- a/packages/server/src/managed-artifact-watcher.test.ts
+++ b/packages/server/src/managed-artifact-watcher.test.ts
@@ -7,6 +7,7 @@ import {
type ManagedArtifactWatcherUnsubscribe,
startManagedArtifactWatcher,
} from './managed-artifact-watcher.ts';
+import { waitWithinTestBudget } from './wait-within-test-budget.test-helper.ts';
let root: string;
let cleanup: ManagedArtifactWatcherUnsubscribe | null = null;
@@ -20,15 +21,6 @@ afterEach(async () => {
rmSync(root, { recursive: true, force: true });
});
-async function eventually(predicate: () => boolean, timeoutMs = 20_000): Promise<void> {
- const start = Date.now();
- while (Date.now() - start < timeoutMs) {
- if (predicate()) return;
- await new Promise((r) => setTimeout(r, 50));
- }
- throw new Error('eventually: predicate never became true');
-}
-
const RUNNING_IN_CI = Boolean(process.env.CI);
describe.skipIf(RUNNING_IN_CI)('startManagedArtifactWatcher', () => {
@@ -42,7 +34,11 @@ describe.skipIf(RUNNING_IN_CI)('startManagedArtifactWatcher', () => {
const leaf = resolve(skillDir, 'SKILL.md');
writeFileSync(leaf, 'v1', 'utf-8');
- await eventually(() => seen.some(([p, c]) => p === leaf && c === 'v1'));
+ await waitWithinTestBudget(
+ "the watcher to report the new SKILL.md with its 'v1' contents",
+ () => seen.some(([p, c]) => p === leaf && c === 'v1'),
+ { timeoutMs: 20_000, pollMs: 50 },
+ );
}, 25_000);
test('fires onUnlink (not onChange) when a SKILL.md is deleted', async () => {
@@ -62,7 +58,11 @@ describe.skipIf(RUNNING_IN_CI)('startManagedArtifactWatcher', () => {
rmSync(leaf, { force: true });
- await eventually(() => unlinked.includes(leaf));
+ await waitWithinTestBudget(
+ 'the watcher to report the deleted SKILL.md as unlinked',
+ () => unlinked.includes(leaf),
+ { timeoutMs: 20_000, pollMs: 50 },
+ );
expect(changed).not.toContain(leaf);
}, 25_000);
@@ -79,7 +79,11 @@ describe.skipIf(RUNNING_IN_CI)('startManagedArtifactWatcher', () => {
writeFileSync(resolve(skillDir, 'NOTES.md'), 'noise', 'utf-8');
writeFileSync(leaf, 'v2', 'utf-8');
- await eventually(() => contents.includes('v2'));
+ await waitWithinTestBudget(
+ "the watcher to report the edited SKILL.md with its 'v2' contents",
+ () => contents.includes('v2'),
+ { timeoutMs: 20_000, pollMs: 50 },
+ );
expect(contents).not.toContain('noise');
}, 25_000);
});
diff --git a/packages/server/src/persistence-tripwire-block.test.ts b/packages/server/src/persistence-tripwire-block.test.ts
index 3d338fd0f..a376905b5 100644
--- a/packages/server/src/persistence-tripwire-block.test.ts
+++ b/packages/server/src/persistence-tripwire-block.test.ts
@@ -5,8 +5,10 @@ import { updateYFragment } from '@tiptap/y-tiptap';
import simpleGit from 'simple-git';
import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
import type * as Y from 'yjs';
+import { expectStable } from './expect-stable.test-helper.ts';
import { mdManager, schema } from './md-manager.ts';
import { createServer } from './server-factory.ts';
+import { waitWithinTestBudget } from './wait-within-test-budget.test-helper.ts';
const FIXTURE_DIR = resolve(import.meta.dirname, 'persistence-tripwire.fixtures');
@@ -46,33 +48,6 @@ function replaceFragmentFromMarkdown(doc: Y.Doc, markdown: string): void {
);
}
-async function waitForCondition(
- predicate: () => boolean,
- { timeoutMs = 5_000, pollMs = 25 }: { timeoutMs?: number; pollMs?: number } = {},
-): Promise<void> {
- const deadline = Date.now() + timeoutMs;
- while (Date.now() < deadline) {
- if (predicate()) return;
- await new Promise((r) => setTimeout(r, pollMs));
- }
- throw new Error(`waitForCondition timed out after ${timeoutMs}ms`);
-}
-
-async function expectStable<T>(
- read: () => T,
- { durationMs = 600, pollMs = 50 }: { durationMs?: number; pollMs?: number } = {},
-): Promise<T> {
- const initial = read();
- const deadline = Date.now() + durationMs;
- while (Date.now() < deadline) {
- if (read() !== initial) {
- throw new Error('value changed during stability window');
- }
- await new Promise((r) => setTimeout(r, pollMs));
- }
- return initial;
-}
-
describe('persistence onStoreDocument tripwire', () => {
let fixture: Fixture;
@@ -115,19 +90,30 @@ describe('persistence onStoreDocument tripwire', () => {
const doubledChildren = serverDoc.getXmlFragment('default').length;
expect(doubledChildren).toBe(baseChildren * 2);
- await waitForCondition(() => {
- return warnSpy.mock.calls.some((call) => {
- const arg = String(call[0] ?? '');
- return arg.includes('"event":"ok-persistence-duplication-blocked"');
- });
- });
+ await waitWithinTestBudget(
+ 'an ok-persistence-duplication-blocked warning to be logged',
+ () =>
+ warnSpy.mock.calls.some((call) => {
+ const arg = String(call[0] ?? '');
+ return arg.includes('"event":"ok-persistence-duplication-blocked"');
+ }),
+ { timeoutMs: 5_000 },
+ );
- await expectStable(() => readFileSync(docPath, 'utf-8'));
+ await expectStable(`${docName}.md on disk`, () => readFileSync(docPath, 'utf-8'));
expect(readFileSync(docPath, 'utf-8')).toBe(baselineBytes);
- await waitForCondition(() => serverDoc.getXmlFragment('default').length === baseChildren);
+ await waitWithinTestBudget(
+ `the ${docName} fragment to be rolled back to its baseline child count`,
+ () => serverDoc.getXmlFragment('default').length === baseChildren,
+ { timeoutMs: 5_000 },
+ );
expect(serverDoc.getXmlFragment('default').length).toBe(baseChildren);
- await waitForCondition(() => serverDoc.getText('source').toString() === baselineBytes);
+ await waitWithinTestBudget(
+ `the ${docName} source text to be rolled back to the baseline bytes`,
+ () => serverDoc.getText('source').toString() === baselineBytes,
+ { timeoutMs: 5_000 },
+ );
expect(serverDoc.getText('source').toString()).toBe(baselineBytes);
const blockedCalls = warnSpy.mock.calls
@@ -189,7 +175,11 @@ describe('persistence onStoreDocument tripwire', () => {
replaceFragmentFromMarkdown(serverDoc, candidateMarkdown);
const baselineSize = readFileSync(docPath, 'utf-8').length;
- await waitForCondition(() => readFileSync(docPath, 'utf-8').length !== baselineSize);
+ await waitWithinTestBudget(
+ `${docName}.md on disk to change size from its baseline`,
+ () => readFileSync(docPath, 'utf-8').length !== baselineSize,
+ { timeoutMs: 5_000 },
+ );
const finalContent = readFileSync(docPath, 'utf-8');
expect(finalContent.length).toBeGreaterThan(baselineSize);
diff --git a/packages/server/src/persistence-tripwire-paste.test.ts b/packages/server/src/persistence-tripwire-paste.test.ts
index 4924097f8..a7f90a444 100644
--- a/packages/server/src/persistence-tripwire-paste.test.ts
+++ b/packages/server/src/persistence-tripwire-paste.test.ts
@@ -21,6 +21,7 @@ import {
OK_PATH_UNRESOLVABLE,
OK_STORE_REFUSED,
} from './document-durability-state.ts';
+import { expectStable } from './expect-stable.test-helper.ts';
import { getLogger } from './logger.ts';
import { lossCaptureCurrentPath, parseLossCaptureLines } from './loss-capture.ts';
import { mdManager, schema } from './md-manager.ts';
@@ -30,6 +31,7 @@ import { classifyDuplication } from './persistence-tripwire.ts';
import { createServer } from './server-factory.ts';
import { initShadowRepo, type ShadowHandle, shadowGit } from './shadow-repo.ts';
import { getDocumentHistory } from './timeline-query.ts';
+import { waitWithinTestBudget } from './wait-within-test-budget.test-helper.ts';
const FIXTURE_DIR = resolve(import.meta.dirname, 'persistence-tripwire.fixtures');
@@ -70,31 +72,6 @@ function occurrences(haystack: string, needle: string): number {
return n;
}
-async function waitFor(
- predicate: () => boolean,
- { timeoutMs = 8_000, pollMs = 25 }: { timeoutMs?: number; pollMs?: number } = {},
-): Promise<void> {
- const deadline = Date.now() + timeoutMs;
- while (Date.now() < deadline) {
- if (predicate()) return;
- await new Promise((r) => setTimeout(r, pollMs));
- }
- throw new Error(`waitFor timed out after ${timeoutMs}ms`);
-}
-
-async function expectStable<T>(
- read: () => T,
- { durationMs = 700, pollMs = 50 }: { durationMs?: number; pollMs?: number } = {},
-): Promise<T> {
- const initial = read();
- const deadline = Date.now() + durationMs;
- while (Date.now() < deadline) {
- if (read() !== initial) throw new Error('value changed during stability window');
- await new Promise((r) => setTimeout(r, pollMs));
- }
- return initial;
-}
-
interface Rig {
tmpDir: string;
shadow: ShadowHandle;
@@ -185,7 +162,11 @@ describe('persistence tripwire vs a whole-document paste', () => {
const frag = serverDoc.getXmlFragment('default');
replaceFragment(serverDoc, TYPED_CHILDREN);
- await waitFor(() => readFileSync(docPath, 'utf-8').length > 0);
+ await waitWithinTestBudget(
+ `the ${docName}.md to be written to disk`,
+ () => readFileSync(docPath, 'utf-8').length > 0,
+ { timeoutMs: 8_000 },
+ );
const baseline = readFileSync(docPath, 'utf-8');
expect(baseline).toBe(USER_DOC);
@@ -193,8 +174,18 @@ describe('persistence tripwire vs a whole-document paste', () => {
replaceFragment(serverDoc, [...kids, ...kids]);
expect(occurrences(serverDoc.getText('source').toString(), USER_DOC_LINE)).toBe(2);
- await waitFor(() => readFileSync(docPath, 'utf-8') !== baseline);
- const persisted = await expectStable(() => readFileSync(docPath, 'utf-8'));
+ await waitWithinTestBudget(
+ `${docName}.md on disk to change from its settled baseline`,
+ () => readFileSync(docPath, 'utf-8') !== baseline,
+ { timeoutMs: 8_000 },
+ );
+ const persisted = await expectStable(
+ `${docName}.md on disk`,
+ () => readFileSync(docPath, 'utf-8'),
+ {
+ durationMs: 700,
+ },
+ );
expect(occurrences(persisted, USER_DOC_LINE)).toBe(2);
expect(persisted.length).toBeGreaterThan(baseline.length);
@@ -265,17 +256,33 @@ describe('persistence tripwire vs a whole-document paste', () => {
replaceFragment(serverDoc, doubledJson.content ?? []);
expect(serverDoc.getXmlFragment('default').length).toBe(baseChildren * 2);
- await waitFor(() => blockedEvents(warnSpy).length > 0);
+ await waitWithinTestBudget(
+ 'an ok-persistence-duplication-blocked warning to be logged',
+ () => blockedEvents(warnSpy).length > 0,
+ { timeoutMs: 8_000 },
+ );
- await expectStable(() => readFileSync(docPath, 'utf-8'));
+ await expectStable(`${docName}.md on disk`, () => readFileSync(docPath, 'utf-8'), {
+ durationMs: 700,
+ });
expect(readFileSync(docPath, 'utf-8')).toBe(baselineBytes);
- await waitFor(() => serverDoc.getXmlFragment('default').length === baseChildren);
- await waitFor(() => serverDoc.getText('source').toString() === baselineBytes);
+ await waitWithinTestBudget(
+ `the ${docName} fragment to be rolled back to its baseline child count`,
+ () => serverDoc.getXmlFragment('default').length === baseChildren,
+ { timeoutMs: 8_000 },
+ );
+ await waitWithinTestBudget(
+ `the ${docName} source text to be rolled back to the baseline bytes`,
+ () => serverDoc.getText('source').toString() === baselineBytes,
+ { timeoutMs: 8_000 },
+ );
expect(getMetrics().persistenceDuplicationReset).toBe(1);
- await waitFor(() => getMetrics().persistenceDuplicationResetCheckpointCreated >= 1, {
- timeoutMs: 10_000,
- });
+ await waitWithinTestBudget(
+ 'a persistence-duplication-reset checkpoint to be created',
+ () => getMetrics().persistenceDuplicationResetCheckpointCreated >= 1,
+ { timeoutMs: 10_000 },
+ );
const shas = (
await shadowGit(rig.shadow).raw(
'for-each-ref',
@@ -356,7 +363,11 @@ describe('persistence tripwire with an absent reconciled base', () => {
if (!serverDoc) return;
const baseChildren = serverDoc.getXmlFragment('default').length;
expect(baseChildren).toBeGreaterThan(0);
- await waitFor(() => server.durabilityState.getReconciledBase(docName) === baseMarkdown);
+ await waitWithinTestBudget(
+ `the reconciled base for ${docName} to be adopted from disk`,
+ () => server.durabilityState.getReconciledBase(docName) === baseMarkdown,
+ { timeoutMs: 8_000 },
+ );
server.durabilityState.deleteReconciledBase(docName);
expect(server.durabilityState.getReconciledBase(docName)).toBeUndefined();
@@ -370,14 +381,22 @@ describe('persistence tripwire with an absent reconciled base', () => {
{ timeout: 10_000, interval: 25 },
);
- await expectStable(() => readFileSync(docPath, 'utf-8'));
+ await expectStable(`${docName}.md on disk`, () => readFileSync(docPath, 'utf-8'), {
+ durationMs: 700,
+ });
expect(readFileSync(docPath, 'utf-8')).toBe(baseMarkdown);
- await waitFor(() => serverDoc.getText('source').toString() === baseMarkdown);
+ await waitWithinTestBudget(
+ `the ${docName} source text to be reset to the base markdown`,
+ () => serverDoc.getText('source').toString() === baseMarkdown,
+ { timeoutMs: 8_000 },
+ );
expect(getMetrics().persistenceDuplicationSpared).toBe(0);
- await waitFor(() => getMetrics().persistenceDuplicationResetCheckpointCreated >= 1, {
- timeoutMs: 10_000,
- });
+ await waitWithinTestBudget(
+ 'a persistence-duplication-reset checkpoint to be created',
+ () => getMetrics().persistenceDuplicationResetCheckpointCreated >= 1,
+ { timeoutMs: 10_000 },
+ );
const hist = await getDocumentHistory(rig.shadow, { docName }, '');
expect(hist.entries.some((e) => e.checkpoint?.kind === 'persistence-duplication-reset')).toBe(
true,
@@ -419,16 +438,28 @@ describe('persistence tripwire with an absent reconciled base', () => {
const settledJson = mdManager.parseWithFallback(settledMarkdown) as { content?: unknown[] };
replaceFragment(serverDoc, settledJson.content ?? []);
- await waitFor(() => readFileSync(docPath, 'utf-8').length > baseMarkdown.length);
+ await waitWithinTestBudget(
+ `the settled write to reach ${docName}.md on disk`,
+ () => readFileSync(docPath, 'utf-8').length > baseMarkdown.length,
+ { timeoutMs: 8_000 },
+ );
const settledStored = readFileSync(docPath, 'utf-8');
- await waitFor(() => server.durabilityState.getReconciledBase(docName) === settledStored);
+ await waitWithinTestBudget(
+ `the reconciled base for ${docName} to catch up to the settled bytes on disk`,
+ () => server.durabilityState.getReconciledBase(docName) === settledStored,
+ { timeoutMs: 8_000 },
+ );
server.durabilityState.deleteReconciledBase(docName);
expect(server.durabilityState.getReconciledBase(docName)).toBeUndefined();
const kids = liveChildren(serverDoc.getXmlFragment('default'));
replaceFragment(serverDoc, [...kids, ...kids]);
- await waitFor(() => occurrences(serverDoc.getText('source').toString(), settledMarker) === 2);
+ await waitWithinTestBudget(
+ 'the doubled paste to appear twice in the source text',
+ () => occurrences(serverDoc.getText('source').toString(), settledMarker) === 2,
+ { timeoutMs: 8_000 },
+ );
await vi.waitFor(
() => expect(getMetrics().persistenceDuplicationSpared).toBeGreaterThanOrEqual(1),
@@ -440,9 +471,15 @@ describe('persistence tripwire with an absent reconciled base', () => {
.filter((s) => s.includes('"event":"ok-persistence-duplication-spared"'));
expect(spared).toHaveLength(1);
- await waitFor(() => occurrences(readFileSync(docPath, 'utf-8'), settledMarker) === 2);
+ await waitWithinTestBudget(
+ `the doubled paste to reach ${docName}.md on disk`,
+ () => occurrences(readFileSync(docPath, 'utf-8'), settledMarker) === 2,
+ { timeoutMs: 8_000 },
+ );
const doubledDisk = readFileSync(docPath, 'utf-8');
- await expectStable(() => readFileSync(docPath, 'utf-8'));
+ await expectStable(`${docName}.md on disk`, () => readFileSync(docPath, 'utf-8'), {
+ durationMs: 700,
+ });
expect(readFileSync(docPath, 'utf-8')).toBe(doubledDisk);
expect(getMetrics().persistenceDuplicationReset).toBe(0);
diff --git a/packages/server/src/serialize-doc-vs-git-show-byte-equality.test.ts b/packages/server/src/serialize-doc-vs-git-show-byte-equality.test.ts
index 8d6a9ef90..7272d4497 100644
--- a/packages/server/src/serialize-doc-vs-git-show-byte-equality.test.ts
+++ b/packages/server/src/serialize-doc-vs-git-show-byte-equality.test.ts
@@ -7,6 +7,7 @@ import { describe as _bunDescribe, afterEach, beforeEach, expect, test, vi } fro
import { __resetQuiescenceForTests } from './bridge-quiescence.ts';
import { resetMetrics } from './metrics.ts';
import { createServer } from './server-factory.ts';
+import { waitWithinTestBudget } from './wait-within-test-budget.test-helper.ts';
function reconstructSerializeDoc(
hocuspocus: import('@hocuspocus/server').Hocuspocus,
@@ -43,18 +44,6 @@ async function setupFixture(): Promise<Fixture> {
};
}
-async function waitForCondition(
- predicate: () => boolean | Promise<boolean>,
- { timeoutMs = 5_000, pollMs = 25 }: { timeoutMs?: number; pollMs?: number } = {},
-): Promise<void> {
- const deadline = Date.now() + timeoutMs;
- while (Date.now() < deadline) {
- if (await predicate()) return;
- await new Promise((r) => setTimeout(r, pollMs));
- }
- throw new Error(`waitForCondition timed out after ${timeoutMs}ms`);
-}
-
beforeEach(() => {
resetMetrics();
__resetQuiescenceForTests();
@@ -94,10 +83,14 @@ describe('A3: serializeDoc(docName) byte-equals git show :<stage>:<file> when fr
await server.ready;
const conn = await server.hocuspocus.openDirectConnection(docName);
try {
- await waitForCondition(() => {
- const doc = server.hocuspocus.documents.get(docName);
- return doc?.getText('source').toString().includes('First paragraph.');
- });
+ await waitWithinTestBudget(
+ `the ${docName} source text to contain 'First paragraph.'`,
+ () => {
+ const doc = server.hocuspocus.documents.get(docName);
+ return doc?.getText('source').toString().includes('First paragraph.') === true;
+ },
+ { timeoutMs: 5_000 },
+ );
const fromYtext = reconstructSerializeDoc(server.hocuspocus, docName);
if (fromYtext === null) {
diff --git a/packages/server/src/serialize-doc-ytext.test.ts b/packages/server/src/serialize-doc-ytext.test.ts
index cff942e1d..a7f843668 100644
--- a/packages/server/src/serialize-doc-ytext.test.ts
+++ b/packages/server/src/serialize-doc-ytext.test.ts
@@ -6,6 +6,7 @@ import { describe as _vitestDescribe, afterEach, beforeEach, expect, test, vi }
import { __resetQuiescenceForTests } from './bridge-quiescence.ts';
import { resetMetrics } from './metrics.ts';
import { createServer } from './server-factory.ts';
+import { waitWithinTestBudget } from './wait-within-test-budget.test-helper.ts';
const describe = process.env.CI ? _vitestDescribe.skip : _vitestDescribe;
@@ -31,18 +32,6 @@ async function setupFixture(): Promise<Fixture> {
};
}
-async function waitForCondition(
- predicate: () => boolean,
- { timeoutMs = 5_000, pollMs = 25 }: { timeoutMs?: number; pollMs?: number } = {},
-): Promise<void> {
- const deadline = Date.now() + timeoutMs;
- while (Date.now() < deadline) {
- if (predicate()) return;
- await new Promise((r) => setTimeout(r, pollMs));
- }
- throw new Error(`waitForCondition timed out after ${timeoutMs}ms`);
-}
-
beforeEach(() => {
resetMetrics();
__resetQuiescenceForTests();
@@ -76,17 +65,20 @@ describe('FR-34: serializeDoc returns ytext bytes verbatim', () => {
try {
await server.ready;
const conn = await server.hocuspocus.openDirectConnection(docName);
- await waitForCondition(() => server.durabilityState.getReconciledBase(docName) !== undefined);
+ await waitWithinTestBudget(
+ `reconciledBase for ${docName} to be seeded from disk`,
+ () => server.durabilityState.getReconciledBase(docName) !== undefined,
+ { timeoutMs: 5_000 },
+ );
expect(server.durabilityState.getReconciledBase(docName)).toBe(initialContent);
const updatedContent = '---\n# Title Updated\n';
writeFileSync(docPath, updatedContent, 'utf-8');
- await waitForCondition(
+ await waitWithinTestBudget(
+ `reconciledBase for ${docName} to pick up the updated bytes from disk`,
() => server.durabilityState.getReconciledBase(docName) === updatedContent,
- {
- timeoutMs: 8_000,
- },
+ { timeoutMs: 8_000 },
);
expect(server.durabilityState.getReconciledBase(docName)).toBe(updatedContent);
@@ -128,18 +120,19 @@ describe('FR-35: setReconciledBase stores raw bytes uniformly across all paths',
try {
await server.ready;
const conn = await server.hocuspocus.openDirectConnection(docName);
- await waitForCondition(
+ await waitWithinTestBudget(
+ `reconciledBase for ${docName} to be seeded with the initial bytes`,
() => server.durabilityState.getReconciledBase(docName) === initialContent,
+ { timeoutMs: 5_000 },
);
const updatedContent = '---\n# Title\n\nA __strong__ paragraph.\n\nNew block.\n';
writeFileSync(docPath, updatedContent, 'utf-8');
- await waitForCondition(
+ await waitWithinTestBudget(
+ `reconciledBase for ${docName} to pick up the updated bytes from disk`,
() => server.durabilityState.getReconciledBase(docName) === updatedContent,
- {
- timeoutMs: 8_000,
- },
+ { timeoutMs: 8_000 },
);
const finalBase = server.durabilityState.getReconciledBase(docName);
@@ -147,10 +140,14 @@ describe('FR-35: setReconciledBase stores raw bytes uniformly across all paths',
expect(finalBase).toContain('---\n');
expect(finalBase).toContain('__strong__');
- await waitForCondition(() => {
- if (!existsSync(docPath)) return false;
- return readFileSync(docPath, 'utf-8') === updatedContent;
- });
+ await waitWithinTestBudget(
+ `${docName}.md on disk to hold the updated bytes`,
+ () => {
+ if (!existsSync(docPath)) return false;
+ return readFileSync(docPath, 'utf-8') === updatedContent;
+ },
+ { timeoutMs: 5_000 },
+ );
expect(readFileSync(docPath, 'utf-8')).toBe(updatedContent);
conn.disconnect();
diff --git a/packages/server/src/test-helper-caller-typecheck-coverage.test.ts b/packages/server/src/test-helper-caller-typecheck-coverage.test.ts
new file mode 100644
index 000000000..8e18660c7
--- /dev/null
+++ b/packages/server/src/test-helper-caller-typecheck-coverage.test.ts
@@ -0,0 +1,173 @@
+import { mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { type ParseError, parse as parseJsonc, printParseErrorCode } from 'jsonc-parser';
+import { describe, expect, onTestFinished, test } from 'vitest';
+
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const TSCONFIG = 'tsconfig.test-helper-callers.json';
+const TYPECHECK_SCRIPT = 'typecheck:test-helper-callers';
+
+const HELPERS = ['wait-within-test-budget.test-helper.ts', 'expect-stable.test-helper.ts'];
+
+const UNSCANNED_DIRS = new Set(['node_modules', 'dist', '.turbo']);
+
+const RELATIVE_SPECIFIER = /(?:\bfrom|\bimport\s*\()\s*'(\.{1,2}\/[^']*)'/g;
+
+function withoutTsExtension(specifier: string): string {
+ return specifier.replace(/\.ts$/, '');
+}
+
+function importsAHelper(source: string): boolean {
+ return [...source.matchAll(RELATIVE_SPECIFIER)].some((match) => {
+ const specifier = withoutTsExtension(match[1] ?? '');
+ return HELPERS.some((helper) => specifier.endsWith(`/${withoutTsExtension(helper)}`));
+ });
+}
+
+function filesUnder(dir: string, suffix: string): string[] {
+ return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+ const path = join(dir, entry.name);
+ if (entry.isDirectory()) {
+ return UNSCANNED_DIRS.has(entry.name) ? [] : filesUnder(path, suffix);
+ }
+ return entry.isFile() && entry.name.endsWith(suffix) ? [path] : [];
+ });
+}
+
+function callersOnDisk(): string[] {
+ return filesUnder(PACKAGE_ROOT, '.test.ts')
+ .filter((path) => importsAHelper(readFileSync(path, 'utf8')))
+ .map((path) => relative(PACKAGE_ROOT, path).replaceAll('\\', '/'))
+ .sort();
+}
+
+function helpersOnDisk(root: string = PACKAGE_ROOT): string[] {
+ return filesUnder(root, '.test-helper.ts').map((path) => basename(path));
+}
+
+function isStringArray(value: unknown): value is string[] {
+ return Array.isArray(value) && value.every((item) => typeof item === 'string');
+}
+
+function namedIn(source: string): string[] {
+ const errors: ParseError[] = [];
+ const config = parseJsonc(source, errors, { allowTrailingComma: true }) as unknown;
+ const parseError = errors[0];
+ if (parseError !== undefined) {
+ throw new Error(
+ `${TSCONFIG} did not parse: ${printParseErrorCode(parseError.error)} at offset ` +
+ `${parseError.offset}. jsonc-parser recovers past the damage and returns a partial ` +
+ 'value, so reading on would compare the callers on disk against whatever survived ' +
+ 'rather than against what the file declares, and report the difference as caller drift.',
+ );
+ }
+ const files: unknown = (config as { files?: unknown } | null)?.files;
+ if (!isStringArray(files)) {
+ throw new Error(
+ `${TSCONFIG} must declare files as an array of strings, the shape tsc requires: a ` +
+ 'different shape draws no parse error at all, and spreading it yields either nothing ' +
+ 'or a string split into its characters, which reads as every caller being unnamed.',
+ );
+ }
+ return [...files].sort();
+}
+
+function namedInConfig(): string[] {
+ return namedIn(readFileSync(resolve(PACKAGE_ROOT, TSCONFIG), 'utf8'));
+}
+
+function packageScripts(): Record<string, string> {
+ const manifest = JSON.parse(readFileSync(resolve(PACKAGE_ROOT, 'package.json'), 'utf8')) as {
+ scripts?: Record<string, string>;
+ };
+ return manifest.scripts ?? {};
+}
+
+describe('every caller of a shared test-only helper sits inside a typecheck program', () => {
+ test(`names in ${TSCONFIG} exactly the test files that import one`, () => {
+ const callers = callersOnDisk();
+ expect(
+ callers.length,
+ 'no test file in this package imports either helper, so this contract is asserting nothing',
+ ).toBeGreaterThan(0);
+ const named = namedInConfig();
+ expect(
+ {
+ unnamed: callers.filter((file) => !named.includes(file)),
+ stale: named.filter((file) => !callers.includes(file)),
+ },
+ `tsconfig.json excludes **/*.test.ts, so ${TSCONFIG} is the only program that reads these ` +
+ 'call sites: an unnamed caller lets a breaking helper signature change pass every ' +
+ 'compiler, and a stale name is a caller the program can no longer find. A name in ' +
+ 'files is always in the program, so naming a caller also obliges it to typecheck: ' +
+ 'admit a helper to HELPERS once every file importing it compiles, and until then ' +
+ 'leave the helper local to the file that needs it rather than sharing it.',
+ ).toEqual({ unnamed: [], stale: [] });
+ });
+
+ test(`reaches that program from the package typecheck script`, () => {
+ const scripts = packageScripts();
+ expect(
+ scripts[TYPECHECK_SCRIPT] ?? '',
+ `${TYPECHECK_SCRIPT} must compile ${TSCONFIG}`,
+ ).toContain(`-p ${TSCONFIG}`);
+ expect(
+ scripts.typecheck ?? '',
+ `${TSCONFIG} compiles nothing anyone runs unless typecheck chains ${TYPECHECK_SCRIPT}`,
+ ).toContain(TYPECHECK_SCRIPT);
+ });
+
+ test('detects a helper import written without its .ts extension', () => {
+ const importing = (specifier: string) => `import { waitWithinTestBudget } from '${specifier}';`;
+
+ expect(importsAHelper(importing('./wait-within-test-budget.test-helper.ts'))).toBe(true);
+ expect(
+ importsAHelper(importing('./wait-within-test-budget.test-helper')),
+ 'moduleResolution "bundler" resolves an extensionless relative import, so a caller ' +
+ 'spelled that way must still be found or it escapes the program unnamed',
+ ).toBe(true);
+ expect(importsAHelper(importing('node:path'))).toBe(false);
+ });
+
+ test('finds a helper whatever depth it sits at, which is what HELPERS can name', () => {
+ const root = mkdtempSync(join(tmpdir(), 'test-helper-scan-'));
+ onTestFinished(() => rmSync(root, { recursive: true, force: true }));
+ mkdirSync(join(root, 'nested', 'deeper'), { recursive: true });
+ writeFileSync(join(root, 'flat.test-helper.ts'), '');
+ writeFileSync(join(root, 'nested', 'deeper', 'buried.test-helper.ts'), '');
+
+ expect(
+ helpersOnDisk(root).sort(),
+ 'importsAHelper matches a helper by basename at any depth, so an existence scan that ' +
+ 'reads one directory level calls a nested helper missing and, through the assertion ' +
+ 'below, reports every caller of a helper that is present as already covered',
+ ).toEqual(['buried.test-helper.ts', 'flat.test-helper.ts']);
+ });
+
+ test('names in HELPERS only helpers that are on disk', () => {
+ const present = helpersOnDisk();
+ expect(
+ HELPERS.filter((helper) => !present.includes(helper)),
+ 'a helper renamed or removed leaves its entry matching nothing, and the guard then ' +
+ 'reports every caller of it as already covered',
+ ).toEqual([]);
+ });
+
+ test(`reads ${TSCONFIG} the way tsc does, and tells a broken file from caller drift`, () => {
+ expect(
+ namedIn('{\n // the callers\n "files": ["src/b.test.ts", "src/a.test.ts",],\n}'),
+ 'tsc compiles a tsconfig carrying comments and trailing commas, so a reader stricter ' +
+ 'than tsc would red on a config that builds',
+ ).toEqual(['src/a.test.ts', 'src/b.test.ts']);
+
+ expect(() => namedIn('{"files": ["src/a.test.ts"')).toThrow(/did not parse/);
+ expect(() => namedIn('{"files": "src/a.test.ts"}')).toThrow(/array of strings/);
+ expect(
+ () => namedIn('null'),
+ 'a bare null is valid JSON and draws no parse error, so without an object check the ' +
+ 'reader throws a raw TypeError from inside itself rather than either diagnostic it writes',
+ ).toThrow(/array of strings/);
+ });
+});
diff --git a/packages/server/src/wait-within-test-budget.test-helper.ts b/packages/server/src/wait-within-test-budget.test-helper.ts
new file mode 100644
index 000000000..9e962b8f1
--- /dev/null
+++ b/packages/server/src/wait-within-test-budget.test-helper.ts
@@ -0,0 +1,86 @@
+import { TestRunner } from 'vitest';
+
+const DEFAULT_POLL_MS = 25;
+const DEFAULT_REPORT_RESERVE_MS = 1_000;
+
+const realSetTimeout = globalThis.setTimeout;
+const realNow = Date.now;
+
+export interface WaitWithinTestBudgetOptions {
+ timeoutMs: number;
+ pollMs?: number;
+ reserveMs?: number;
+}
+
+export function remainingTestBudgetMs(nowMs: number = realNow()): number | undefined {
+ const currentTest = TestRunner.getCurrentTest();
+ if (currentTest === undefined || currentTest.concurrent === true) return undefined;
+ const result = currentTest.result;
+ if (result?.startTime === undefined) return undefined;
+ const timeout = currentTest.timeout;
+ if (!Number.isFinite(timeout) || timeout <= 0) return undefined;
+ if ((result.retryCount ?? 0) > 0 || (result.repeatCount ?? 0) > 0) return undefined;
+ return timeout - (nowMs - result.startTime);
+}
+
+function budgetNote(
+ budgetMs: number | undefined,
+ grantedMs: number,
+ timeoutMs: number,
+ reserveMs: number,
+): string {
+ if (budgetMs === undefined) {
+ return ", granted the full request: the test's own remaining budget could not be read";
+ }
+ if (grantedMs >= timeoutMs) return '';
+ if (grantedMs > 0) {
+ return `, clamped to ${grantedMs}ms to leave ${reserveMs}ms for this failure and the test's own teardown to run inside the test's timeout`;
+ }
+ if (budgetMs >= 0) {
+ return `, granted no time: only ${budgetMs}ms of the test's own timeout was left, at or below the ${reserveMs}ms reserved for this failure and the test's own teardown`;
+ }
+ return `, granted no time: the test's own timeout was already overdrawn by ${-budgetMs}ms when this wait began`;
+}
+
+function predicateFailure(what: string, thrown: unknown): Error {
+ const originalMessage = thrown instanceof Error ? thrown.message : String(thrown);
+ const failure = new Error(`while waiting for ${what}: ${originalMessage}`, {
+ cause: thrown,
+ });
+ const originalStack = thrown instanceof Error ? thrown.stack : undefined;
+ if (originalStack !== undefined) {
+ failure.stack = originalStack.replace(originalMessage, () => failure.message);
+ }
+ return failure;
+}
+
+export async function waitWithinTestBudget(
+ what: string,
+ predicate: () => boolean | Promise<boolean>,
+ options: WaitWithinTestBudgetOptions,
+): Promise<void> {
+ const { timeoutMs, pollMs = DEFAULT_POLL_MS, reserveMs = DEFAULT_REPORT_RESERVE_MS } = options;
+ const startedAt = realNow();
+ const budgetMs = remainingTestBudgetMs(startedAt);
+ const grantedMs = budgetMs === undefined ? timeoutMs : Math.min(timeoutMs, budgetMs - reserveMs);
+ const deadline = startedAt + grantedMs;
+
+ for (;;) {
+ let holds: boolean;
+ try {
+ holds = await predicate();
+ } catch (thrown) {
+ throw predicateFailure(what, thrown);
+ }
+ if (holds) return;
+ const leftMs = deadline - realNow();
+ if (leftMs <= 0) break;
+ await new Promise((resolve) => realSetTimeout(resolve, Math.min(pollMs, leftMs)));
+ }
+
+ const waitedMs = realNow() - startedAt;
+ const note = budgetNote(budgetMs, grantedMs, timeoutMs, reserveMs);
+ throw new Error(
+ `timed out waiting for ${what} after ${waitedMs}ms (requested ${timeoutMs}ms${note})`,
+ );
+}
diff --git a/packages/server/src/wait-within-test-budget.test.ts b/packages/server/src/wait-within-test-budget.test.ts
new file mode 100644
index 000000000..ef1f4a945
--- /dev/null
+++ b/packages/server/src/wait-within-test-budget.test.ts
@@ -0,0 +1,347 @@
+import { readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterAll, beforeEach, describe, expect, test, vi } from 'vitest';
+import {
+ remainingTestBudgetMs,
+ waitWithinTestBudget,
+} from './wait-within-test-budget.test-helper.ts';
+
+const realSetTimeout = globalThis.setTimeout;
+
+let attemptsSeen = 0;
+
+const OWN_TIMEOUT_MS = 4_000;
+
+const LOST_EVENT_CAP_MS = 5_000;
+const LOST_EVENT_REQUEST_MS = LOST_EVENT_CAP_MS * 12;
+
+const CLAMP_GRANT_MS = 250;
+const CLAMP_POLL_MS = 25;
+const CLAMP_POLL_SLACK = 4;
+
+describe('remainingTestBudgetMs', () => {
+ test('reads its own timeout and shrinks as it runs', { timeout: OWN_TIMEOUT_MS }, async () => {
+ const atStart = remainingTestBudgetMs();
+ expect(atStart).toBeGreaterThan(0);
+ expect(atStart).toBeLessThanOrEqual(OWN_TIMEOUT_MS);
+
+ await new Promise((resolve) => setTimeout(resolve, 200));
+
+ const later = remainingTestBudgetMs();
+ expect(later).toBeLessThan(atStart ?? 0);
+ });
+
+ test('reports no budget when the test timeout is one vitest treats as unbounded', () => {
+ expect(remainingTestBudgetMs()).toBeUndefined();
+ }, 0);
+
+ test('reports no budget once a retry has made the start stamp stale', { retry: 1 }, () => {
+ if (attemptsSeen === 0) {
+ attemptsSeen += 1;
+ throw new Error('first attempt fails on purpose so the second one runs as a retry');
+ }
+ expect(remainingTestBudgetMs()).toBeUndefined();
+ });
+
+ describe('once a repeat has made the start stamp stale', () => {
+ let repeatsSeen = 0;
+
+ afterAll(() => {
+ expect(repeatsSeen).toBe(2);
+ });
+
+ test('reports no budget', { repeats: 1 }, () => {
+ repeatsSeen += 1;
+ if (repeatsSeen === 1) {
+ expect(remainingTestBudgetMs()).toBeGreaterThan(0);
+ return;
+ }
+ expect(remainingTestBudgetMs()).toBeUndefined();
+ });
+ });
+
+ test.concurrent('reports no budget in a concurrent test, whose identity the runner singleton cannot pin', ({
+ expect,
+ }) => {
+ expect(remainingTestBudgetMs()).toBeUndefined();
+ });
+});
+
+describe('waitWithinTestBudget', () => {
+ test('returns as soon as the predicate holds', async () => {
+ let arrived = false;
+ setTimeout(() => {
+ arrived = true;
+ }, 50);
+
+ await waitWithinTestBudget('the flag to flip', () => arrived, {
+ timeoutMs: 5_000,
+ pollMs: 10,
+ });
+
+ expect(arrived).toBe(true);
+ }, 10_000);
+
+ test('a lost event names the wait before its cap', { timeout: LOST_EVENT_CAP_MS }, async () => {
+ await expect(
+ waitWithinTestBudget('an event that never arrives', () => false, {
+ timeoutMs: LOST_EVENT_REQUEST_MS,
+ pollMs: 10,
+ reserveMs: 3_500,
+ }),
+ ).rejects.toThrow(/^timed out waiting for an event that never arrives after \d+ms/);
+ });
+
+ test('says it clamped, and by how much, when the test budget is the binding limit', async () => {
+ const readAt = Date.now();
+ const budgetAtStart = remainingTestBudgetMs(readAt) ?? 0;
+ expect(budgetAtStart).toBeGreaterThan(CLAMP_GRANT_MS);
+ const reserveMs = budgetAtStart - CLAMP_GRANT_MS;
+
+ let polls = 0;
+ let firstPollAt = 0;
+ const startedAt = Date.now();
+ const failure = await waitWithinTestBudget(
+ 'a clamped wait',
+ () => {
+ polls += 1;
+ if (firstPollAt === 0) firstPollAt = Date.now();
+ return false;
+ },
+ { timeoutMs: 60_000, pollMs: CLAMP_POLL_MS, reserveMs },
+ ).then(
+ () => 'the wait resolved instead of reporting the clamp',
+ (thrown: unknown) => (thrown instanceof Error ? thrown.message : String(thrown)),
+ );
+ const elapsedMs = Date.now() - startedAt;
+
+ expect(failure).toMatch(
+ new RegExp(
+ `^timed out waiting for a clamped wait after \\d+ms \\(requested 60000ms, clamped to \\d+ms to leave ${reserveMs}ms for this failure and the test's own teardown to run inside the test's timeout\\)$`,
+ ),
+ );
+
+ const grantedMs = Number(/clamped to (\d+)ms/.exec(failure)?.[1]);
+ expect(grantedMs).toBeLessThanOrEqual(CLAMP_GRANT_MS);
+ expect(
+ grantedMs,
+ 'the grant is this request minus the reserve, short only by the time between this test ' +
+ 'reading its own remaining budget and the wait reading it again, which the run measures ' +
+ 'rather than assumes, so no machine can drive the grant below this bound',
+ ).toBeGreaterThanOrEqual(CLAMP_GRANT_MS - (firstPollAt - readAt));
+ expect(elapsedMs).toBeGreaterThanOrEqual(grantedMs);
+ expect(
+ polls,
+ 'a wait that runs past the deadline it reported keeps polling, and the reported grant is ' +
+ 'the one number widening the deadline leaves untouched. Contention only lowers this ' +
+ 'count, because a slow host spends more of a fixed window on each poll, so the bound ' +
+ 'reds on a deadline half again too long rather than on a loaded machine',
+ ).toBeLessThanOrEqual(Math.ceil(grantedMs / CLAMP_POLL_MS) + CLAMP_POLL_SLACK);
+ }, 10_000);
+
+ test('does not shorten a wait the test has room for', async () => {
+ const startedAt = Date.now();
+
+ await expect(
+ waitWithinTestBudget('a predicate that stays false', () => false, {
+ timeoutMs: 300,
+ pollMs: 10,
+ }),
+ ).rejects.toThrow(/\(requested 300ms\)$/);
+
+ expect(Date.now() - startedAt).toBeGreaterThanOrEqual(300);
+ }, 20_000);
+
+ test('says it ran blind when the test own remaining budget could not be read', async () => {
+ await expect(
+ waitWithinTestBudget('a wait with no readable budget', () => false, {
+ timeoutMs: 300,
+ pollMs: 10,
+ }),
+ ).rejects.toThrow(
+ /\(requested 300ms, granted the full request: the test's own remaining budget could not be read\)$/,
+ );
+ }, 0);
+
+ test('grants no time, and says so, when the budget is already inside the reserve', async () => {
+ let polls = 0;
+
+ await expect(
+ waitWithinTestBudget(
+ 'a wait with no budget left to grant',
+ () => {
+ polls += 1;
+ return false;
+ },
+ {
+ timeoutMs: 60_000,
+ pollMs: 10,
+ reserveMs: 30_000,
+ },
+ ),
+ ).rejects.toThrow(
+ /\(requested 60000ms, granted no time: only \d+ms of the test's own timeout was left, at or below the 30000ms reserved for this failure and the test's own teardown\)$/,
+ );
+
+ expect(polls).toBe(1);
+ }, 5_000);
+
+ describe('when a hook has already overdrawn the test budget', () => {
+ beforeEach(async () => {
+ await new Promise((resolve) => setTimeout(resolve, 800));
+ });
+
+ test('says the budget was overdrawn instead of reporting negative time left', async () => {
+ await expect(
+ waitWithinTestBudget('a wait that begins overdrawn', () => false, {
+ timeoutMs: 60_000,
+ pollMs: 10,
+ }),
+ ).rejects.toThrow(
+ /granted no time: the test's own timeout was already overdrawn by \d+ms when this wait began\)$/,
+ );
+ }, 500);
+ });
+
+ test('keeps polling when the caller has installed fake timers', async () => {
+ vi.useFakeTimers();
+ try {
+ let arrived = false;
+ realSetTimeout(() => {
+ arrived = true;
+ }, 100);
+
+ await waitWithinTestBudget('the flag to flip under fake timers', () => arrived, {
+ timeoutMs: 4_000,
+ pollMs: 10,
+ });
+
+ expect(arrived).toBe(true);
+ } finally {
+ vi.useRealTimers();
+ }
+ }, 8_000);
+
+ test('still reaches its own deadline when the caller has installed fake timers', async () => {
+ vi.useFakeTimers();
+ try {
+ await expect(
+ waitWithinTestBudget('an event that never arrives under fake timers', () => false, {
+ timeoutMs: 300,
+ pollMs: 10,
+ }),
+ ).rejects.toThrow(
+ /^timed out waiting for an event that never arrives under fake timers after \d+ms/,
+ );
+ } finally {
+ vi.useRealTimers();
+ }
+ }, 8_000);
+
+ test('accepts an async predicate and awaits it before checking the deadline', async () => {
+ let arrived = false;
+ setTimeout(() => {
+ arrived = true;
+ }, 50);
+
+ await waitWithinTestBudget('an async probe to report the flag', async () => arrived, {
+ timeoutMs: 5_000,
+ pollMs: 10,
+ });
+
+ expect(arrived).toBe(true);
+ }, 10_000);
+
+ test('a throwing predicate names the wait instead of failing anonymously', async () => {
+ await expect(
+ waitWithinTestBudget(
+ 'the disk file to settle',
+ () => {
+ throw new Error('ENOENT: no such file or directory');
+ },
+ { timeoutMs: 1_000 },
+ ),
+ ).rejects.toThrow(/the disk file to settle/);
+ });
+
+ test('a throwing predicate keeps its own failure in the message', async () => {
+ await expect(
+ waitWithinTestBudget(
+ 'the disk file to settle',
+ () => {
+ throw new Error('ENOENT: no such file or directory');
+ },
+ { timeoutMs: 1_000 },
+ ),
+ ).rejects.toThrow(/ENOENT: no such file or directory/);
+ });
+
+ test('a rejected async predicate names the wait and keeps its own failure', async () => {
+ await expect(
+ waitWithinTestBudget(
+ 'an async probe of the disk file',
+ async () => {
+ throw new Error('EACCES: permission denied');
+ },
+ { timeoutMs: 1_000 },
+ ),
+ ).rejects.toThrow(
+ /while waiting for an async probe of the disk file: EACCES: permission denied/,
+ );
+ });
+
+ test('a predicate that throws a non-Error still names the wait', async () => {
+ await expect(
+ waitWithinTestBudget(
+ 'the disk file to settle',
+ () => {
+ throw 'the watcher gave up';
+ },
+ { timeoutMs: 1_000 },
+ ),
+ ).rejects.toThrow(/while waiting for the disk file to settle: the watcher gave up/);
+ });
+
+ test('keeps the thrown error as the cause, so its own properties stay readable', async () => {
+ const missing = join(tmpdir(), 'wait-within-test-budget-absent-notes.md');
+
+ await expect(
+ waitWithinTestBudget('the disk file to settle', () => readFileSync(missing, 'utf8') !== '', {
+ timeoutMs: 1_000,
+ pollMs: 10,
+ }),
+ ).rejects.toHaveProperty('cause.code', 'ENOENT');
+ });
+
+ test('keeps the frames of the predicate that threw, not the frames of the wrapper', async () => {
+ const missing = join(tmpdir(), 'wait-within-test-budget-absent-notes.md');
+
+ await expect(
+ waitWithinTestBudget('the disk file to settle', () => readFileSync(missing, 'utf8') !== '', {
+ timeoutMs: 1_000,
+ pollMs: 10,
+ }),
+ ).rejects.toHaveProperty('stack', expect.stringMatching(/\n\s+at \S*readFileSync\b/));
+ });
+
+ test('a predicate that throws on a later poll still names the wait', async () => {
+ let polls = 0;
+
+ await expect(
+ waitWithinTestBudget(
+ 'the disk file to settle',
+ () => {
+ polls += 1;
+ if (polls < 3) return false;
+ throw new Error('ENOENT: no such file or directory');
+ },
+ { timeoutMs: 1_000, pollMs: 10 },
+ ),
+ ).rejects.toThrow(
+ /while waiting for the disk file to settle: ENOENT: no such file or directory/,
+ );
+
+ expect(polls).toBe(3);
+ });
+});
diff --git a/packages/server/tsconfig.test-helper-callers.json b/packages/server/tsconfig.test-helper-callers.json
new file mode 100644
index 000000000..270181f8b
--- /dev/null
+++ b/packages/server/tsconfig.test-helper-callers.json
@@ -0,0 +1,14 @@
+{
+ "extends": "./tsconfig.json",
+ "include": [],
+ "files": [
+ "src/expect-stable.test.ts",
+ "src/file-watcher-chokidar-fallback.test.ts",
+ "src/managed-artifact-watcher.test.ts",
+ "src/persistence-tripwire-block.test.ts",
+ "src/persistence-tripwire-paste.test.ts",
+ "src/serialize-doc-vs-git-show-byte-equality.test.ts",
+ "src/serialize-doc-ytext.test.ts",
+ "src/wait-within-test-budget.test.ts"
+ ]
+}