Unit Testing a Colyseus Project¶

The @colyseus/testing package provides a few utility methods for testing your Colyseus application. It can be used along with your favorite testing framework, such as Mocha, or Jest.

Recommendations and best practices¶

Make assertions on both server-side and client-side structures after simulating an exchange of messages between them.
Room instances are disposed between tests - make sure each test you declare is creating the room you're going to perform tests and don't re-use room instances between tests.
Always declare your test cases with async.
Before running assertions make sure you await for the server or client to process pending actions

Mocha + TypeScriptJest + TypeScript

import { ColyseusTestServer, boot } from "@colyseus/testing";

// import your "app.config.ts" file here.
import appConfig from "../src/app.config";

describe("testing your Colyseus app", () => {
  let colyseus: ColyseusTestServer;

  before(async () => colyseus = await boot(appConfig));
  after(async () => colyseus.shutdown());

  beforeEach(async () => await colyseus.cleanup());

  it("connecting into a room", async() => {
    // `room` is the server-side Room instance reference.
    const room = await colyseus.createRoom("my_room", {});

    // `client1` is the client-side `Room` instance reference (same as JavaScript SDK)
    const client1 = await colyseus.connectTo(room);

    // make your assertions
    assert.strictEqual(client1.sessionId, room.clients[0].sessionId);
  });
});

import { ColyseusTestServer, boot } from "@colyseus/testing";

// import your "app.config.ts" file here.
import appConfig from "../src/app.config";

describe("testing your Colyseus app", () => {
  let colyseus: ColyseusTestServer;

  beforeAll(async () => colyseus = await boot(appConfig));
  afterAll(async () => await colyseus.shutdown());

  beforeEach(async () => await colyseus.cleanup());

  it("connecting into a room", async() => {
    // `room` is the server-side Room instance reference.
    const room = await colyseus.createRoom("my_room", {});

    // `client1` is the client-side `Room` instance reference (same as JavaScript SDK)
    const client1 = await colyseus.connectTo(room);

    // make your assertions
    expect(client1.sessionId).toEqual(room.clients[0].sessionId);
  });
});

Waiting for asynchronous actions to process¶

`room.waitForMessage(type)`¶

Wait for a particular message type to arrive in the server.

it("should receive message", async() => {
    const room = await colyseus.createRoom("my_room");
    const client1 = await colyseus.connectTo(room);

    client1.send("foo", "payload");

    // wait for specific a message
    const [ client, message ] = await room.waitForMessage("foo");

    // ... message "foo" has been received and processed
    assert.strictEqual(client.sessionId, client1.sessionId);
    assert.strictEqual("payload", message);
});

`room.waitForNextMessage()`¶

Wait for any next message to arrive in the server.

Parameters

additionalDelay: number - additional delay after onMessage has been called in the server-side, in milliseconds (optional)

it("should receive message", async() => {
    const room = await colyseus.createRoom("my_room");
    const client1 = await colyseus.connectTo(room);

    let received = false;
    room.onMessage("foo", (client, message) => {
        received = true;
    });

    client1.send("foo");
    await room.waitForNextMessage();

    assert.ok(received);
});

`room.waitForNextPatch()`¶

Wait for the server to send the latest patched state to all clients.

it("client state must match server's after patch is received", async() => {
    const room = await colyseus.createRoom("my_room");
    const client1 = await colyseus.connectTo(room);

    await room.waitForNextPatch();

    // server and client's state must match after the patch
    assert.deepStrictEqual(client1.state.toJSON(), room.state.toJSON());
});

`room.waitForNextSimulationTick()`¶

Wait for the next simulation tick to complete.

it("should assert something after room's simulation tick", async() => {
    const room = await colyseus.createRoom("my_room");
    const client1 = await colyseus.connectTo(room);

    await room.waitForNextSimulationTick();

    // (this is just an illustration scenario)
    // (assuming the room's state has a "tick" property that updates during setSimulationInterval())
    assert.strictEqual(room.state.tick, 1);
});

Client-side SDK methods & utilities¶

From your test-cases, you may call any of the client-side SDK methods through colyseus.sdk

Example

it("should connect into battle_room with options x, y, z", async () => {
    const client = await colyseus.sdk.joinOrCreate("battle_room", {
        a: "a",
        b: "b",
        c: "c"
    });
    assert.ok(client.sessionId);
});

`client.waitForNextPatch()`¶

Wait for client state to be in sync with the server.

it("should do xyz after receiving message 'x'", async () => {
    const client = await colyseus.sdk.joinOrCreate("battle_room");
    await client.waitForNextPatch();
    // perform assertions after client has received a message
});

`client.waitForMessage(type)`¶

Wait for a particular message type to arrive in the client-side.

it("should do xyz after receiving message 'x'", async () => {
    const client = await colyseus.sdk.joinOrCreate("battle_room");
    client.send("ask-for-x");

    await client.waitForMessage("received-x");
    // perform assertions after client has received "received-x" message type.
});

`client.waitForNextMessage()`¶

Wait for any next message to arrive in the client.

it("should do xyz after receiving message 'x'", async () => {
    const client = await colyseus.sdk.joinOrCreate("battle_room");
    client.send("ask-for-x");

    await client.waitForNextMessage();
    // perform assertions after client has received a message
});

Testing HTTP Routes¶

The @colyseus/testing also offers an HTTP client for requesting your custom http routes:

colyseus.http.get(url, opts)
colyseus.http.post(url, opts)
colyseus.http.patch(url, opts)
colyseus.http.delete(url, opts)
colyseus.http.put(url, opts)

Example

it("should get json data", async () => {
    const response = await colyseus.http.get("/");

    // "data" is the response body
    assert.deepStrictEqual({ success: true }, response.data);

    // access to response headers.
    assert.strictEqual('header value', response.headers['some-header']);
});

Unit Testing a Colyseus Project¶

Recommendations and best practices¶

Waiting for asynchronous actions to process¶

room.waitForMessage(type)¶

room.waitForNextMessage()¶

room.waitForNextPatch()¶

room.waitForNextSimulationTick()¶