loadtest

https://www.npmjs.com/package/loadtest
Admin
loadtest is an HTTP and WebSocket load testing tool that allows you to simulate real-world server...
Tokens:25,650
Snippets:349
Trust Score:9.6
Update:5 months ago
Show doc for...
Tokens:
Raw
### Start the test server

Source: https://www.npmjs.com/package/loadtest?activeTab=readme

Start the test server with a specified number of cores.

```bash
$ testserver-loadtest --cores 2
Listening on http://localhost:7357/
Listening on http://localhost:7357/

```

--------------------------------

### Start test server

Source: https://www.npmjs.com/package/loadtest?activeTab=code

Starts the test server with a specified number of cores. The server will listen on http://localhost:7357/.

```bash
$ testserver-loadtest --cores 2
Listening on http://localhost:7357/
Listening on http://localhost:7357/
```

--------------------------------

### Install loadtest globally

Source: https://www.npmjs.com/package/loadtest?activeTab=readme

Install the loadtest package globally using npm.

```bash
$ sudo npm install -g loadtest

```

--------------------------------

### startServer() Function

Source: https://www.npmjs.com/package/loadtest?activeTab=readme

The `startServer` function is used to start a test server that can be used for load testing.

```APIDOC
## startServer()

### Description
Starts a test server for load testing purposes.

### Method
`startServer(options)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* `options` (object): Configuration options for the server.
  * `port` (number): optional port to use for the server, default 7357.
  * `delay` (number): milliseconds to wait before answering each request.
  * `error` (number): HTTP status code to return, default 200 (no error).
  * `percent` (number): return error only for the given % of requests.
  * `logger` (function): function to call after every request. Signature: `(request, response)`.

### Returns
A test server object with a `close()` method.
```

--------------------------------

### startServer() Function

Source: https://www.npmjs.com/package/loadtest?activeTab=code

The `startServer()` function is used to start a test server. It accepts options to configure the server's behavior, such as port, delay, and error responses.

```APIDOC
## `startServer()`

### Description
Starts a test server that can be used for load testing. The server can be configured with various options and closed when no longer needed.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

#### Function Parameters
* `options` (object): An object containing server configuration options.
  * `port` (number): Optional port to use for the server, default 7357.
  * `delay` (number): Milliseconds to wait before answering each request.
  * `error` (number): HTTP status code to return, default 200 (no error).
  * `percent` (number): Return error only for the given % of requests.
  * `logger` (function): Function to call after every request. Signature: `(request, response)`.

### Request Example
```javascript
import { startServer } from 'loadtest';

async function runServer() {
  const server = await startServer({ port: 8000, delay: 100 });
  console.log('Test server started on port 8000');
  // ... perform actions that use the server ...
  await server.close();
  console.log('Test server closed');
}

runServer();
```

### Response
Returns a test server object that has a `close()` method.
```

--------------------------------

### Get Online Help

Source: https://www.npmjs.com/package/loadtest?activeTab=readme

Run the loadtest command without any parameters to display online help and available options.

```bash
$ loadtest
```

--------------------------------

### Get Online Help

Source: https://www.npmjs.com/package/loadtest?activeTab=code

Displays the help message for the loadtest command when run without any parameters.

```bash
$ loadtest

```

--------------------------------

### Load Request Body from File with Loadtest (Bash Example)

Source: https://www.npmjs.com/package/loadtest?activeTab=code

Example of using -p flag to load request body from a file. Remember to set the content type with -T.

```bash
# Example usage with a JS file for dynamic body generation
# loadtest -p sample/post-file.js -T application/json ...
```

--------------------------------

### Install loadtest Globally

Source: https://www.npmjs.com/package/loadtest?activeTab=code

Installs the loadtest package globally for command-line use. Use sudo on Ubuntu or Mac OS X.

```bash
npm install -g loadtest

```

```bash
sudo npm install -g loadtest

```

--------------------------------

### startServer() Function

Source: https://www.npmjs.com/package/loadtest?activeTab=dependents

The `startServer()` function is used to start a test server. It accepts an options object to configure the server's port, response delay, error codes, and logging. The function returns a server instance that can be closed when testing is complete.

```APIDOC
## `startServer()`

### Description
Starts a test server for load testing purposes.

### Usage
```javascript
import { startServer } from 'loadtest';
const server = await startServer({ port: 8000 });
// Perform testing
await server.close();
```

### Parameters
* `options` (object) - Optional - Configuration options for the test server.
  * `port` (number) - Optional - The port to use for the server (defaults to 7357).
  * `delay` (number) - Optional - Milliseconds to wait before answering each request.
  * `error` (number) - Optional - The HTTP status code to return for errors (defaults to 200).
  * `percent` (number) - Optional - The percentage of requests for which to return an error.
  * `logger` (function) - Optional - A function called after each request is processed. Receives `(request, response)`.

### Returns
A test server object with a `close()` method.
```

--------------------------------

### Start Test Server with loadtest

Source: https://www.npmjs.com/package/loadtest?activeTab=readme

Use the exported startServer function to initiate a test server. The server can be closed when testing is complete. Options like port, delay, and error simulation are available.

```javascript
import {startServer} from 'loadtest'
const server = await startServer({port: 8000})
// do your thing
await server.close()
```

--------------------------------

### Run basic load test

Source: https://www.npmjs.com/package/loadtest?activeTab=code

Performs a load test against a given URL for a specified duration and concurrency. This example tests for 20 seconds with 10 concurrent users.

```bash
$ loadtest http://localhost:7357/ -t 20 -c 10
...
Requests: 9589, requests per second: 1915, mean latency: 10 ms
Requests: 16375, requests per second: 1359, mean latency: 10 ms
Requests: 16375, requests per second: 0, mean latency: 0 ms
...
Completed requests:  16376
Requests per second: 368
Total time:          44.503181166000005 s

Percentage of requests served within a certain time
  50%      4 ms
  90%      5 ms
  95%      6 ms
  99%      14 ms
 100%      35997 ms (longest request)
```

--------------------------------

### Install loadtest globally

Source: https://www.npmjs.com/package/loadtest?activeTab=code

Installs the loadtest package globally on your system. This command is typically run once before using the loadtest CLI.

```bash
$ sudo npm install -g loadtest
```

--------------------------------

### Loadtest Configuration File Example

Source: https://www.npmjs.com/package/loadtest?activeTab=readme

A .loadtestrc file can be used to configure test parameters. Options specified here are used if not provided on the command line. Supports various settings like delay, concurrency, and headers.

```json
{
	"delay": "Delay the response for the given milliseconds",
	"error": "Return an HTTP error code",
	"percent": "Return an error (default 500) only for some % of requests",
	"maxRequests": "Number of requests to perform",
	"concurrency": "Number of requests to make",
	"maxSeconds": "Max time in seconds to wait for responses",
	"timeout": "Timeout for each request in milliseconds",
	"method": "method to url",
	"contentType": "MIME type for the body",
	"body": "Data to send",
	"file": "Send the contents of the file",
	"cookies": {
		"key": "value"
	},
	"headers": {
		"key": "value"
	},
	"secureProtocol": "TLS/SSL secure protocol method to use",
	"insecure": "Allow self-signed certificates over https",
	"cert": "The client certificate to use",
	"key": "The client key to use",
	"requestGenerator": "JS module with a custom request generator function",
	"recover": "Do not exit on socket receive errors (default)",
	"agentKeepAlive": "Use a keep-alive http agent",
	"proxy": "Use a proxy for requests",
	"requestsPerSecond": "Specify the requests per second for each client",
	"indexParam": "pattern to replace with a generated index in the URL",
	"indexParamLiteral": "string to replace with a generated index in the URL",
	"indexParamCallback": "function() {that generates ids to insert into the URL}"
}
```

--------------------------------

### Install loadtest Globally

Source: https://www.npmjs.com/package/loadtest?activeTab=readme

Install the loadtest package globally using npm. This command is typically run on Ubuntu or Mac OS X systems with sudo privileges.

```bash
sudo npm install -g loadtest
```

--------------------------------

### Set HTTP Method for Loadtest

Source: https://www.npmjs.com/package/loadtest?activeTab=dependents

Use the -m or --method option to specify the HTTP method (e.g., GET, POST, PUT, DELETE, PATCH). Defaults to GET.

```bash
$ loadtest -m POST
```

--------------------------------

### Install loadtest as a Dev Dependency

Source: https://www.npmjs.com/package/loadtest?activeTab=code

Installs the loadtest package as a development dependency for API integration within your project.

```bash
npm install --save-dev loadtest

```

--------------------------------

### Specify TLS/SSL Protocol for Loadtest

Source: https://www.npmjs.com/package/loadtest?activeTab=readme

Use the -s or --secureProtocol option to specify the TLS/SSL method for the loadtest. Example: TLSv1_method.

```bash
$ loadtest -n 1000 -s TLSv1_method https://www.example.com

```

--------------------------------

### Run load test with fixed RPS

Source: https://www.npmjs.com/package/loadtest?activeTab=code

Executes a load test with a fixed requests per second (rps) rate. This example targets 1000 rps for 20 seconds with 10 concurrent users.

```bash
$ loadtest http://localhost:7357/ -t 20 -c 10 --rps 1000
...
Requests: 4551, requests per second: 910, mean latency: 0 ms
Requests: 9546, requests per second: 1000, mean latency: 0 ms
Requests: 14549, requests per second: 1000, mean latency: 20 ms
...
Percentage of requests served within a certain time
  50%      1 ms
  90%      2 ms
  95%      8 ms
  99%      133 ms
 100%      1246 ms (longest request)
```

--------------------------------

### Set Request Method

Source: https://www.npmjs.com/package/loadtest

Use the -m or --method option to specify the HTTP method for the request. Accepts GET, POST, PUT, DELETE, PATCH, and their lowercase equivalents. Default is GET.

```bash
-m POST
```

--------------------------------

### loadTest() Function

Source: https://www.npmjs.com/package/loadtest?activeTab=dependents

The `loadTest()` function is used to initiate a load testing process against a specified URL. It accepts a wide range of parameters to customize the test, including concurrency, request limits, timeouts, headers, and more. For a full explanation of all parameters and examples, refer to the `doc/api.md` file.

```APIDOC
## `loadTest()`

### Description
Initiates a load test against a given URL with configurable parameters.

### Parameters

#### URL
* `url` (string) - Required - The URL to invoke for the load test.

#### Test Configuration
* `concurrency` (number) - Optional - The number of parallel clients to start.
* `maxRequests` (number) - Optional - The maximum number of requests to perform before ending the test.
* `maxSeconds` (number) - Optional - The maximum duration in seconds for the test.
* `requestsPerSecond` (number) - Optional - The number of requests to send per second per client.

#### Request Details
* `method` (string) - Optional - The HTTP method to use (defaults to 'GET').
* `body` (any) - Optional - The content to send in the request body.
* `contentType` (string) - Optional - The MIME type for the request body (defaults to 'text/plain').
* `headers` (object) - Optional - An object containing request headers. Keys are header names, values are strings. Multiple values can be separated by semicolons.
* `cookies` (array) - Optional - An array of cookies to send, in the format 'name=value'.

#### Advanced Options
* `timeout` (number) - Optional - Timeout for each request in milliseconds (0 to disable, defaults to enabled).
* `requestGenerator` (function) - Optional - A custom function to generate requests.
* `agentKeepAlive` (boolean) - Optional - If true, uses 'Connection: Keep-alive'.
* `quiet` (boolean) - Optional - If true, suppresses console messages.
* `indexParam` (regexp) - Optional - Regular expression to replace in URL and body with a unique index.
* `indexParamLiteral` (string) - Optional - Literal string to replace in URL and body with a unique index.
* `indexParamCallback` (function) - Optional - Function to generate unique indexes.
* `insecure` (boolean) - Optional - Allows invalid and self-signed certificates over HTTPS.
* `secureProtocol` (string) - Optional - TLS/SSL method to use.
* `statusCallback` (function) - Optional - Callback function executed after each request completes. Receives `(error, result)`.
* `contentInspector` (function) - Optional - Callback function executed before aggregating statistics. Receives `(result)`.
```

--------------------------------

### Install loadtest as a Dev Dependency

Source: https://www.npmjs.com/package/loadtest?activeTab=readme

Install the loadtest package as a development dependency within your npm project. This allows for API integration into your own tests.

```bash
npm install --save-dev loadtest
```

--------------------------------

### Configure Test Server Cores

Source: https://www.npmjs.com/package/loadtest?activeTab=readme

Use the --cores option to specify the number of cores for the test server. Defaults to half the available cores in recent versions.

```bash
--cores number

```

--------------------------------

### Run Load Test (Lower Rate)

Source: https://www.npmjs.com/package/loadtest?activeTab=dependents

Test the server at a lower rate of 500 rps for 20 seconds. This demonstrates achieving a sustained rate with minimal errors.

```bash
$ loadtest http://localhost:7357/ -t 20 -c 10 --rps 500
... 
Requests: 0, requests per second: 0, mean latency: 0 ms
Requests: 2258, requests per second: 452, mean latency: 0 ms
Requests: 4757, requests per second: 500, mean latency: 0 ms
Requests: 7258, requests per second: 500, mean latency: 0 ms
Requests: 9757, requests per second: 500, mean latency: 0 ms
...
Requests per second: 500
Completed requests:  9758
Total errors:        0
Total time:          20.002735398000002 s
Requests per second: 488
Total time:          20.002735398000002 s

Percentage of requests served within a certain time
  50%      1 ms
  90%      1 ms
  95%      1 ms
  99%      14 ms
 100%      148 ms (longest request)


```

--------------------------------

### Run Loadtest Test Server

Source: https://www.npmjs.com/package/loadtest?activeTab=readme

Execute the bundled test server for load testing. It accepts optional port and delay parameters.

```bash
$ testserver-loadtest [options] [port]

```

--------------------------------

### Run Test Server and Load Test Client

Source: https://www.npmjs.com/package/loadtest?activeTab=readme

Execute a load test against a local test server. This is useful for measuring the practical limits of the loadtest tool on your machine.

```bash
$ node bin/testserver.js
$ node bin/loadtest.js -n 1000000 -c 100 http://localhost:7357/
```

--------------------------------

### Run Load Test (Fixed Rate)

Source: https://www.npmjs.com/package/loadtest?activeTab=dependents

Run a load test with a fixed rate of 1000 requests per second for 20 seconds. This helps in observing server behavior under a specific throughput.

```bash
$ loadtest http://localhost:7357/ -t 20 -c 10 --rps 1000
... 
Requests: 4551, requests per second: 910, mean latency: 0 ms
Requests: 9546, requests per second: 1000, mean latency: 0 ms
Requests: 14549, requests per second: 1000, mean latency: 20 ms
...
Percentage of requests served within a certain time
  50%      1 ms
  90%      2 ms
  95%      8 ms
  99%      133 ms
 100%      1246 ms (longest request)


```

--------------------------------

### Configuration File (.loadtestrc)

Source: https://www.npmjs.com/package/loadtest?activeTab=dependents

Loadtest supports configuration options via a `.loadtestrc` file in the working directory or specified in the `loadtest` entry of `package.json`. Options in the file are used if not provided directly in the command line or API.

```APIDOC
## Configuration File (`.loadtestrc`)

### Description
Allows external configuration of load test parameters.

### Supported Options
* `delay` (number): Delay the response in milliseconds.
* `error` (number): HTTP status code to return for errors.
* `percent` (number): Percentage of requests to return an error for.
* `maxRequests` (number): Maximum number of requests to perform.
* `concurrency` (number): Number of parallel requests.
* `maxSeconds` (number): Maximum test duration in seconds.
* `timeout` (number): Timeout for each request in milliseconds.
* `method` (string): HTTP method for requests.
* `contentType` (string): MIME type for the request body.
* `body` (any): Data to send in the request body.
* `file` (string): Path to a file whose contents will be sent as the body.
* `cookies` (object): Key-value pairs for cookies.
* `headers` (object): Key-value pairs for request headers.
* `secureProtocol` (string): TLS/SSL secure protocol method.
* `insecure` (boolean): Allow self-signed certificates over HTTPS.
* `cert` (string): Path to the client certificate file.
* `key` (string): Path to the client key file.
* `requestGenerator` (string): Path to a JS module with a custom request generator function.
* `recover` (boolean): Do not exit on socket receive errors (default: true).
* `agentKeepAlive` (boolean): Use a keep-alive HTTP agent.
* `proxy` (string): URL of the proxy to use for requests.
* `requestsPerSecond` (number): Requests per second for each client.
* `indexParam` (string): Pattern to replace with a generated index in the URL.
* `indexParamLiteral` (string): Literal string to replace with a generated index in the URL.
* `indexParamCallback` (string): Path to a JS module with a function to generate indexes.
```

--------------------------------

### Run a basic load test

Source: https://www.npmjs.com/package/loadtest?activeTab=readme

Perform a load test for 20 seconds with a concurrency of 10.

```bash
$ loadtest http://localhost:7357/ -t 20 -c 10
... 
Requests: 9589, requests per second: 1915, mean latency: 10 ms
Requests: 16375, requests per second: 1359, mean latency: 10 ms
Requests: 16375, requests per second: 0, mean latency: 0 ms
...
Completed requests:  16376
Requests per second: 368
Total time:          44.503181166000005 s

Percentage of requests served within a certain time
  50%      4 ms
  90%      5 ms
  95%      6 ms
  99%      14 ms
 100%      35997 ms (longest request)


```

--------------------------------

### Run load test with errors

Source: https://www.npmjs.com/package/loadtest?activeTab=readme

Run a load test for 50 seconds with a fixed rate of 1000 RPS to observe errors.

```bash
$ loadtest http://localhost:7357/ -t 50 -c 10 --rps 1000
... 
Requests: 29212, requests per second: 496, mean latency: 14500 ms
Errors: 426, accumulated errors: 428, 1.5% of total requests


```

--------------------------------

### Configuration File Options

Source: https://www.npmjs.com/package/loadtest?activeTab=readme

Loadtest supports configuration options via a `.loadtestrc` file in the working directory or specified in `package.json`.

```APIDOC
## Configuration File

### Description
Options can be specified in a `.loadtestrc` file or in the `loadtest` entry of `package.json`.

### Supported Options
* `delay` (number): Delay the response for the given milliseconds.
* `error` (number): Return an HTTP error code.
* `percent` (number): Return an error (default 500) only for some % of requests.
* `maxRequests` (number): Number of requests to perform.
* `concurrency` (number): Number of requests to make.
* `maxSeconds` (number): Max time in seconds to wait for responses.
* `timeout` (number): Timeout for each request in milliseconds.
* `method` (string): HTTP method to url.
* `contentType` (string): MIME type for the body.
* `body` (any): Data to send.
* `file` (string): Send the contents of the file.
* `cookies` (object): Key-value pairs for cookies.
* `headers` (object): Key-value pairs for headers.
* `secureProtocol` (string): TLS/SSL secure protocol method to use.
* `insecure` (boolean): Allow self-signed certificates over https.
* `cert` (string): The client certificate to use.
* `key` (string): The client key to use.
* `requestGenerator` (string): JS module with a custom request generator function.
* `recover` (boolean): Do not exit on socket receive errors (default).
* `agentKeepAlive` (boolean): Use a keep-alive http agent.
* `proxy` (string): Use a proxy for requests.
* `requestsPerSecond` (number): Specify the requests per second for each client.
* `indexParam` (string): pattern to replace with a generated index in the URL.
* `indexParamLiteral` (string): string to replace with a generated index in the URL.
* `indexParamCallback` (function): function() {that generates ids to insert into the URL}.
```

--------------------------------

### Configuration File (.loadtestrc)

Source: https://www.npmjs.com/package/loadtest?activeTab=code

Loadtest can be configured using a `.loadtestrc` file in the working directory or specified in `package.json`. Options in this file are used if not provided via command line or function arguments.

```APIDOC
## Configuration File (`.loadtestrc`)

### Description
Allows external configuration of load test parameters through a JSON file.

### Supported Options
* `delay` (number): Delay the response for the given milliseconds.
* `error` (number): Return an HTTP error code.
* `percent` (number): Return an error (default 500) only for some % of requests.
* `maxRequests` (number): Number of requests to perform.
* `concurrency` (number): Number of requests to make.
* `maxSeconds` (number): Max time in seconds to wait for responses.
* `timeout` (number): Timeout for each request in milliseconds.
* `method` (string): HTTP method to use for requests.
* `contentType` (string): MIME type for the request body.
* `body` (string): Data to send in the request body.
* `file` (string): Path to a file whose contents will be sent as the request body.
* `cookies` (object): Key-value pairs for cookies.
* `headers` (object): Key-value pairs for request headers.
* `secureProtocol` (string): TLS/SSL secure protocol method to use.
* `insecure` (boolean): Allow self-signed certificates over https.
* `cert` (string): Path to the client certificate file.
* `key` (string): Path to the client key file.
* `requestGenerator` (string): Path to a JS module with a custom request generator function.
* `recover` (boolean): Do not exit on socket receive errors (default).
* `agentKeepAlive` (boolean): Use a keep-alive http agent.
* `proxy` (string): URL of the proxy to use for requests.
* `requestsPerSecond` (number): Specify the requests per second for each client.
* `indexParam` (string): Pattern to replace with a generated index in the URL.
* `indexParamLiteral` (string): Literal string to replace with a generated index in the URL.
* `indexParamCallback` (string): Path to a JS module exporting a function that generates IDs to insert into the URL.

### Example `.loadtestrc` file
```json
{
  "delay": 50,
  "maxRequests": 5000,
  "concurrency": 20,
  "headers": {
    "X-Custom-Header": "MyValue"
  }
}
```
```

--------------------------------

### Basic loadtest Command

Source: https://www.npmjs.com/package/loadtest?activeTab=code

Runs a load test on a specified URL. Use -n for the total number of requests and -c for concurrency. The URL can be http, https, or ws.

```bash
$ loadtest [-n requests] [-c concurrency] [-k] URL

```

--------------------------------

### Configure Test Server Delay

Source: https://www.npmjs.com/package/loadtest?activeTab=readme

Use the --delay option to set a delay in milliseconds before the test server answers each request, simulating a busy server.

```bash
--delay ms

```

--------------------------------

### Test Server - Cores

Source: https://www.npmjs.com/package/loadtest?activeTab=versions

Configure the number of cores for the test server to use. Defaults to half the available cores.

```APIDOC
## --cores number

### Description
Number of cores to use. If not 1, will start in multi-process mode. Since version v6.3.0 the test server uses half the available cores by default; use `--cores 1` to use in single-process mode.

### Parameters
#### Query Parameters
- **--cores** (number) - Optional - The number of CPU cores to use for the test server.
```

--------------------------------

### Run load test with lower RPS

Source: https://www.npmjs.com/package/loadtest?activeTab=code

Tests the server at a reduced rate (500 rps) for 20 seconds with 10 concurrent users. This helps identify a stable operating point.

```bash
$ loadtest http://localhost:7357/ -t 20 -c 10 --rps 500
...
Requests: 0, requests per second: 0, mean latency: 0 ms
Requests: 2258, requests per second: 452, mean latency: 0 ms
Requests: 4757, requests per second: 500, mean latency: 0 ms
Requests: 7258, requests per second: 500, mean latency: 0 ms
Requests: 9757, requests per second: 500, mean latency: 0 ms
...
Requests per second: 500
Completed requests:  9758
Total errors:        0
Total time:          20.002735398000002 s
Requests per second: 488
Total time:          20.002735398000002 s

Percentage of requests served within a certain time
  50%      1 ms
  90%      1 ms
  95%      1 ms
  99%      14 ms
 100%      148 ms (longest request)
```

--------------------------------

### Use Low-Level TCP Sockets (Experimental)

Source: https://www.npmjs.com/package/loadtest

The --tcp option enables the use of low-level TCP sockets for potentially faster performance. This is an experimental feature and may not support all options.

```bash
--tcp

```

--------------------------------

### Basic loadtest Command

Source: https://www.npmjs.com/package/loadtest?activeTab=readme

Run loadtest as a script to test a URL. Specify the maximum number of requests with -n and concurrency with -c. The URL can be HTTP, HTTPS, or WS.

```bash
$ loadtest [-n requests] [-c concurrency] [-k] URL
```

--------------------------------

### Send POST Body from File

Source: https://www.npmjs.com/package/loadtest?activeTab=dependents

Use the -p option to send data from a file as the POST body. Ensure the -T option is set to the correct content type.

```bash
# Example usage for -p (assuming post-file.js exists)
# loadtest -p post-file.js -T application/json ...
```

--------------------------------

### Display Loadtest Version

Source: https://www.npmjs.com/package/loadtest?activeTab=dependencies

Use the `-V` or `--version` flag to display the current version of the loadtest tool and exit.

--------------------------------

### Multi-process Mode

Source: https://www.npmjs.com/package/loadtest?activeTab=versions

Run loadtest in multi-process mode using multiple CPU cores.

```APIDOC
## --cores number

### Description
Start `loadtest` in multi-process mode on a number of cores simultaneously. Forks the requested number of processes using the Node.js cluster module. The total number of requests and the rps rate are shared among all processes. The result shown is the aggregation of results from all cores. This option is not available in the API, since it runs just within the calling process. The default value has changed in version 7+, from 1 to half the available CPUs on the machine. Set to 1 to get the previous single-process mode.

### Parameters
#### Query Parameters
- **--cores** (number) - Optional - The number of CPU cores to use for multi-processing.
```

--------------------------------

### Test Server - Delay

Source: https://www.npmjs.com/package/loadtest?activeTab=versions

Configure the test server to wait before responding to requests.

```APIDOC
## --delay ms

### Description
Wait the specified number of milliseconds before answering each request.

### Parameters
#### Query Parameters
- **--delay** (number) - Optional - Delay in milliseconds before responding.
```

--------------------------------

### Run load test with lower RPS

Source: https://www.npmjs.com/package/loadtest?activeTab=readme

Perform a load test for 20 seconds with a fixed rate of 500 requests per second.

```bash
$ loadtest http://localhost:7357/ -t 20 -c 10 --rps 500
... 
Requests: 0, requests per second: 0, mean latency: 0 ms
Requests: 2258, requests per second: 452, mean latency: 0 ms
Requests: 4757, requests per second: 500, mean latency: 0 ms
Requests: 7258, requests per second: 500, mean latency: 0 ms
Requests: 9757, requests per second: 500, mean latency: 0 ms
... 
Requests per second: 500
Completed requests:  9758
Total errors:        0
Total time:          20.002735398000002 s
Requests per second: 488
Total time:          20.002735398000002 s

Percentage of requests served within a certain time
  50%      1 ms
  90%      1 ms
  95%      1 ms
  99%      14 ms
 100%      148 ms (longest request)


```

--------------------------------

### Specify Client Key for HTTPS

Source: https://www.npmjs.com/package/loadtest

Set the client key for HTTPS connections using the --key option. Must be used in conjunction with --cert.

```bash
--key path/to/key.pem

```

--------------------------------

### Run load test with keep-alive and high RPS

Source: https://www.npmjs.com/package/loadtest?activeTab=code

Tests the server with keep-alive enabled and a high target rate of 2000 rps for 20 seconds with 10 concurrent users. Demonstrates high throughput capabilities.

```bash
$ loadtest http://localhost:7357/ -t 20 -c 10 --keepalive --rps 2000
...
Requests per second: 1950

Percentage of requests served within a certain time
  50%      1 ms
  90%      2 ms
  95%      2 ms
  99%      7 ms
 100%      20 ms (longest request)
```

--------------------------------

### TCP Sockets (Experimental)

Source: https://www.npmjs.com/package/loadtest?activeTab=versions

Use low-level TCP sockets for potentially faster connections. Note: not all options are supported.

```APIDOC
## --tcp (experimental)

### Description
Option to use low level TCP sockets, faster than the standard HTTP library. Not all options are supported. Experimental option. May not work with your test case. See TCP Sockets Performance for details.

### Parameters
#### Query Parameters
- **--tcp** (boolean) - Optional - Enable low-level TCP sockets.
```

--------------------------------

### Run Load Test Against Test Server

Source: https://www.npmjs.com/package/loadtest?activeTab=code

Executes a load test against a local test server to measure the practical limits of the loadtest tool. Requires running the test server in a separate console.

```bash
$ node bin/testserver.js

```

```bash
$ node bin/loadtest.js -n 1000000 -c 100 http://localhost:7357/

```

--------------------------------

### Specify Client Certificate for HTTPS

Source: https://www.npmjs.com/package/loadtest

Set the client certificate for HTTPS connections using the --cert option. Must be used in conjunction with --key.

```bash
--cert path/to/cert.pem

```

--------------------------------

### Client Key

Source: https://www.npmjs.com/package/loadtest?activeTab=versions

Specify a client key file for HTTPS connections.

```APIDOC
## --key path/to/key.pem

### Description
Sets the key for the http client to use. Must be used with `--cert`.

### Parameters
#### Query Parameters
- **--key** (string) - Required - Path to the client key file.
```

--------------------------------

### Run load test with keep-alive

Source: https://www.npmjs.com/package/loadtest?activeTab=readme

Perform a load test for 20 seconds with keep-alive enabled.

```bash
$ loadtest http://localhost:7357/ -t 20 -c 10 -k
... 
Requests per second: 4099

Percentage of requests served within a certain time
50%      2 ms
90%      3 ms
95%      3 ms
99%      10 ms
100%      25 ms (longest request)


```

--------------------------------

### Invoke Load Test

Source: https://www.npmjs.com/package/loadtest?activeTab=code

This snippet shows how to use the exported `loadTest` function to initiate a load test with specified options. It's important to note that if neither `maxRequests` nor `maxSeconds` is provided, the test will run indefinitely.

```APIDOC
## Invoke Load Test

To run a load test, invoke the exported function `loadTest()` with the desired options:

```javascript
import {loadTest} from 'loadtest'

const options = {
    url: 'http://localhost:8000',
    maxRequests: 1000,
}
const result = await loadTest(options)
result.show()
console.log('Tests run successfully')
```

Beware: if there are no `maxRequests` and no `maxSeconds`, the test will run forever.
```

--------------------------------

### Run load test with fixed RPS

Source: https://www.npmjs.com/package/loadtest?activeTab=readme

Perform a load test with a fixed rate of 1000 requests per second.

```bash
$ loadtest http://localhost:7357/ -t 20 -c 10 --rps 1000
... 
Requests: 4551, requests per second: 910, mean latency: 0 ms
Requests: 9546, requests per second: 1000, mean latency: 0 ms
Requests: 14549, requests per second: 1000, mean latency: 20 ms
... 
Percentage of requests served within a certain time
  50%      1 ms
  90%      2 ms
  95%      8 ms
  99%      133 ms
 100%      1246 ms (longest request)


```

--------------------------------

### Configure Test Server Error Response

Source: https://www.npmjs.com/package/loadtest

Set the test server to return a specific error code for every request using the --error option.

```bash
--error 5xx

```

--------------------------------

### Send String as POST Body

Source: https://www.npmjs.com/package/loadtest?activeTab=dependents

Use the -P or --postBody option to send a literal string as the POST request body.

```bash
-P '{"key": "a9acf03f"}'
```

--------------------------------

### Enable Keep-Alive Connections

Source: https://www.npmjs.com/package/loadtest?activeTab=dependents

Use the -k or --keepalive option to enable HTTP keep-alive connections by setting the 'Connection: keep-alive' header. This uses agentkeepalive for better performance.

```bash
# Example: loadtest -k ...
```

--------------------------------

### Configure Test Server Error Percentage

Source: https://www.npmjs.com/package/loadtest

Specify the percentage of requests for which the test server should return an error using the --percent option. The default error is 500.

```bash
--percent yy

```

--------------------------------

### Generate Dynamic POST Body from File

Source: https://www.npmjs.com/package/loadtest?activeTab=readme

Use the `-p` or `--postFile` option to send data from a file. If the file has a `.js` extension, it's imported as a Node.js module exporting a default function that generates the request body dynamically.

```javascript
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
  }
}
```

--------------------------------

### Version Option

Source: https://www.npmjs.com/package/loadtest?activeTab=versions

Display the version number of the loadtest tool and exit.

```APIDOC
## -V, --version

### Description
Show version number and exit.

### Method
GET

### Endpoint
N/A (CLI Option)

### Parameters
#### Query Parameters
- **-V** (boolean) - Optional - Show version number and exit.
- **--version** (boolean) - Optional - Show version number and exit.
```

--------------------------------

### Invoke Load Test

Source: https://www.npmjs.com/package/loadtest?activeTab=readme

This function allows you to programmatically initiate a load test. You must provide an options object, including the target URL and either `maxRequests` or `maxSeconds` to define the test duration. Failure to specify either will result in an indefinite test.

```APIDOC
## Invoke Load Test

### Description
To run a load test, invoke the exported function `loadTest()` with the desired options.

### Method
`loadTest(options)`

### Parameters
#### Options Object
- **url** (string) - Required - The URL to test.
- **maxRequests** (number) - Optional - The maximum number of requests to send.
- **maxSeconds** (number) - Optional - The maximum number of seconds to run the test.

### Request Example
```javascript
import {loadTest} from 'loadtest'

const options = {
    url: 'http://localhost:8000',
    maxRequests: 1000,
}
const result = await loadTest(options)
result.show()
console.log('Tests run successfully')
```

### Notes
Beware: if there are no `maxRequests` and no `maxSeconds`, the test will run forever.
```
Tokens:
Raw