Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
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.jsonindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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 } froimport { __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 frawait 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.jsonnew file mode 100644index 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"+ ]+}