loadtest 5.2.0 → 6.1.0

package/.eslintrc

@@ -6,7 +6,7 @@ env:
 extends: eslint:recommended
 parserOptions:
   sourceType: module
-  ecmaVersion: 8
+  ecmaVersion: 14
 rules:
   no-inner-declarations: 0
   no-unused-vars:

package/README.md

@@ -33,8 +33,9 @@ For access to the API just add package `loadtest` to your `package.json` devDepe
 
 ### Compatibility
 
-Versions 5 and later should be used at least with Node.js v10 or later:
+Versions 6 and later should be used at least with Node.js v16 or later:
 
+* Node.js v16 or later: ^6.0.0
 * Node.js v10 or later: ^5.0.0
 * Node.js v8 or later: 4.x.y.
 * Node.js v6 or earlier: ^3.1.0.
@@ -83,7 +84,7 @@ but the resulting figure is much more robust.
 `loadtest` is also quite extensible.
 Using the provided API it is very easy to integrate loadtest with your package, and run programmatic load tests.
 loadtest makes it very easy to run load tests as part of systems tests, before deploying a new version of your software.
-The results include mean response times and percentiles,
+The result includes mean response times and percentiles,
 so that you can abort deployment e.g. if 99% of the requests don't finish in 10 ms or less.
 
 ### Usage Don'ts
@@ -110,6 +111,7 @@ The following parameters are compatible with Apache ab.
 #### `-n requests`
 
 Number of requests to send out.
+Default is no limit; will keep on sending if not specified.
 
 Note: the total number of requests sent can be bigger than the parameter if there is a concurrency parameter;
 loadtest will report just the first `n`.
@@ -118,6 +120,7 @@ loadtest will report just the first `n`.
 
 loadtest will create a certain number of clients; this parameter controls how many.
 Requests from them will arrive concurrently to the server.
+Default value is 1.
 
 Note: requests are not sent in parallel (from different processes),
 but concurrently (a second request may be sent before the first has been answered).
@@ -125,6 +128,7 @@ but concurrently (a second request may be sent before the first has been answere
 #### `-t timelimit`
 
 Max number of seconds to wait until requests no longer go out.
+Default is no limit; will keep on sending if not specified.
 
 Note: this is different than Apache `ab`, which stops _receiving_ requests after the given seconds.
 
@@ -174,59 +178,63 @@ Send the string as the PATCH body. E.g.: `-A '{"key": "a9acf03f"}'`
 
 #### `-m method`
 
-Send method to link. Accept: [GET, POST, PUT, DELETE, PATCH, get, post, put, delete, patch], Default is GET
-E.g.: -m POST
+Set method that will be sent to the test URL.
+Accepts: `GET`, `POST`, `PUT`, `DELETE`, `PATCH`,
+and lowercase versions. Default is `GET`.
+Example: `-m POST`.
 
-#### `--data POST some variables`
+#### `--data body`
 
-Send some data. It does not support method GET.
-E.g: `--data '{"username": "test", "password": "test"}' -T 'application/x-www-form-urlencoded' -m POST`
+Add some data to send in the body. It does not support method GET.
+Requires setting the method with `-m` and the type with `-T`.
+Example: `--data '{"username": "test", "password": "test"}' -T 'application/x-www-form-urlencoded' -m POST`
 
-It required `-m` and `-T 'application/x-www-form-urlencoded'`
 
 #### `-p POST-file`
 
 Send the data contained in the given file in the POST body.
 Remember to set `-T` to the correct content-type.
 
-If `POST-file` has `.js` extension it will be `require`d. It should be a valid node module and it
-should `export` a single function, which is invoked with an automatically generated request identifier
+If `POST-file` has `.js` extension it will be `import`ed. It should be a valid node module and it
+should `export` a default function, which is invoked with an automatically generated request identifier
 to provide the body of each request.
 This is useful if you want to generate request bodies dynamically and vary them for each request.
 
 Example:
 
 ```javascript
-module.exports = function(requestId) {
+export default function request(requestId) {
   // this object will be serialized to JSON and sent in the body of the request
   return {
 	key: 'value',
 	requestId: requestId
-  };
-};
+  }
+}
 ```
 
+See sample file in `sample/post-file.js`, and test in `test/body-generator.js`.
+
 #### `-u PUT-file`
 
 Send the data contained in the given file as a PUT request.
 Remember to set `-T` to the correct content-type.
 
-If `PUT-file` has `.js` extension it will be `require`d. It should be a valid node module and it
-should `export` a single function, which is invoked with an automatically generated request identifier
+If `PUT-file` has `.js` extension it will be `import`ed. It should be a valid node module and it
+should `export` a default function, which is invoked with an automatically generated request identifier
 to provide the body of each request.
 This is useful if you want to generate request bodies dynamically and vary them for each request.
-For an example function see above for `-p`.
+For examples see above for `-p`.
 
 #### `-a PATCH-file`
 
 Send the data contained in the given file as a PATCH request.
 Remember to set `-T` to the correct content-type.
 
-If `PATCH-file` has `.js` extension it will be `require`d. It should be a valid node module and it
-should `export` a single function, which is invoked with an automatically generated request identifier
+If `PATCH-file` has `.js` extension it will be `import`ed. It should be a valid node module and it
+should `export` a default function, which is invoked with an automatically generated request identifier
 to provide the body of each request.
 This is useful if you want to generate request bodies dynamically and vary them for each request.
-For an example function see above for `-p`.
+For examples see above for `-p`.
 
 ##### `-r`
 
@@ -253,6 +261,7 @@ The following parameters are _not_ compatible with Apache ab.
 
 Controls the number of requests per second that are sent.
 Can be fractional, e.g. `--rps 0.5` sends one request every two seconds.
+Not used by default: each request is sent as soon as the previous one is responded.
 
 Note: Concurrency doesn't affect the final number of requests per second,
 since rps will be shared by all the clients. E.g.:
@@ -310,10 +319,12 @@ Note: instead of using the default agent, this option is now an alias for `-k`.
 
 Do not show any messages.
 
-#### `--debug`
+#### `--debug` (deprecated)
 
 Show debug messages.
 
+Note: deprecated in version 6+.
+
 #### `--insecure`
 
 Allow invalid and self-signed certificates over https.
@@ -376,7 +387,7 @@ with concurrency 10 (only relevant results are shown):
       99%      14 ms
      100%      35997 ms (longest request)
 
-Results were quite erratic, with some requests taking up to 36 seconds;
+The result was quite erratic, with some requests taking up to 36 seconds;
 this suggests that Node.js is queueing some requests for a long time, and answering them irregularly.
 Now we will try a fixed rate of 1000 rps:
 
@@ -431,10 +442,10 @@ We now know that our server can accept 500 rps without problems.
 Not bad for a single-process naïve Node.js server...
 We may refine our results further to find at which point from 500 to 1000 rps our server breaks down.
 
-But instead let us research how to improve the results.
+But instead let us research how to improve the result.
 One obvious candidate is to add keep-alive to the requests so we don't have to create
 a new connection for every request.
-The results (with the same test server) are impressive:
+The result (with the same test server) is impressive:
 
     $ loadtest http://localhost:7357/ -t 20 -c 10 -k
     ...
@@ -473,19 +484,18 @@ thus allowing you to load test your application in your own tests.
 To run a load test, just call the exported function `loadTest()` with a set of options and an optional callback:
 
 ```javascript
-const loadtest = require('loadtest');
+import {loadTest} from 'loadtest'
+
 const options = {
 	url: 'http://localhost:8000',
 	maxRequests: 1000,
-};
-loadtest.loadTest(options, function(error, result)
-{
-	if (error)
-	{
-		return console.error('Got an error: %s', error);
+}
+loadTest(options, function(error, result) {
+	if (error) {
+		return console.error('Got an error: %s', error)
 	}
-	console.log('Tests run successfully');
-});
+	console.log('Tests run successfully')
+})
 ```
 
 The callback `function(error, result)` will be invoked when the max number of requests is reached,
@@ -588,10 +598,12 @@ Use an agent with 'Connection: Keep-alive'.
 Note: Uses [agentkeepalive](https://npmjs.org/package/agentkeepalive),
 which performs better than the default node.js agent.
 
-#### `quiet`
+#### `quiet` (deprecated)
 
 Do not show any messages.
 
+Note: deprecated in version 6+, shows a warning.
+
 #### `indexParam`
 
 The given string will be replaced in the final URL with a unique index.
@@ -633,29 +645,29 @@ The TLS/SSL method to use. (e.g. TLSv1_method)
 Example:
 
 ```javascript
-const loadtest = require('loadtest');
+import {loadTest} from 'loadtest'
 
 const options = {
 	url: 'https://www.example.com',
     maxRequests: 100,
     secureProtocol: 'TLSv1_method'
-};
+}
 
-loadtest.loadTest(options, function(error) {
+loadTest(options, function(error) {
 	if (error) {
-		return console.error('Got an error: %s', error);
+		return console.error('Got an error: %s', error)
 	}
-	console.log('Tests run successfully');
-});
+	console.log('Tests run successfully')
+})
 ```
 
 #### `statusCallback`
 
-If present, this function executes after every request operation completes. Provides immediate access to test results while the
+If present, this function executes after every request operation completes. Provides immediate access to the test result while the
 test batch is still running. This can be used for more detailed custom logging or developing your own spreadsheet or
-statistical analysis of results.
+statistical analysis of the result.
 
-The results and error passed to the callback are in the same format as the results passed to the final callback.
+The result and error passed to the callback are in the same format as the result passed to the final callback.
  
 In addition, the following three properties are added to the `result` object:
 
@@ -668,28 +680,28 @@ You will need to check if `error` is populated in order to determine which objec
 Example:
 
 ```javascript
-const loadtest = require('loadtest');
+import {loadTest} from 'loadtest'
 
 function statusCallback(error, result, latency) {
-    console.log('Current latency %j, result %j, error %j', latency, result, error);
-    console.log('----');
-    console.log('Request elapsed milliseconds: ', result.requestElapsed);
-    console.log('Request index: ', result.requestIndex);
-    console.log('Request loadtest() instance index: ', result.instanceIndex);
+    console.log('Current latency %j, result %j, error %j', latency, result, error)
+    console.log('----')
+    console.log('Request elapsed milliseconds: ', result.requestElapsed)
+    console.log('Request index: ', result.requestIndex)
+    console.log('Request loadtest() instance index: ', result.instanceIndex)
 }
 
 const options = {
     url: 'http://localhost:8000',
     maxRequests: 1000,
     statusCallback: statusCallback
-};
+}
 
-loadtest.loadTest(options, function(error) {
+loadTest(options, function(error) {
     if (error) {
-        return console.error('Got an error: %s', error);
+        return console.error('Got an error: %s', error)
     }
-    console.log('Tests run successfully');
-});
+    console.log('Tests run successfully')
+})
 ```
 
  
@@ -746,9 +758,9 @@ function contentInspector(result) {
 },
 ```
 
-### Results
+### Result
 
-The latency results passed to your callback at the end of the load test contains a full set of data, including:
+The latency result passed to your callback at the end of the load test contains a full set of data, including:
 mean latency, number of errors and percentiles.
 An example follows:
 
@@ -788,14 +800,20 @@ The second parameter contains info about the current request:
     
 ### Start Test Server
 
-To start the test server use the exported function `startServer()` with a set of options and an optional callback:
+To start the test server use the exported function `startServer()` with a set of options:
 
 ```javascript
-const testserver = require('testserver');
-const server = testserver.startServer({ port: 8000 });
+import {startServer} from 'loadtest'
+const server = await startServer({port: 8000})
 ```
 
 This function returns an HTTP server which can be `close()`d when it is no longer useful.
+As a legacy from before promises existed,
+if the optional callback is passed then it will not behave as `async`:
+
+```
+const server = startServer({port: 8000}, error => console.error(error))
+```
 
 The following options are available.
 
@@ -856,11 +874,13 @@ The expected structure of the file is the following:
 }
 ```
 
+See sample file in `sample/.loadtestrc`.
+
 For more information about the actual configuration file name, read the [confinode user manual](https://github.com/slune-org/confinode/blob/master/doc/en/usermanual.md#configuration-search). In the list of the [supported file types](https://github.com/slune-org/confinode/blob/master/doc/extensions.md), please note that only synchronous loaders can be used with _loadtest_.
 
 ### Complete Example
 
-The file `lib/integration.js` shows a complete example, which is also a full integration test:
+The file `test/integration.js` shows a complete example, which is also a full integration test:
 it starts the server, send 1000 requests, waits for the callback and closes down the server.
 
 ## Versioning

package/bin/loadtest.js

@@ -1,22 +1,11 @@
 #!/usr/bin/env node
-'use strict';
 
-/**
- * Binary to run loadtest.
- * (C) 2013 Manuel Ernst, Alex Fernández.
- */
+import {readFile} from 'fs/promises'
+import * as stdio from 'stdio'
+import {loadTest} from '../lib/loadtest.js'
+import {showResult} from '../lib/show.js'
 
-// requires
-const stdio = require('stdio');
-const fs = require('fs');
-const path = require('path');
-const urlLib = require('url');
-const loadTest = require('../lib/loadtest.js');
-const headers = require('../lib/headers.js');
-const packageJson = require(__dirname + '/../package.json');
-const config = require('../lib/config');
 
-// init
 const options = stdio.getopt({
 	maxRequests: {key: 'n', args: 1, description: 'Number of requests to perform'},
 	concurrency: {key: 'c', args: 1, description: 'Number of requests to make'},
@@ -39,156 +28,41 @@ const options = stdio.getopt({
 	version: {key: 'V', description: 'Show version number and exit'},
 	proxy: {args: 1, description: 'Use a proxy for requests e.g. http://localhost:8080 '},	
 	rps: {args: 1, description: 'Specify the requests per second for each client'},
-	agent: {description: 'Use a keep-alive http agent (deprecated)'},
 	index: {args: 1, description: 'Replace the value of given arg with an index in the URL'},
-	quiet: {description: 'Do not log any messages'},
-	debug: {description: 'Show debug messages'},
 	insecure: {description: 'Allow self-signed certificates over https'},
 	key: {args: 1, description: 'The client key to use'},
-	cert: {args: 1, description: 'The client certificate to use'}
+	cert: {args: 1, description: 'The client certificate to use'},
+	quiet: {description: 'Do not log any messages'},
+	agent: {description: 'Use a keep-alive http agent (deprecated)'},
+	debug: {description: 'Show debug messages (deprecated)'}
 });
-if (options.version) {
-	console.log('Loadtest version: %s', packageJson.version);
-	process.exit(0);
-}
-// is there an url? if not, break and display help
-if (!options.args || options.args.length < 1) {
-	console.error('Missing URL to load-test');
-	help();
-} else if (options.args.length > 1) {
-	console.error('Too many arguments: %s', options.args);
-	help();
-}
-
-const configuration = config.loadConfig(options);
 
-options.url = options.args[0];
-options.agentKeepAlive = options.keepalive || options.agent || configuration.agentKeepAlive;
-options.indexParam = options.index || configuration.indexParam;
-
-//TODO: add index Param
-// Allow a post body string in options
-// Ex -P '{"foo": "bar"}'
-if (options.postBody) {
-	options.method = 'POST';
-	options.body = options.postBody;
-}
-if (options.postFile) {
-	options.method = 'POST';
-	options.body = readBody(options.postFile, '-p');
-}
-if (options.data) {
-	options.body = JSON.parse(options.data);
-}
-if (options.method) {
-	const acceptedMethods = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'get', 'post', 'put', 'delete', 'patch'];
-	if (acceptedMethods.indexOf(options.method) === -1) {
-		options.method = 'GET';
-	}
-}
-if(options.putFile) {
-	options.method = 'PUT';
-	options.body = readBody(options.putFile, '-u');
-}
-if (options.patchBody) {
-	options.method = 'PATCH';
-	options.body = options.patchBody;
-}
-if(options.patchFile) {
-	options.method = 'PATCH';
-	options.body = readBody(options.patchFile, '-a');
-}
-if(!options.method) {
-	options.method = configuration.method;
-}
-if(!options.body) {
-	if(configuration.body) {
-		options.body = configuration.body;
-	} else if(configuration.file) {
-		options.body = readBody(configuration.file, 'configuration.request.file');
+async function processAndRun(options) {
+	if (options.version) {
+		const packageJson = JSON.parse(await readFile(new URL('../package.json', import.meta.url)))
+		console.log('Loadtest version: %s', packageJson.version);
+		process.exit(0);
 	}
-}
-options.requestsPerSecond = options.rps ? parseFloat(options.rps) : configuration.requestsPerSecond;
-if(!options.key) {
-	options.key = configuration.key;
-}
-if(options.key) {
-	options.key = fs.readFileSync(options.key);
-}
-if(!options.cert) {
-	options.cert = configuration.cert;
-}
-if(options.cert) {
-	options.cert = fs.readFileSync(options.cert);
-}
-
-const defaultHeaders = options.headers || !configuration.headers ? {} : configuration.headers;
-defaultHeaders['host'] = urlLib.parse(options.url).host;
-defaultHeaders['user-agent'] = 'loadtest/' + packageJson.version;
-defaultHeaders['accept'] = '*/*';
-
-if (options.headers) {
-	headers.addHeaders(options.headers, defaultHeaders);
-	console.log('headers: %s, %j', typeof defaultHeaders, defaultHeaders);
-}
-options.headers = defaultHeaders;
-
-if (!options.requestGenerator) {
-	options.requestGenerator = configuration.requestGenerator;
-}
-if (options.requestGenerator) {
-	options.requestGenerator = require(path.resolve(options.requestGenerator));
-}
-
-// Use configuration file for other values
-if(!options.maxRequests) {
-	options.maxRequests = configuration.maxRequests;
-}
-if(!options.concurrency) {
-	options.concurrency = configuration.concurrency;
-}
-if(!options.maxSeconds) {
-	options.maxSeconds = configuration.maxSeconds;
-}
-if(!options.timeout && configuration.timeout) {
-	options.timeout = configuration.timeout;
-}
-if(!options.contentType) {
-	options.contentType = configuration.contentType;
-}
-if(!options.cookies) {
-	options.cookies = configuration.cookies;
-}
-if(!options.secureProtocol) {
-	options.secureProtocol = configuration.secureProtocol;
-}
-if(!options.insecure) {
-	options.insecure = configuration.insecure;
-}
-if(!options.recover) {
-	options.recover = configuration.recover;
-}
-if(!options.proxy) {
-	options.proxy = configuration.proxy;
-}
-
-loadTest.loadTest(options);
-
-function readBody(filename, option) {
-	if (typeof filename !== 'string') {
-		console.error('Invalid file to open with %s: %s', option, filename);
+	// is there an url? if not, break and display help
+	if (!options.args || options.args.length < 1) {
+		console.error('Missing URL to load-test');
+		help();
+	} else if (options.args.length > 1) {
+		console.error('Too many arguments: %s', options.args);
 		help();
 	}
-
-	if(path.extname(filename) === '.js') {
-		return require(path.resolve(filename));
+	options.url = options.args[0];
+	try {
+		const result = await loadTest(options)
+		showResult(options, result)
+	} catch(error) {
+		console.error(error.message)
+		help()
 	}
-
-	const ret = fs.readFileSync(filename, {encoding: 'utf8'}).replace("\n", "");
-
-	return ret;
 }
 
+await processAndRun(options)
+
 /**
  * Show online help.
  */

package/bin/testserver.js

@@ -1,23 +1,16 @@
 #!/usr/bin/env node
-'use strict';
 
-/**
- * Binary to run test server.
- * (C) 2013 Manuel Ernst, Alex Fernández.
- */
+import * as stdio from 'stdio'
+import {startServer} from '../lib/testserver.js'
+import {loadConfig} from '../lib/config.js'
 
-// requires
-const stdio = require('stdio');
-const testServer = require('../lib/testserver');
-const config = require('../lib/config')
 
-// init
 const options = stdio.getopt({
 	delay: {key: 'd', args: 1, description: 'Delay the response for the given milliseconds'},
 	error: {key: 'e', args: 1, description: 'Return an HTTP error code'},
 	percent: {key: 'p', args: 1, description: 'Return an error (default 500) only for some % of requests'},
 });
-const configuration = config.loadConfig(options)
+const configuration = loadConfig()
 if (options.args && options.args.length == 1) {
 	options.port = parseInt(options.args[0], 10);
 	if (!options.port) {
@@ -45,5 +38,5 @@ if(!options.percent) {
 	options.percent = configuration.percent
 }
 
-testServer.startServer(options);
+startServer(options);
 

package/index.js

@@ -1,16 +1,10 @@
-'use strict';
+import {loadTest} from './lib/loadtest.js'
+import {startServer} from './lib/testserver.js'
 
-/**
- * Package contains a load test script and a test server.
- * (C) 2013 Alex Fernández.
- */
+const loadtest = {loadTest, startServer}
 
+export default loadtest
 
-// requires
-const loadtest = require('./lib/loadtest.js');
-const testserver = require('./lib/testserver.js');
-
-// exports
-exports.loadTest = loadtest.loadTest;
-exports.startServer = testserver.startServer;
+export * from './lib/loadtest.js'
+export * from './lib/testserver.js'
 

package/lib/baseClient.js

@@ -1,14 +1,8 @@
-"use strict";
+import * as urlLib from 'url'
+import {addUserAgent} from './headers.js'
 
-const urlLib = require('url');
-const Log = require('log');
-const headers = require('./headers.js');
 
-// globals
-const log = new Log('info');
-
-
-class BaseClient {
+export class BaseClient {
 	constructor(operation, params) {
 		this.operation = operation;
 		this.params = params;
@@ -22,14 +16,11 @@ class BaseClient {
 		return (error, result) => {
 			let errorCode = null;
 			if (error) {
-				log.debug('Connection %s failed: %s', id, error);
 				if (result) {
 					errorCode = result;
 				} else {
 					errorCode = '-1';
 				}
-			} else {
-				log.debug('Connection %s ended', id);
 			}
 			this.operation.latency.end(id, errorCode);
 			let callback;
@@ -56,28 +47,20 @@ class BaseClient {
 		this.options.agent = false;
 		if (this.params.body) {
 			if (typeof this.params.body == 'string') {
-				log.debug('Received string body');
 				this.generateMessage = () => this.params.body;
 			} else if (typeof this.params.body == 'object') {
-				log.debug('Received JSON body');
 				this.generateMessage = () => this.params.body;
 			} else if (typeof this.params.body == 'function') {
-				log.debug('Received function body');
 				this.generateMessage = this.params.body;
 			} else {
-				log.error('Unrecognized body: %s', typeof this.params.body);
+				console.error('Unrecognized body: %s', typeof this.params.body);
 			}
 			this.options.headers['Content-Type'] = this.params.contentType || 'text/plain';
 		}
-		headers.addUserAgent(this.options.headers);
+		addUserAgent(this.options.headers);
 		if (this.params.secureProtocol) {
 			this.options.secureProtocol = this.params.secureProtocol;
 		}
-		log.debug('Options: %j',this.options);
 	}
 }
 
-module.exports = {
-	BaseClient,
-}
-