{"id":14564,"library":"etherpad-load-test-socket-io","title":"Etherpad Socket.IO Load Test Client","description":"`etherpad-load-test-socket-io` is a client library providing the core logic for programmatically load testing an Etherpad instance via its Socket.IO API. It simulates various user activities, such as \"lurkers\" (viewers) and \"active authors\" (editors), to gauge the performance and scalability of an Etherpad server. While this package provides the underlying client functionality, it is typically consumed by higher-level command-line tools, such as `etherpad-load-test`, which offer a more user-friendly interface for executing load tests. The current stable version is 1.0.3, with a Node.js engine requirement of `>=18.0.0`. Its release cadence aligns with the development of the `etherpad-load-test` CLI and the broader Etherpad project, focusing on stability and compatibility with Etherpad Lite. Its key differentiator is its direct, low-level interaction with Etherpad's Socket.IO protocol, enabling deep customization of load testing scenarios.","status":"active","version":"1.0.3","language":"javascript","source_language":"en","source_url":"https://github.com/ether/etherpad-load-test","tags":["javascript"],"install":[{"cmd":"npm install etherpad-load-test-socket-io","lang":"bash","label":"npm"},{"cmd":"yarn add etherpad-load-test-socket-io","lang":"bash","label":"yarn"},{"cmd":"pnpm add etherpad-load-test-socket-io","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This is a peer dependency for the Etherpad server, indicating that the server must be configured with specific load testing capabilities to work with this client.","package":"ep_etherpad-lite","optional":false}],"imports":[{"note":"The primary export is a `Client` class/constructor as a default export, suitable for ES module imports.","wrong":"const Client = require('etherpad-load-test-socket-io');","symbol":"Client","correct":"import Client from 'etherpad-load-test-socket-io';"},{"note":"For CommonJS environments, `require` is the correct way to import the default-exported `Client` constructor.","wrong":"import Client from 'etherpad-load-test-socket-io';","symbol":"Client (CommonJS)","correct":"const Client = require('etherpad-load-test-socket-io');"},{"note":"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.","wrong":"import { Client } from 'etherpad-load-test-socket-io';","symbol":"Client (Type)","correct":"import type Client from 'etherpad-load-test-socket-io';"}],"quickstart":{"code":"import Client from 'etherpad-load-test-socket-io';\n\n// Configuration for your Etherpad instance and the load test\nconst etherpadUrl = 'http://127.0.0.1:9001'; // Ensure your Etherpad instance is running here\nconst padId = 'myLoadTestPad';\nconst userId = 'testUser123';\nconst userName = 'Load Tester';\nconst readOnly = false; // true for lurkers, false for active authors\n\nasync function runSingleClientTest() {\n  console.log(`Starting client for pad: ${padId}`);\n\n  try {\n    // Instantiate the client with Etherpad details\n    const client = new Client(etherpadUrl, padId, userId, userName, readOnly);\n\n    // Event listeners for client lifecycle and messages\n    client.on('connect', () => {\n      console.log(`Client ${userId} connected to ${etherpadUrl}/p/${padId}`);\n      // Additional actions can be performed here, e.g., typing or sending messages\n      // For a basic connection test, just connecting and waiting is sufficient.\n    });\n\n    client.on('disconnect', (reason: string) => {\n      console.log(`Client ${userId} disconnected: ${reason}`);\n    });\n\n    client.on('error', (err: Error) => {\n      console.error(`Client ${userId} error: ${err.message}`);\n    });\n\n    client.on('message', (msg: any) => {\n      // console.log(`Client ${userId} received message:`, msg); // Can be very verbose for active pads\n    });\n\n    // Establish the connection to the Etherpad instance\n    client.connect();\n\n    // Keep the client connected for a duration (e.g., 30 seconds)\n    console.log(`Keeping client ${userId} connected for 30 seconds...`);\n    await new Promise(resolve => setTimeout(resolve, 30000));\n\n    // Disconnect after the test duration\n    client.disconnect();\n    console.log(`Client ${userId} test finished.`);\n\n  } catch (error) {\n    console.error('Failed to initialize or run client:', error);\n  }\n}\n\nrunSingleClientTest();\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Add `\"loadTest\": true` to your Etherpad Lite server's `settings.json` and restart the Etherpad instance.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Always set `\"loadTest\": false` in your Etherpad Lite `settings.json` and restart the server once load testing is complete.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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.","error":"Connection refused"},{"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.","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.","error":"Cannot find module 'etherpad-load-test-socket-io'"},{"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.","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.","error":"Client received unexpected message format or no activity after connection."}],"ecosystem":"npm"}