<commit_before>[![Build Status](https://secure.travis-ci.org/alexfernandez/loadtest.png)](http://travis-ci.org/alexfernandez/loadtest)

# loadtest

Runs a load test on the selected HTTP URL. The API allows for easy integration in your own tests.

Why use `loadtest` instead of any other of the available tools, notably Apache `ab`?
`loadtest` allows you to configure and tweak requests to simulate real world loads.

The set of basic options are designed to be compatible with Apache `ab`.
But while `ab` can only set a concurrency level and lets the server adjust to it,
`loadtest` allows you to set a rate or requests per second with the `--rps` option.
Example:

    loadtest -c 10 --rps 200 http://mysite.com/

This command sends exactly 200 requests per second with concurrency 10,
so you can see how your server copes with sustained rps.
Even if `ab` reported a rate of 200 rps,
you will be surprised to see how a constant rate of requests per second affects performance:
no longer are the requests adjusted to the server, but the server must adjust to the requests!
Rps rates are usually lowered dramatically about 20~25% (in our example from 200 to 150 rps),
but the resulting figure is much more robust.

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, so that you can abort deployment e.g. if 99% of the requests don't finish in 10 ms or less.

## Changes in Version 1.0

* Option parsing has been improved; no longer is a `true` needed after certain options.
* Requests per second specified with `--rps` are now total rps, instead of multiplied by concurrency.
* Option `--agent` has been deprecated in favor of `--keepalive`.
* Support for Node.js < 0.10 removed.

## Installation

Install globally as root:

    # npm install -g loadtest

On Ubuntu or Mac OS X systems install using sudo:

    $ sudo npm install -g loadtest

For access to the API just add package `loadtest` to your `package.json` devDependencies:

    {
        ...
        "devDependencies": {
            "loadtest": "*"
        },
        ...
    }

## Basic Usage

Run as a script to load test a URL:

    $ loadtest [-n requests] [-c concurrency] URL

The URL can be "http://" or "https://". Set the max number of requests with `-n`, and the desired level of concurrency with the `-c` parameter.

Single-dash parameters (e.g. `-n`) are designed to be compatible with Apache `ab`.
  http://httpd.apache.org/docs/2.2/programs/ab.html

To get online help, run loadtest without parameters:

    $ loadtest

### Regular Usage

The following parameters are compatible with Apache ab.

#### `-n requests`

Number of requests to send out.

Note: the total number of requests sent can be bigger than the parameter, if there is a concurrency parameter
and number of requests is not a multiple of concurrency.

#### `-c concurrency`

loadtest will create a simultaneous number of clients; this parameter controls how many.

#### `-t timelimit`

Max number of seconds to wait until requests no longer go out.

Note: this is different than Apache `ab`, which stops _receiving_ requests after the given seconds.

### `-C cookie-name=value`

Send a cookie with the request. The cookie `name=value` is then sent to the server.
This parameter can be repeated as many times as needed.

### `-H header:value`

Send a custom header with the request. The line `header:value` is then sent to the server.
This parameter can be repeated as many times as needed.

Note: loadtest will add a few headers on its own: the "host" header parsed from the URL,
a custom user agent "loadtest/" plus version, and an accept header for "\*/\*".
Example user agent: `loadtest/1.0.0`.

### `-T content-type`

Set the MIME content type for POST data. Default: `text/plain`.

### `-P POST-body`

Send the string as the POST body. E.g.: `-P '{"key": "<KEY>"}'`<commit_msg>Clarify that duplicate headers are ignored.<commit_after>[![Build Status](https://secure.travis-ci.org/alexfernandez/loadtest.png)](http://travis-ci.org/alexfernandez/loadtest)

# loadtest

Runs a load test on the selected HTTP URL. The API allows for easy integration in your own tests.

Why use `loadtest` instead of any other of the available tools, notably Apache `ab`?
`loadtest` allows you to configure and tweak requests to simulate real world loads.

The set of basic options are designed to be compatible with Apache `ab`.
But while `ab` can only set a concurrency level and lets the server adjust to it,
`loadtest` allows you to set a rate or requests per second with the `--rps` option.
Example:

    loadtest -c 10 --rps 200 http://mysite.com/

This command sends exactly 200 requests per second with concurrency 10,
so you can see how your server copes with sustained rps.
Even if `ab` reported a rate of 200 rps,
you will be surprised to see how a constant rate of requests per second affects performance:
no longer are the requests adjusted to the server, but the server must adjust to the requests!
Rps rates are usually lowered dramatically about 20~25% (in our example from 200 to 150 rps),
but the resulting figure is much more robust.

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,
so that you can abort deployment e.g. if 99% of the requests don't finish in 10 ms or less.

## Changes in Version 1.0

* Option parsing has been improved; no longer is a `true` needed after certain options.
* Requests per second specified with `--rps` are now total rps, instead of multiplied by concurrency.
* Option `--agent` has been deprecated in favor of `--keepalive`.
* Support for Node.js < 0.10 removed.

## Installation

Install globally as root:

    # npm install -g loadtest

On Ubuntu or Mac OS X systems install using sudo:

    $ sudo npm install -g loadtest

For access to the API just add package `loadtest` to your `package.json` devDependencies:

    {
        ...
        "devDependencies": {
            "loadtest": "*"
        },
        ...
    }

## Basic Usage

Run as a script to load test a URL:

    $ loadtest [-n requests] [-c concurrency] URL

The URL can be "http://" or "https://". Set the max number of requests with `-n`, and the desired level of concurrency with the `-c` parameter.

Single-dash parameters (e.g. `-n`) are designed to be compatible with Apache `ab`.
  http://httpd.apache.org/docs/2.2/programs/ab.html

To get online help, run loadtest without parameters:

    $ loadtest

### Regular Usage

The following parameters are compatible with Apache ab.

#### `-n requests`

Number of requests to send out.

Note: the total number of requests sent can be bigger than the parameter, if there is a concurrency parameter
and number of requests is not a multiple of concurrency.

#### `-c concurrency`

loadtest will create a simultaneous number of clients; this parameter controls how many.

#### `-t timelimit`

Max number of seconds to wait until requests no longer go out.

Note: this is different than Apache `ab`, which stops _receiving_ requests after the given seconds.

### `-C cookie-name=value`

Send a cookie with the request. The cookie `name=value` is then sent to the server.
This parameter can be repeated as many times as needed.

### `-H header:value`

Send a custom header with the request. The line `header:value` is then sent to the server.
This parameter can be repeated as many times as needed.
Example:

    $ loadtest -H user-agent:tester/0.4 ...

Note: if not present, loadtest will add a few headers on its own: the "host" header parsed from the URL,
a custom user agent "loadtest/" plus version (`loadtest/1.1.0`), and an accept header for "\*/\*".

Note: when the same header is sent several times, only the last value will be considered.
If you want to send multiple values with a header, separate them with semicolons:

    $ loadtest -H accept:text/plain;text-html ...

### `-T content-type`

Set the MIME content type for POST data. Default: `text/plain`.

### `-P POST-body`

Send the string as the POST body. E.g.: `-P '{"key": "<KEY>"}'`
{'fraction_non_alphanumeric': 0.08142433234421365, 'fraction_numerical': 0.009020771513353116, 'mean_word_length': 3.6296703296703297, 'pattern_counts': {'":': 6, '<': 7, '<?xml version=': 0, '>': 5, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1232142', 'n_tokens_mistral': 2413, 'n_tokens_neox': 2285, 'n_words': 1261}