@joystyk/testing 0.0.0-stage → 0.2.0

package/dist/waiting.js

@@ -0,0 +1,97 @@
+//#region src/waiting.ts
+var host = globalThis;
+/**
+* The default wall-clock budget for a wait: generous, but under the browser and e2e
+* projects' 60-second test timeout, so a wait that fails names what never happened instead of
+* ending in a bare timeout.
+*/
+var WAIT_BUDGET_MS = 45e3;
+/** Resolves after `ms` milliseconds: for yielding to the page, never for waiting on a result. */
+var pause = (ms) => new Promise((resolve) => host.setTimeout(resolve, ms));
+/**
+* Resolves on a fresh task, without the 4 ms clamp nested timers get, so the events,
+* commands and due timers queued before it can run.
+*/
+var nextTask = () => {
+	const Channel = host.MessageChannel;
+	if (Channel === void 0) return pause(0);
+	return new Promise((resolve) => {
+		const channel = new Channel();
+		channel.port1.onmessage = () => {
+			channel.port1.close();
+			resolve();
+		};
+		channel.port2.postMessage(null);
+	});
+};
+/**
+* Resolves once `condition` holds, checking every few milliseconds. Fails with "Timed out
+* waiting for <what>" after the budget, which by default is most of the test's own timeout.
+*/
+var waitUntil = async (condition, what, options = {}) => {
+	const budget = options.timeoutMs ?? 45e3;
+	const start = host.performance.now();
+	while (!condition()) {
+		if (host.performance.now() - start > budget) throw new Error(`Timed out after ${String(budget)} ms waiting for ${what}.`);
+		await pause(options.intervalMs ?? 10);
+	}
+};
+/** A manual frame scheduler for a fixed-step runner, at `frameMs` per frame (default 60 Hz). */
+var manualFrames = (frameMs = 1e3 / 60) => {
+	let pending = null;
+	let now = 0;
+	const port = { request: (callback) => {
+		pending = callback;
+		return () => {
+			if (pending === callback) pending = null;
+		};
+	} };
+	const run = (count) => {
+		let ran = 0;
+		for (let i = 0; i < count; i += 1) {
+			const callback = pending;
+			pending = null;
+			if (callback !== null) {
+				ran += 1;
+				callback(now);
+			}
+			now += frameMs;
+		}
+		return ran;
+	};
+	const until = async (condition, what, options = {}) => {
+		const maxFrames = options.maxFrames ?? 3600;
+		const budget = options.timeoutMs ?? 45e3;
+		const start = host.performance.now();
+		let frames = 0;
+		while (!condition()) {
+			if (frames >= maxFrames) throw new Error(`Gave up waiting for ${what} after ${String(maxFrames)} frames.`);
+			if (host.performance.now() - start > budget) throw new Error(`Timed out after ${String(budget)} ms waiting for ${what} (${String(frames)} frames run).`);
+			if (pending === null) await pause(10);
+			else {
+				frames += run(1);
+				await nextTask();
+			}
+		}
+	};
+	const advance = async (count) => {
+		let ran = 0;
+		for (let i = 0; i < count; i += 1) {
+			await nextTask();
+			ran += run(1);
+		}
+		await nextTask();
+		return ran;
+	};
+	return {
+		port,
+		run,
+		pending: () => pending !== null,
+		until,
+		advance
+	};
+};
+//#endregion
+export { WAIT_BUDGET_MS, manualFrames, nextTask, pause, waitUntil };
+
+//# sourceMappingURL=waiting.js.map

package/dist/waiting.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"waiting.js","names":[],"sources":["../src/waiting.ts"],"sourcesContent":["// Waiting in tests on a busy machine. The suite shares its machine with other work, so a\n// test never sleeps for a fixed time and hopes, and never gives a condition a budget measured\n// in seconds of wall-clock time it might not get. It waits for the condition itself, with a\n// budget that only a real failure exhausts. A real-time game runs on `manualFrames`, which\n// counts game time in frames the test runs, so load slows the test down but can't change\n// what happens in it. See docs/design-docs/testing-under-load.md.\nimport type { FrameScheduler } from '@joystyk/session';\n\n// This package names neither DOM nor Node types; these exist in both.\nconst host = globalThis as unknown as {\n  setTimeout(callback: () => void, ms: number): unknown;\n  performance: { now(): number };\n  MessageChannel?: new () => {\n    port1: { onmessage: (() => void) | null; close(): void };\n    port2: { postMessage(message: unknown): void };\n  };\n};\n\n/**\n * The default wall-clock budget for a wait: generous, but under the browser and e2e\n * projects' 60-second test timeout, so a wait that fails names what never happened instead of\n * ending in a bare timeout.\n */\nexport const WAIT_BUDGET_MS = 45_000;\n\n/** Resolves after `ms` milliseconds: for yielding to the page, never for waiting on a result. */\nexport const pause = (ms: number): Promise<void> => new Promise((resolve) => host.setTimeout(resolve, ms));\n\n/**\n * Resolves on a fresh task, without the 4 ms clamp nested timers get, so the events,\n * commands and due timers queued before it can run.\n */\nexport const nextTask = (): Promise<void> => {\n  const Channel = host.MessageChannel;\n  if (Channel === undefined) return pause(0);\n  return new Promise((resolve) => {\n    const channel = new Channel();\n    channel.port1.onmessage = () => {\n      channel.port1.close();\n      resolve();\n    };\n    channel.port2.postMessage(null);\n  });\n};\n\nexport type WaitOptions = {\n  /** The wall-clock budget. Default `WAIT_BUDGET_MS`. */\n  readonly timeoutMs?: number;\n  /** How often to check. Default 10 ms. */\n  readonly intervalMs?: number;\n};\n\n/**\n * Resolves once `condition` holds, checking every few milliseconds. Fails with \"Timed out\n * waiting for <what>\" after the budget, which by default is most of the test's own timeout.\n */\nexport const waitUntil = async (condition: () => boolean, what: string, options: WaitOptions = {}): Promise<void> => {\n  const budget = options.timeoutMs ?? WAIT_BUDGET_MS;\n  const start = host.performance.now();\n  while (!condition()) {\n    if (host.performance.now() - start > budget)\n      throw new Error(`Timed out after ${String(budget)} ms waiting for ${what}.`);\n    await pause(options.intervalMs ?? 10);\n  }\n};\n\nexport type FrameWaitOptions = {\n  /** The most frames that may run a callback before the wait fails: game time. Default 3600 (a minute at 60 Hz). */\n  readonly maxFrames?: number;\n  /** The wall-clock budget, for waits on the UI while the runner is paused. Default `WAIT_BUDGET_MS`. */\n  readonly timeoutMs?: number;\n};\n\n/** A frame scheduler that runs only when the test says so. */\nexport interface ManualFrames {\n  /** Pass this as the runner's `frames` port. */\n  readonly port: FrameScheduler;\n  /**\n   * Runs `count` frames, each `frameMs` after the last, and returns how many of them had a\n   * callback waiting. A paused or finished runner requests none, so it returns 0.\n   */\n  run(count: number): number;\n  /** True when a callback waits for the next frame. */\n  pending(): boolean;\n  /**\n   * Runs `count` frames, yielding to the page between them as `until` does, so input that\n   * arrives meanwhile is handled. For checking that nothing happens over some game time.\n   * Returns how many frames had a callback waiting.\n   */\n  advance(count: number): Promise<number>;\n  /**\n   * Runs one frame at a time until `condition` holds, yielding to the page between frames\n   * so events, commands and timers run. Game time can't outrun the check, so a phase that\n   * lasts a few ticks is never skipped, and a busy machine only makes the wait take longer.\n   * Fails after `maxFrames` frames that ran a callback, or after the wall-clock budget.\n   */\n  until(condition: () => boolean, what: string, options?: FrameWaitOptions): Promise<void>;\n}\n\n/** A manual frame scheduler for a fixed-step runner, at `frameMs` per frame (default 60 Hz). */\nexport const manualFrames = (frameMs = 1000 / 60): ManualFrames => {\n  let pending: ((now: number) => void) | null = null;\n  let now = 0;\n  const port: FrameScheduler = {\n    request: (callback) => {\n      pending = callback;\n      return () => {\n        if (pending === callback) pending = null;\n      };\n    },\n  };\n  const run = (count: number): number => {\n    let ran = 0;\n    for (let i = 0; i < count; i += 1) {\n      const callback = pending;\n      pending = null;\n      if (callback !== null) {\n        ran += 1;\n        callback(now);\n      }\n      now += frameMs;\n    }\n    return ran;\n  };\n  const until = async (condition: () => boolean, what: string, options: FrameWaitOptions = {}): Promise<void> => {\n    const maxFrames = options.maxFrames ?? 3600;\n    const budget = options.timeoutMs ?? WAIT_BUDGET_MS;\n    const start = host.performance.now();\n    let frames = 0;\n    while (!condition()) {\n      if (frames >= maxFrames) throw new Error(`Gave up waiting for ${what} after ${String(maxFrames)} frames.`);\n      if (host.performance.now() - start > budget)\n        throw new Error(`Timed out after ${String(budget)} ms waiting for ${what} (${String(frames)} frames run).`);\n      if (pending === null) {\n        // Nothing to run: the runner is paused or waiting on the UI. Let the page catch up.\n        await pause(10);\n      } else {\n        frames += run(1);\n        await nextTask();\n      }\n    }\n  };\n  const advance = async (count: number): Promise<number> => {\n    let ran = 0;\n    for (let i = 0; i < count; i += 1) {\n      await nextTask();\n      ran += run(1);\n    }\n    await nextTask();\n    return ran;\n  };\n  return { port, run, pending: () => pending !== null, until, advance };\n};\n"],"mappings":";AASA,IAAM,OAAO;;;;;;AAcb,IAAa,iBAAiB;;AAG9B,IAAa,SAAS,OAA8B,IAAI,SAAS,YAAY,KAAK,WAAW,SAAS,EAAE,CAAC;;;;;AAMzG,IAAa,iBAAgC;CAC3C,MAAM,UAAU,KAAK;CACrB,IAAI,YAAY,KAAA,GAAW,OAAO,MAAM,CAAC;CACzC,OAAO,IAAI,SAAS,YAAY;EAC9B,MAAM,UAAU,IAAI,QAAQ;EAC5B,QAAQ,MAAM,kBAAkB;GAC9B,QAAQ,MAAM,MAAM;GACpB,QAAQ;EACV;EACA,QAAQ,MAAM,YAAY,IAAI;CAChC,CAAC;AACH;;;;;AAaA,IAAa,YAAY,OAAO,WAA0B,MAAc,UAAuB,CAAC,MAAqB;CACnH,MAAM,SAAS,QAAQ,aAAA;CACvB,MAAM,QAAQ,KAAK,YAAY,IAAI;CACnC,OAAO,CAAC,UAAU,GAAG;EACnB,IAAI,KAAK,YAAY,IAAI,IAAI,QAAQ,QACnC,MAAM,IAAI,MAAM,mBAAmB,OAAO,MAAM,EAAE,kBAAkB,KAAK,EAAE;EAC7E,MAAM,MAAM,QAAQ,cAAc,EAAE;CACtC;AACF;;AAoCA,IAAa,gBAAgB,UAAU,MAAO,OAAqB;CACjE,IAAI,UAA0C;CAC9C,IAAI,MAAM;CACV,MAAM,OAAuB,EAC3B,UAAU,aAAa;EACrB,UAAU;EACV,aAAa;GACX,IAAI,YAAY,UAAU,UAAU;EACtC;CACF,EACF;CACA,MAAM,OAAO,UAA0B;EACrC,IAAI,MAAM;EACV,KAAK,IAAI,IAAI,GAAG,IAAI,OAAO,KAAK,GAAG;GACjC,MAAM,WAAW;GACjB,UAAU;GACV,IAAI,aAAa,MAAM;IACrB,OAAO;IACP,SAAS,GAAG;GACd;GACA,OAAO;EACT;EACA,OAAO;CACT;CACA,MAAM,QAAQ,OAAO,WAA0B,MAAc,UAA4B,CAAC,MAAqB;EAC7G,MAAM,YAAY,QAAQ,aAAa;EACvC,MAAM,SAAS,QAAQ,aAAA;EACvB,MAAM,QAAQ,KAAK,YAAY,IAAI;EACnC,IAAI,SAAS;EACb,OAAO,CAAC,UAAU,GAAG;GACnB,IAAI,UAAU,WAAW,MAAM,IAAI,MAAM,uBAAuB,KAAK,SAAS,OAAO,SAAS,EAAE,SAAS;GACzG,IAAI,KAAK,YAAY,IAAI,IAAI,QAAQ,QACnC,MAAM,IAAI,MAAM,mBAAmB,OAAO,MAAM,EAAE,kBAAkB,KAAK,IAAI,OAAO,MAAM,EAAE,cAAc;GAC5G,IAAI,YAAY,MAEd,MAAM,MAAM,EAAE;QACT;IACL,UAAU,IAAI,CAAC;IACf,MAAM,SAAS;GACjB;EACF;CACF;CACA,MAAM,UAAU,OAAO,UAAmC;EACxD,IAAI,MAAM;EACV,KAAK,IAAI,IAAI,GAAG,IAAI,OAAO,KAAK,GAAG;GACjC,MAAM,SAAS;GACf,OAAO,IAAI,CAAC;EACd;EACA,MAAM,SAAS;EACf,OAAO;CACT;CACA,OAAO;EAAE;EAAM;EAAK,eAAe,YAAY;EAAM;EAAO;CAAQ;AACtE"}

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@joystyk/testing",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Dev-time conformance suites for engines and simulations, plus test RNGs, a fake clock, fake storage and fixture builders.",
+  "private": false,
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./fixtures": {
+      "types": "./dist/fixtures/index.d.ts",
+      "default": "./dist/fixtures/index.js"
+    }
+  },
+  "dependencies": {
+    "@joystyk/contracts": "0.2.0",
+    "@joystyk/kit": "0.2.0",
+    "@joystyk/session": "0.2.0"
+  },
+  "peerDependencies": {
+    "vitest": "4.1.11"
+  },
+  "devDependencies": {
+    "typescript": "5.9.3",
+    "vite": "8.3.3",
+    "vitest": "4.1.11"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "NOTICE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=24.15.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/joystyk-games/game-libraries.git",
+    "directory": "packages/testing"
+  },
+  "homepage": "https://github.com/joystyk-games/game-libraries/tree/main/packages/testing#readme",
+  "bugs": {
+    "url": "https://github.com/joystyk-games/game-libraries/issues"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "node ../../scripts/build-package.ts"
+  }
 }