Etherpad Socket.IO Load Test Client

Common errors

• Connection refused

  cause The Etherpad instance is not running, the URL/port provided to the client is incorrect, or the `"loadTest": true` setting is missing on the server, causing the server to reject the specialized load test connection.
  fix Verify your Etherpad instance is running and accessible at the specified `etherpadUrl`. Double-check that `"loadTest": true` is set in `settings.json` and the Etherpad server has been restarted. Ensure no firewall is blocking the connection.

• Cannot find module 'etherpad-load-test-socket-io'

  cause The package `etherpad-load-test-socket-io` is not installed as a dependency in your project, or there's a mismatch between CommonJS `require` and ES Module `import` syntax in your environment.
  fix Install the package using `npm install etherpad-load-test-socket-io` or `yarn add etherpad-load-test-socket-io`. If using TypeScript or a bundler, ensure your configuration (e.g., `tsconfig.json`) supports ES module imports for Node.js modules, or use `const Client = require(...)` for CommonJS.

• Client received unexpected message format or no activity after connection.

  cause The Etherpad server might be configured incorrectly, or the specific pad ID is invalid/non-existent, leading to a lack of expected Socket.IO traffic. This can also happen if the client expects a specific protocol version or feature not supported by the Etherpad instance.
  fix Ensure the `padId` is valid on your Etherpad instance. Review the Etherpad server logs for any errors related to Socket.IO connections or pad access. Verify compatibility between the client library version and your Etherpad Lite server version, especially regarding Socket.IO protocol changes.

Warnings

• breaking To enable load testing functionality and allow clients to connect, the Etherpad Lite server *must* have `"loadTest": true` configured in its `settings.json` file. Failure to do so will prevent clients from establishing a proper connection or interacting with the server.
  Fix: Add `"loadTest": true` to your Etherpad Lite server's `settings.json` and restart the Etherpad instance.
• gotcha Forgetting to disable `"loadTest": true` in `settings.json` after completing load tests can leave your Etherpad instance vulnerable or impact its normal operation due to potential resource consumption or exposed internal APIs.
  Fix: Always set `"loadTest": false` in your Etherpad Lite `settings.json` and restart the server once load testing is complete.
• gotcha This package, `etherpad-load-test-socket-io`, is a client *library* for programmatic use. The command-line interface (CLI) described in the provided README (`etherpad-load-test` command) refers to a separate wrapper package, `etherpad-load-test`, which consumes this library. Direct CLI execution is not provided by `etherpad-load-test-socket-io` itself.
  Fix: If you intend to use a command-line interface, install `etherpad-load-test` globally (`npm install -g etherpad-load-test`). For programmatic use, import and instantiate the `Client` class from `etherpad-load-test-socket-io`.

Install

• npm install etherpad-load-test-socket-io npm
• yarn add etherpad-load-test-socket-io yarn
• pnpm add etherpad-load-test-socket-io pnpm

Imports

• Client
  wrong:

  const Client = require('etherpad-load-test-socket-io');

  correct:

  import Client from 'etherpad-load-test-socket-io';

  The primary export is a `Client` class/constructor as a default export, suitable for ES module imports.
• Client (CommonJS)
  wrong:

  import Client from 'etherpad-load-test-socket-io';

  correct:

  const Client = require('etherpad-load-test-socket-io');

  For CommonJS environments, `require` is the correct way to import the default-exported `Client` constructor.
• Client (Type)
  wrong:

  import { Client } from 'etherpad-load-test-socket-io';

  correct:

  import type Client from 'etherpad-load-test-socket-io';

  While the package itself may not ship explicit TypeScript declaration files, if types are provided externally (e.g., via `@types`), this is the correct way to import the type of the default-exported `Client` class.

Quickstart

This example demonstrates how to programmatically initialize and connect a single `etherpad-load-test-socket-io` client to a specific Etherpad pad, simulating a user for a set duration, and handling basic connection events.

import Client from 'etherpad-load-test-socket-io';

// Configuration for your Etherpad instance and the load test
const etherpadUrl = 'http://127.0.0.1:9001'; // Ensure your Etherpad instance is running here
const padId = 'myLoadTestPad';
const userId = 'testUser123';
const userName = 'Load Tester';
const readOnly = false; // true for lurkers, false for active authors

async function runSingleClientTest() {
  console.log(`Starting client for pad: ${padId}`);

  try {
    // Instantiate the client with Etherpad details
    const client = new Client(etherpadUrl, padId, userId, userName, readOnly);

    // Event listeners for client lifecycle and messages
    client.on('connect', () => {
      console.log(`Client ${userId} connected to ${etherpadUrl}/p/${padId}`);
      // Additional actions can be performed here, e.g., typing or sending messages
      // For a basic connection test, just connecting and waiting is sufficient.
    });

    client.on('disconnect', (reason: string) => {
      console.log(`Client ${userId} disconnected: ${reason}`);
    });

    client.on('error', (err: Error) => {
      console.error(`Client ${userId} error: ${err.message}`);
    });

    client.on('message', (msg: any) => {
      // console.log(`Client ${userId} received message:`, msg); // Can be very verbose for active pads
    });

    // Establish the connection to the Etherpad instance
    client.connect();

    // Keep the client connected for a duration (e.g., 30 seconds)
    console.log(`Keeping client ${userId} connected for 30 seconds...`);
    await new Promise(resolve => setTimeout(resolve, 30000));

    // Disconnect after the test duration
    client.disconnect();
    console.log(`Client ${userId} test finished.`);

  } catch (error) {
    console.error('Failed to initialize or run client:', error);
  }
}

runSingleClientTest();