@irtio/testing 3.1.1 → 4.1.0

package/README.md

@@ -0,0 +1,66 @@
+# @irtio/testing
+
+Test room logic with real irtio clients and a controllable clock. Check synchronization, RPCs,
+reconnection, and visibility without opening sockets.
+
+```bash
+npm install --save-dev @irtio/testing vitest
+```
+
+## Test a player update
+
+This test uses the room generated by `npx irtio init --tick --yes`.
+Create or replace `irtio/room.test.ts`:
+
+```ts
+import { expect, test } from 'vitest';
+import { testRoom } from '@irtio/testing';
+import '@irtio/testing/matchers';
+import room from './room.js';
+
+test('an owned write reaches another player', async () => {
+  const t = await testRoom(room);
+  try {
+    const [a, b] = await t.join(2, { role: 'player' });
+    const player = a.state.players.get(a.id);
+    expect(player).toBeDefined();
+    player!.x = 10;
+    a.flush();
+    await t.tick(2);
+
+    expect(t.state.players.get(a.id)?.x).toBe(10);
+    expect(b.state.players.get(a.id)?.x).toBe(10);
+    expect(t).toHaveConverged();
+    expect(t).toHaveNoVisibilityLeaks();
+  } finally {
+    t.stop();
+  }
+});
+```
+
+```bash
+npx vitest run irtio/room.test.ts
+```
+
+## Drive the clock
+
+| Method | Behavior |
+| --- | --- |
+| `await t.join(spec?)` | Join one client |
+| `await t.join(n, spec?)` | Join multiple clients |
+| `await t.tick(n?)` | Advance server ticks; defaults to one |
+| `await t.run(ms)` | Advance fake time in milliseconds |
+| `await t.until(predicate, options?)` | Advance until a condition holds, or reject at the limit |
+| `t.stop()` | Stop the room and its clients |
+
+Await all clock operations. By default, awaiting client RPCs also advances the clock until they
+settle, and a room handler error fails the test. Configure `autoPump` and `failOnHandlerError`
+when testing those behaviors explicitly.
+
+`testRelay()` tests schema-less relay messaging. Import `@irtio/testing/matchers` to register
+Vitest matchers; the main entry point also exports assertion functions for other runners.
+For physics rooms, await the corresponding `initPhysics`, `initRapier2d`, or `initMatter`
+initializer before creating the test room.
+
+See the [testing reference](https://irt.io/docs/reference/testing) for all options, matchers,
+network conditions, and physics helpers.

package/dist/{chunk-47O3HZBE.js → chunk-7GS3V7QO.js}

@@ -1,4 +1,5 @@
 // src/compare.ts
+import { isPerClient } from "@irtio/runtime";
 import {
   cloneValue,
   computeDirty,
@@ -46,7 +47,7 @@ function divergence(ext, authority, client, visible, memberships = /* @__PURE__
   for (const [name, cd] of computeDirty(ext, authority, client)) {
     if (!visible.has(name)) continue;
     const desc = ext.collection(name);
-    const membership = desc.visibility === "spatial-grid" ? memberships.get(name) : void 0;
+    const membership = isPerClient(desc) ? memberships.get(name) : void 0;
     for (const id of cd.added) {
       if (!membership || !membership.has(id)) out.push(`${name}[${id}]: only in the client's view`);
     }
@@ -108,6 +109,7 @@ import {
   RoomCore,
   RoomFullError,
   createVisibilityPolicy,
+  isPerClient as isPerClient2,
   visibleNames
 } from "@irtio/runtime";
 import { FakeClock, HarnessHost, frameTypeName } from "@irtio/runtime/test";
@@ -247,6 +249,7 @@ var DROPPABLE = /* @__PURE__ */ new Set([
 ]);
 var MICROTASK_TURNS = 8;
 var SETTLE_ROUNDS = 64;
+var RUN_HOPS_MAX = 1e4;
 var JOIN_TIMEOUT_MS = 3e4;
 var HELD_FRAMES_MAX = 16;
 var DROPPED_HELD = new Uint8Array(0);
@@ -873,16 +876,16 @@ var TestHarness = class {
       const seen = this.deliveredIds(link.clientId, dc.name);
       const leaked = dc.ops.filter((op) => {
         if (op.op === "remove") {
-          if (keep.has(dc.name)) return desc.visibility === "spatial-grid" && !seen.has(op.id);
+          if (keep.has(dc.name)) return isPerClient2(desc) && !seen.has(op.id);
           return !seen.has(op.id);
         }
         if (!keep.has(dc.name)) return true;
-        if (desc.visibility !== "spatial-grid") return false;
+        if (!isPerClient2(desc)) return false;
         return !policy.maySeeEntity(desc, op.id);
       });
       for (const op of dc.ops) {
         if (op.op === "remove") seen.delete(op.id);
-        else if (desc.visibility !== "spatial-grid" || policy.maySeeEntity(desc, op.id)) {
+        else if (!isPerClient2(desc) || policy.maySeeEntity(desc, op.id)) {
           seen.add(op.id);
         }
       }
@@ -976,8 +979,30 @@ var TestHarness = class {
       await this.settle();
     }
   }
+  /**
+   * Bug #127: one `clock.advance(ms)` would fire every timer in the window, but a script parked on
+   * `await npc.wait(50)` only resumes in a **microtask**, which cannot run until `advance` has
+   * returned — so the script's next timer was armed after the window had already gone by and a
+   * 1000 ms run took the script exactly one step. So hop instead of leaping: advance to the next
+   * due timer, let microtasks drain (continuations run, new timers get armed), and repeat until
+   * the target. With nothing armed it is still a single leap.
+   */
   async run(ms) {
-    this.clock.advance(ms);
+    const target = this.clock.now() + Math.max(0, ms);
+    for (let hops = 0; ; hops++) {
+      if (hops > RUN_HOPS_MAX) {
+        throw new Error(
+          `testRoom: t.run(${ms}) did not settle \u2014 more than ${RUN_HOPS_MAX} timers came due, which usually means a timer re-arms itself at the same fake time`
+        );
+      }
+      const due = this.clock.nextDueAt();
+      if (due === void 0 || due > target) {
+        this.clock.advance(target - this.clock.now());
+        break;
+      }
+      this.clock.advance(Math.max(0, due - this.clock.now()));
+      await microtasks();
+    }
     await this.settle();
   }
   /**
@@ -1182,7 +1207,7 @@ var TestHarness = class {
       const policy = createVisibilityPolicy(this.ext, this.plain, client.id, role);
       const view = client.view;
       for (const c of this.ext.collections) {
-        if (c.visibility === "spatial-grid") {
+        if (isPerClient2(c)) {
           const coll = view[c.name];
           const ids = coll ? [...coll.ids()].filter((id) => !policy.maySeeEntity(c, id)) : [];
           if (ids.length > 0) {

package/dist/index.d.ts

@@ -566,6 +566,14 @@ declare class TestHarness<S extends AnySchema> implements TestRoom<S> {
      */
     private reportHandlerErrors;
     tick(n?: number): Promise<void>;
+    /**
+     * Bug #127: one `clock.advance(ms)` would fire every timer in the window, but a script parked on
+     * `await npc.wait(50)` only resumes in a **microtask**, which cannot run until `advance` has
+     * returned — so the script's next timer was armed after the window had already gone by and a
+     * 1000 ms run took the script exactly one step. So hop instead of leaping: advance to the next
+     * due timer, let microtasks drain (continuations run, new timers get armed), and repeat until
+     * the target. With nothing armed it is still a single leap.
+     */
     run(ms: number): Promise<void>;
     /**
      * Advances until `pred()` holds. In **event mode** a tick is a zero-length clock step, so this

package/dist/index.js

@@ -12,7 +12,7 @@ import {
   toHaveRejected,
   toStayUnderBandwidth,
   toStayWithinPrediction
-} from "./chunk-47O3HZBE.js";
+} from "./chunk-7GS3V7QO.js";
 
 // src/relay-harness.ts
 import { joinRelay } from "@irtio/client";

package/dist/matchers.js

@@ -5,7 +5,7 @@ import {
   toHaveRejected,
   toStayUnderBandwidth,
   toStayWithinPrediction
-} from "./chunk-47O3HZBE.js";
+} from "./chunk-7GS3V7QO.js";
 
 // src/matchers.ts
 import { expect } from "vitest";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@irtio/testing",
-  "version": "3.1.1",
+  "version": "4.1.0",
   "description": "irtio's blessed test API: testRoom() in-process rooms with real client semantics, plus Vitest matchers",
   "license": "MIT",
   "repository": {
@@ -28,12 +28,12 @@
     "dist"
   ],
   "dependencies": {
-    "@irtio/bots": "3.1.1",
-    "@irtio/client": "3.1.1",
-    "@irtio/protocol": "3.1.1",
-    "@irtio/runtime": "3.1.1",
-    "@irtio/schema": "3.1.1",
-    "@irtio/server": "3.1.1"
+    "@irtio/bots": "^4.1.0",
+    "@irtio/client": "^4.1.0",
+    "@irtio/protocol": "^4.1.0",
+    "@irtio/runtime": "^4.1.0",
+    "@irtio/schema": "^4.1.0",
+    "@irtio/server": "^4.1.0"
   },
   "peerDependencies": {
     "vitest": ">=3"