Load Testing

The @colyseus/loadtest tool lets you stress test your Colyseus server by simulating multiple concurrent client connections. Each simulated client runs a custom script where you can implement bot behavior — joining rooms, sending messages, and reacting to state changes — to verify how your server performs under load.

Installation

This package is installed by default on new projects created via npm create colyseus-app.

npm install --save-dev @colyseus/loadtest

pnpm add --save-dev @colyseus/loadtest

yarn add --dev @colyseus/loadtest

bun add --dev @colyseus/loadtest

Usage

Run the load test command with the following arguments:

script — path to your custom client script
--room — name of the room to connect to
--numClients — number of simulated clients to spawn
--endpoint — your server endpoint (defaults to http://localhost:2567)

For example, to connect 50 clients into a "battle" room:

Terminal

npx tsx loadtest/example.ts --room battle --numClients 50 --endpoint http://localhost:2567

Scripting

Each simulated client executes the script you provide. Use room lifecycle events to implement bot behavior that interacts with the room during the test.

loadtest/example.ts

import { Client, Room } from "@colyseus/sdk";
import { cli, Options } from "@colyseus/loadtest";
 
async function main(options: Options) {
    const client = new Client(options.endpoint);
    const room: Room = await client.joinOrCreate(options.roomName, {
        // your join options here...
    });
 
    console.log("joined successfully!");
 
    room.onMessage("*", (type, message) => {
        console.log("onMessage:", type, message);
    });
 
    room.onStateChange((state) => {
        console.log(room.sessionId, "new state:", state);
    });
 
    room.onError((err) => {
        console.log(room.sessionId, "!! ERROR !!", err.message);
    })
 
    room.onLeave((code) => {
        console.log(room.sessionId, "left.");
    });
}
 
cli(main);

Monitoring Panel Unit Testing