@ably-labs/locust 0.0.1 → 0.0.5

package/README.md

@@ -10,7 +10,7 @@ _[Ably](https://ably.com) is the platform that powers synchronized digital exper
 
 ## Quick Start
 
-See [example/users.js](/example/users.js) for an example of defining Locust users in JavaScript, and [example/index.js](/example/index.js) for an example program which connects to a Locust master and runs the defined users during a load test.
+See [example/users.ts](/example/users.ts) for an example of defining Locust users in TypeScript, and [example/index.ts](/example/index.ts) for an example program which connects to a Locust master and runs the defined users during a load test.
 
 The example can be run by copying `example/.env.sample` to `example/.env`, setting `ABLY_API_KEY` to your Ably API key, and running [Docker Compose](https://docs.docker.com/compose/):
 
@@ -83,3 +83,15 @@ worker.register('ExampleUser', () => new User());
 
 worker.run();
 ```
+
+## Testing
+
+Start an instance of Locust and run the tests:
+
+```
+cd tests
+
+docker compose up --build
+
+npm test
+```

package/lib/Worker.d.ts

@@ -1,4 +1,4 @@
-import winston from 'winston';
+import * as winston from 'winston';
 import { Dealer } from 'zeromq';
 import { Message, MessageType } from './Message';
 import { Stats } from './Stats';
@@ -48,6 +48,10 @@ interface User {
  * A function which is registered with a worker to initialise a User.
  */
 declare type UserFn = () => User;
+/**
+ * A function which is called when an event happens.
+ */
+declare type EventFn = (data: any) => void;
 /**
  * A Locust worker which connects to a Locust master ZeroMQ socket and spawns
  * Locust users during an active load test.
@@ -105,6 +109,12 @@ export declare class Worker {
      * discard outdated messages.
      */
     lastReceivedSpawnTimestamp: number;
+    /**
+     * A set of functions which are called when events happen.
+     */
+    callbacks: {
+        [key: string]: EventFn[];
+    };
     constructor(opts: Options);
     /**
      * Register a function to initialise users of the given class name.
@@ -120,6 +130,18 @@ export declare class Worker {
      *
      */
     run(): Promise<void>;
+    /**
+     * Register a callback to be called when an event happens.
+     */
+    on(event: string, callback: (data: any) => void): void;
+    /**
+     * Register a callback to be called when a user starts.
+     */
+    onUserStart(callback: EventFn): void;
+    /**
+     * Register a callback to be called when a user stops.
+     */
+    onUserStop(callback: EventFn): void;
     /**
      * Send a protocol message to the Locust master.
      */
@@ -195,5 +217,9 @@ export declare class Worker {
         };
         user_count: number;
     };
+    /**
+     * Invoke all callbacks for the given event with the given data.
+     */
+    emit(event: string, data: any): void;
 }
 export {};

package/lib/Worker.js

@@ -1,4 +1,23 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
     function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
     return new (P || (P = Promise))(function (resolve, reject) {
@@ -42,12 +61,9 @@ var __asyncValues = (this && this.__asyncValues) || function (o) {
     function verb(n) { i[n] = o[n] && function (v) { return new Promise(function (resolve, reject) { v = o[n](v), settle(resolve, reject, v.done, v.value); }); }; }
     function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }
 };
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Worker = void 0;
-var winston_1 = __importDefault(require("winston"));
+var winston = __importStar(require("winston"));
 var zeromq_1 = require("zeromq");
 var constants_1 = require("./constants");
 var Message_1 = require("./Message");
@@ -72,15 +88,16 @@ var Worker = /** @class */ (function () {
         this.userFns = {};
         this.users = {};
         this.state = "ready" /* Ready */;
-        this.log = winston_1.default.createLogger({
-            format: winston_1.default.format.combine(winston_1.default.format.timestamp(), winston_1.default.format.json()),
+        this.log = winston.createLogger({
+            format: winston.format.combine(winston.format.timestamp(), winston.format.json()),
             transports: [
-                new winston_1.default.transports.Console({
+                new winston.transports.Console({
                     level: opts.logLevel || 'info',
                 }),
             ],
         });
         this.lastReceivedSpawnTimestamp = 0;
+        this.callbacks = {};
     }
     /**
      * Register a function to initialise users of the given class name.
@@ -127,7 +144,7 @@ var Worker = /** @class */ (function () {
                         data = _c.value[0];
                         try {
                             msg = Message_1.Message.decode(data);
-                            this.log.info("Received '" + msg.type + "' message");
+                            this.log.debug("Received '" + msg.type + "' message");
                             this.handle(msg);
                         }
                         catch (err) {
@@ -157,6 +174,27 @@ var Worker = /** @class */ (function () {
             });
         });
     };
+    /**
+     * Register a callback to be called when an event happens.
+     */
+    Worker.prototype.on = function (event, callback) {
+        if (!this.callbacks[event]) {
+            this.callbacks[event] = [];
+        }
+        this.callbacks[event].push(callback);
+    };
+    /**
+     * Register a callback to be called when a user starts.
+     */
+    Worker.prototype.onUserStart = function (callback) {
+        this.on('user.start', callback);
+    };
+    /**
+     * Register a callback to be called when a user stops.
+     */
+    Worker.prototype.onUserStop = function (callback) {
+        this.on('user.stop', callback);
+    };
     /**
      * Send a protocol message to the Locust master.
      */
@@ -199,6 +237,7 @@ var Worker = /** @class */ (function () {
         this.lastReceivedSpawnTimestamp = data.timestamp;
         this.state = "spawning" /* Spawning */;
         this.send("spawning" /* Spawning */, null);
+        this.log.info("Handling spawn message: expected = " + JSON.stringify(data.user_classes_count) + ", actual = " + JSON.stringify(this.spawnState().user_classes_count));
         for (var _i = 0, _a = Object.keys(data.user_classes_count); _i < _a.length; _i++) {
             var userClass = _a[_i];
             // check we have a registered function for the given class
@@ -279,11 +318,13 @@ var Worker = /** @class */ (function () {
      * Start the given number of users.
      */
     Worker.prototype.startUsers = function (userClass, userFn, count) {
+        this.log.debug("Starting " + count + " " + userClass + " users");
         for (var i = 0; i < count; i++) {
             try {
                 var user = userFn();
                 user.start();
                 this.users[userClass].push(user);
+                this.emit('user.start', { userClass: userClass });
             }
             catch (err) {
                 this.logException("Error initialising " + userClass + " user: " + err);
@@ -301,10 +342,12 @@ var Worker = /** @class */ (function () {
      * Stop the given number of users.
      */
     Worker.prototype.stopUsers = function (userClass, count) {
+        this.log.debug("Stopping " + count + " " + userClass + " users");
         for (var i = 0; i < count; i++) {
             var user = this.users[userClass].pop();
             if (user !== undefined) {
                 user.stop();
+                this.emit('user.stop', { userClass: userClass });
             }
         }
     };
@@ -378,6 +421,19 @@ var Worker = /** @class */ (function () {
             user_count: Object.values(this.users).reduce(function (sum, users) { return sum + users.length; }, 0),
         };
     };
+    /**
+     * Invoke all callbacks for the given event with the given data.
+     */
+    Worker.prototype.emit = function (event, data) {
+        var callbacks = this.callbacks[event];
+        if (!callbacks) {
+            return;
+        }
+        for (var _i = 0, callbacks_1 = callbacks; _i < callbacks_1.length; _i++) {
+            var callback = callbacks_1[_i];
+            callback(data);
+        }
+    };
     return Worker;
 }());
 exports.Worker = Worker;

package/lib/constants.d.ts

@@ -6,7 +6,7 @@
  *
  * See https://github.com/locustio/locust/blob/2.4.3/locust/runners.py#L879-L886
  */
-export declare const PROTOCOL_VERSION = "2.4.3";
+export declare const PROTOCOL_VERSION = "2.5.0";
 /**
  * The interval between successive heartbeats.
  */

package/lib/constants.js

@@ -9,7 +9,7 @@ exports.STATS_INTERVAL = exports.HEARTBEAT_INTERVAL = exports.PROTOCOL_VERSION =
  *
  * See https://github.com/locustio/locust/blob/2.4.3/locust/runners.py#L879-L886
  */
-exports.PROTOCOL_VERSION = '2.4.3';
+exports.PROTOCOL_VERSION = '2.5.0';
 /**
  * The interval between successive heartbeats.
  */

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@ably-labs/locust",
-  "version": "0.0.1",
+  "version": "0.0.5",
   "description": "A JavaScript load generator for Locust.io.",
   "main": "lib/index.js",
+  "types": "lib/index.d.ts",
   "scripts": {
     "build": "tsc --build",
     "clean": "tsc --build --clean",
@@ -11,7 +12,7 @@
     "test": "jest"
   },
   "files": [
-    "lib"
+    "lib/**/*"
   ],
   "repository": {
     "type": "git",