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). Use it 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 ws://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((code, message) => {
        console.log(room.sessionId, "!! ERROR !!", message);
    })
 
    room.onLeave((code) => {
        console.log(room.sessionId, "left.");
    });
}
 
cli(main);

Monitoring Panel Unit Testing