@irtio/testing

Test room logic with real irtio clients and a controllable clock. Check synchronization, RPCs, reconnection, and visibility without opening sockets.

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:

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();
  }
});

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 for all options, matchers, network conditions, and physics helpers.