@irtio/testing 3.0.0 → 3.1.0

package/dist/{chunk-3W5KPX3I.js → chunk-47O3HZBE.js}

@@ -86,6 +86,7 @@ function clockScheduler(clock) {
 }
 
 // src/harness.ts
+import { spawnBots } from "@irtio/bots";
 import { INTERNAL_SESSION, joinRoom } from "@irtio/client";
 import {
   ErrorCode,
@@ -259,6 +260,7 @@ function frameNameOf(frame) {
 async function microtasks(turns = MICROTASK_TURNS) {
   for (let i = 0; i < turns; i++) await Promise.resolve();
 }
+var NPC_TRACE_LIMIT = 16;
 function detailOf(detail) {
   return detail ? { detail } : {};
 }
@@ -282,6 +284,8 @@ var TestHarness = class {
   /** Client ids a frame was dropped for because nobody knows them, each warned about once. */
   unknownSendWarned = /* @__PURE__ */ new Set();
   clientList = [];
+  /** D44: live NPC sessions by client id. */
+  npcSessions = /* @__PURE__ */ new Map();
   roleById = /* @__PURE__ */ new Map();
   roleOverrides = /* @__PURE__ */ new Map();
   traceLog = [];
@@ -340,6 +344,8 @@ var TestHarness = class {
       }
       this.holdOrDrop(clientId, frame);
     };
+    this.host.onSpawnNpc = (clientId, config) => this.spawnNpc(clientId, config);
+    this.host.onDespawnNpc = (clientId) => this.despawnNpc(clientId);
     this.coreRef = new RoomCore(this.definition, this.host, {
       roomId: this.roomId,
       ...options.seed !== void 0 ? { seed: options.seed } : {},
@@ -437,13 +443,20 @@ var TestHarness = class {
   // -------------------------------------------------------------------------
   // The link
   // -------------------------------------------------------------------------
-  /** A `Transport` bound to one `t.join()`; reconnects call `connect` again with the same spec. */
-  transportFor(spec) {
+  /**
+   * A `Transport` bound to one `t.join()`; reconnects call `connect` again with the same spec.
+   *
+   * `identity` is how an NPC gets in: the runtime mints its client id (`npc-<room>-<n>`) before the
+   * host is asked to open the session, and every reconnect this transport makes has to come back as
+   * that same id with the same `npc` flag, exactly as the supervisor's loopback does.
+   */
+  transportFor(spec, identity) {
     return {
       connect: () => {
         const link = {
           socket: void 0,
-          clientId: `c${this.nextClientId++}`,
+          clientId: identity?.clientId ?? `c${this.nextClientId++}`,
+          npc: identity?.npc ?? false,
           role: "",
           joined: false,
           connected: true,
@@ -463,6 +476,105 @@ var TestHarness = class {
       }
     };
   }
+  // -------------------------------------------------------------------------
+  // D44: NPCs
+  // -------------------------------------------------------------------------
+  /**
+   * `room.spawnNPC`, in process. The runtime has already validated the config and minted the id;
+   * what is left is the supervisor's half — find the script in the definition's `npcs` map and put
+   * a real client behind it.
+   *
+   * Everything here rides `this.clock`: the bot joins through `transportFor`, so its frames are the
+   * same fake-clock timers a player's are, and `scheduler` makes `npc.wait` / `npc.until` fake time
+   * too. So an NPC spawned inside a tick becomes visible on the next `t.tick()` / `t.run()` /
+   * `t.settle`, and never makes progress behind the test's back.
+   *
+   * Throwing is deliberate: the caller is `room.spawnNPC` inside a handler, which the runtime runs
+   * under `tryRun`, so the sentence lands in `t.handlerErrors` and (by default) fails the test at
+   * the clock call that ran the handler. Recording it and carrying on is what this used to do, and
+   * it is how "my NPC never showed up" became a silent test.
+   */
+  spawnNpc(clientId, config) {
+    if (this.stopped) return;
+    if (this.npcSessions.has(clientId)) {
+      this.host.log("warn", [`irtio: npc ${clientId} is already running; spawn ignored`]);
+      return;
+    }
+    const scripts = this.definition.config.npcs;
+    const script = scripts?.[config.brain.script];
+    if (!script) {
+      throw new Error(
+        `testRoom: no npc script named ${JSON.stringify(config.brain.script)} in this room's npcs map`
+      );
+    }
+    const name = config.name ?? config.brain.script;
+    const entry = {
+      clientId,
+      script: config.brain.script,
+      runner: void 0,
+      stopped: false
+    };
+    this.npcSessions.set(clientId, entry);
+    this.activity++;
+    void spawnBots(1, {
+      schema: this.definition.schema,
+      room: this.roomId,
+      url: TEST_URL,
+      key: TEST_KEY,
+      name,
+      ...config.role !== void 0 ? { role: config.role } : {},
+      ...config.seed !== void 0 ? { seed: config.seed } : {},
+      traceLimit: NPC_TRACE_LIMIT,
+      // Both of these are real timers in `@irtio/bots`, and a fake-clock harness must not own one:
+      // the join is bounded by the test's own clock calls, and "every bot disconnected" is what
+      // `t.stop()` deliberately does.
+      joinTimeoutMs: 0,
+      roomGoneGraceMs: 0,
+      transport: this.transportFor({}, { clientId, npc: true }),
+      scheduler: this.scheduler,
+      script: (bot) => script(bot)
+    }).then(
+      (runner) => {
+        this.activity++;
+        entry.runner = runner;
+        if (entry.stopped) void this.stopNpc(entry);
+        else void runner.done().catch((err) => this.noteNpcError(entry, err));
+      },
+      (err) => {
+        this.npcSessions.delete(clientId);
+        this.noteNpcError(entry, err);
+      }
+    );
+  }
+  despawnNpc(clientId) {
+    const entry = this.npcSessions.get(clientId);
+    if (!entry) return;
+    this.npcSessions.delete(clientId);
+    entry.stopped = true;
+    if (entry.runner) void this.stopNpc(entry);
+  }
+  /** Stops one NPC's runner: its script winds down, then it leaves the room like any client. */
+  async stopNpc(entry) {
+    const runner = entry.runner;
+    entry.runner = void 0;
+    if (!runner) return;
+    this.activity++;
+    try {
+      await runner.stop();
+    } catch (err) {
+      this.noteNpcError(entry, err);
+    }
+    this.activity++;
+  }
+  /** An NPC failure, filed where a handler throw is filed — see `reportHandlerErrors`. */
+  noteNpcError(entry, err) {
+    this.handlerErrorLog.push({
+      handler: `npcs.${entry.script} (${entry.clientId})`,
+      message: err instanceof Error ? err.message : String(err),
+      tick: this.coreRef.tick
+    });
+    this.activity++;
+  }
   /**
    * Bug #49: a frame for a client with no link. Held when the core has the client and counts it
    * connected, which is exactly the window between `RoomCore.join` running `onJoin` and
@@ -635,7 +747,8 @@ var TestHarness = class {
         result = this.coreRef.join(link.clientId, {
           ...role !== void 0 ? { role } : {},
           ...name !== void 0 ? { name } : {},
-          ...reconnecting ? { reconnecting: true } : {}
+          ...reconnecting ? { reconnecting: true } : {},
+          ...link.npc ? { npc: true } : {}
         });
       } catch (err) {
         failure = err;
@@ -1218,6 +1331,11 @@ var TestHarness = class {
   }
   stop() {
     this.stopped = true;
+    for (const entry of [...this.npcSessions.values()]) {
+      this.npcSessions.delete(entry.clientId);
+      entry.stopped = true;
+      void this.stopNpc(entry);
+    }
     for (const client of this.clientList) client.leave();
     for (const link of this.links) link.socket.hangUp();
     this.coreRef.stop();

package/dist/index.d.ts

@@ -407,6 +407,8 @@ declare class TestHarness<S extends AnySchema> implements TestRoom<S> {
     /** Client ids a frame was dropped for because nobody knows them, each warned about once. */
     private readonly unknownSendWarned;
     private readonly clientList;
+    /** D44: live NPC sessions by client id. */
+    private readonly npcSessions;
     private readonly roleById;
     private readonly roleOverrides;
     private readonly traceLog;
@@ -468,8 +470,35 @@ declare class TestHarness<S extends AnySchema> implements TestRoom<S> {
     /** M7 pf4: the RPC trace, or `undefined` unless `traceRpc: true` armed one. */
     get rpcTrace(): RpcTraceDump | undefined;
     private enterCore;
-    /** A `Transport` bound to one `t.join()`; reconnects call `connect` again with the same spec. */
+    /**
+     * A `Transport` bound to one `t.join()`; reconnects call `connect` again with the same spec.
+     *
+     * `identity` is how an NPC gets in: the runtime mints its client id (`npc-<room>-<n>`) before the
+     * host is asked to open the session, and every reconnect this transport makes has to come back as
+     * that same id with the same `npc` flag, exactly as the supervisor's loopback does.
+     */
     private transportFor;
+    /**
+     * `room.spawnNPC`, in process. The runtime has already validated the config and minted the id;
+     * what is left is the supervisor's half — find the script in the definition's `npcs` map and put
+     * a real client behind it.
+     *
+     * Everything here rides `this.clock`: the bot joins through `transportFor`, so its frames are the
+     * same fake-clock timers a player's are, and `scheduler` makes `npc.wait` / `npc.until` fake time
+     * too. So an NPC spawned inside a tick becomes visible on the next `t.tick()` / `t.run()` /
+     * `t.settle`, and never makes progress behind the test's back.
+     *
+     * Throwing is deliberate: the caller is `room.spawnNPC` inside a handler, which the runtime runs
+     * under `tryRun`, so the sentence lands in `t.handlerErrors` and (by default) fails the test at
+     * the clock call that ran the handler. Recording it and carrying on is what this used to do, and
+     * it is how "my NPC never showed up" became a silent test.
+     */
+    private spawnNpc;
+    private despawnNpc;
+    /** Stops one NPC's runner: its script winds down, then it leaves the room like any client. */
+    private stopNpc;
+    /** An NPC failure, filed where a handler throw is filed — see `reportHandlerErrors`. */
+    private noteNpcError;
     /**
      * Bug #49: a frame for a client with no link. Held when the core has the client and counts it
      * connected, which is exactly the window between `RoomCore.join` running `onJoin` and

package/dist/index.js

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

package/dist/matchers.js

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

package/package.json

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