<commit_before>```
             _           _
            (_)         (_)
 _ __ ___    _   _ __    _    __ _   _   _   _ __
| '_ ` _ \  | | | '_ \  | |  / _` | | | | | | '_ \
| | | | | | | | | | | | | | | (_| | | |_| | | | | |
|_| |_| |_| |_| |_| |_| |_|  \__, |  \__,_| |_| |_|
                              __/ |
                             |___/
```

**minigun** is a simple but powerful load-testing tool designed to help you
make your apps more performant, reliable, and scalable.

[http://minigun.io](http://minigun.io)

[![Build Status](https://travis-ci.org/shoreditch-ops/minigun.svg?branch=master)](https://travis-ci.org/shoreditch-ops/minigun)

[![gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/shoreditch-ops/minigun)

# Features

- HTTP(S) and WebSocket support
- Detailed performance metrics (latency, RPS, throughput)
- NEW! Graphical reports
- Test scenarios are just easy-to-read JSON - all declarative, no code ([see an example](https://github.com/shoreditch-ops/minigun-core/blob/master/test/scripts/all_features.json))
- Dynamic payloads
- Use minigun as a standalone CLI tool or as a Node.js library
- Good performance
- Plugin support (experimental) - [docs](https://github.com/shoreditch-ops/minigun/blob/master/docs/plugins.md)
- Open-source & free

# Quickstart

## Install

**minigun** is available via [npm](http://npmjs.org)

`$ npm install -g minigun`

## Run

`$ minigun quick -d 30 -r 5 http://127.0.0.1:3000/test`

This will run a test for 30 seconds with an average of 5 new requests to
`http://127.0.0.1:3000/test` every second.

## Run with a more complex scenario

`$ minigun run hello.json`

Where `hello.json` is your tests script that contains something like:

```javascript
{
  "config": {
      "target": "http://127.0.0.1:3000",
      "phases": [
        { "duration": 120, "arrivalRate": 10 }
      ],
      "defaults": {
        "headers": {
          "content-type": "application/json",
          "x-my-service-auth": "9<PASSWORD>"
        }
      }
  },
  "scenarios": [
    {
      "flow": [
        { "get": {"url": "/test"}},
        { "think": 1 },
        { "post": {"url": "/test", "json": { "name": "hassy" }}}
      ]
    }
  ]
}
```

# Create a report

Create a graphical report from the JSON stats produced by `minigun run` with:
`minigun report <minigun_report_xxxxx.json>`

An example: :tophat:

![https://cldup.com/PYeZJTCe86-1200x1200.png](https://cldup.com/PYeZJTCe86-1200x1200.png)

# Use cases

- Benchmark the performance of your API or microservice as you're building it
- Ensure new code does not introduce performance regressions
- Test your code for memory leaks
- Benchmark dependencies (libraries, frameworks, external services) to get a
  feel for their performance characteristics before you integrate
- Run load-tests before you launch to ensure your application can meet
  projected demand

# Learn More

- [HTTP Features](https://github.com/shoreditch-ops/minigun/wiki/HTTP-Features)
- [WebSocket Features](https://github.com/shoreditch-ops/minigun/wiki/WebSocket-Features)


## When NOT to use Minigun

Minigun is **not** a web server benchmarking tool. Its sweet spot is performance
testing of applications and APIs with complex transactional scenarios.

Having said that, Minigun is capable of generating 500+ RPS on modest hardware
(a 512MB Digital Ocean droplet). Still though, if you are after raw RPS to
simply hammer a single URL, you may want to use `ab` instead.

**tldr:**
Benchmarking an Nginx installation? Use `ab`. Testing a Node.js
API, a RoR webapp, or a realtime WebSocket-based app? Use Minigun.

# Design

## Declarative tests

**minigun** test cases are 100% declarative. Your test-case describes _what_
needs to happen, not _how_ it happens.

Benefits of this approach:

- Tests can be 100% reproducible, since there is no custom code.
- Test cases can be auto-generated and analysed by other tools - it's just JSON.
- DSLs can be written for any language. We have a JS DSL on the roadmap, and
  one can be written easily for Ruby, Python, Lua or another language.
- Stronger performance guarantees can be made in absence of custom code.

Further reading:
- [Imperative vs Declarative Programming](http://latentflip.com/imperative-vs-declarative/)

## Statistically-sound testing

### Modeling user arrivals
<commit_msg>Recommend wrk instead of ab for http testing.<commit_after>```
             _           _
            (_)         (_)
 _ __ ___    _   _ __    _    __ _   _   _   _ __
| '_ ` _ \  | | | '_ \  | |  / _` | | | | | | '_ \
| | | | | | | | | | | | | | | (_| | | |_| | | | | |
|_| |_| |_| |_| |_| |_| |_|  \__, |  \__,_| |_| |_|
                              __/ |
                             |___/
```

**minigun** is a simple but powerful load-testing tool designed to help you
make your apps more performant, reliable, and scalable.

[http://minigun.io](http://minigun.io)

[![Build Status](https://travis-ci.org/shoreditch-ops/minigun.svg?branch=master)](https://travis-ci.org/shoreditch-ops/minigun)

[![gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/shoreditch-ops/minigun)

# Features

- HTTP(S) and WebSocket support
- Detailed performance metrics (latency, RPS, throughput)
- NEW! Graphical reports
- Test scenarios are just easy-to-read JSON - all declarative, no code ([see an example](https://github.com/shoreditch-ops/minigun-core/blob/master/test/scripts/all_features.json))
- Dynamic payloads
- Use minigun as a standalone CLI tool or as a Node.js library
- Good performance
- Plugin support (experimental) - [docs](https://github.com/shoreditch-ops/minigun/blob/master/docs/plugins.md)
- Open-source & free

# Quickstart

## Install

**minigun** is available via [npm](http://npmjs.org)

`$ npm install -g minigun`

## Run

`$ minigun quick -d 30 -r 5 http://127.0.0.1:3000/test`

This will run a test for 30 seconds with an average of 5 new requests to
`http://127.0.0.1:3000/test` every second.

## Run with a more complex scenario

`$ minigun run hello.json`

Where `hello.json` is your tests script that contains something like:

```javascript
{
  "config": {
      "target": "http://127.0.0.1:3000",
      "phases": [
        { "duration": 120, "arrivalRate": 10 }
      ],
      "defaults": {
        "headers": {
          "content-type": "application/json",
          "x-my-service-auth": "<PASSWORD>"
        }
      }
  },
  "scenarios": [
    {
      "flow": [
        { "get": {"url": "/test"}},
        { "think": 1 },
        { "post": {"url": "/test", "json": { "name": "hassy" }}}
      ]
    }
  ]
}
```

# Create a report

Create a graphical report from the JSON stats produced by `minigun run` with:
`minigun report <minigun_report_xxxxx.json>`

An example: :tophat:

![https://cldup.com/PYeZJTCe86-1200x1200.png](https://cldup.com/PYeZJTCe86-1200x1200.png)

# Use cases

- Benchmark the performance of your API or microservice as you're building it
- Ensure new code does not introduce performance regressions
- Test your code for memory leaks
- Benchmark dependencies (libraries, frameworks, external services) to get a
  feel for their performance characteristics before you integrate
- Run load-tests before you launch to ensure your application can meet
  projected demand

# Learn More

- [HTTP Features](https://github.com/shoreditch-ops/minigun/wiki/HTTP-Features)
- [WebSocket Features](https://github.com/shoreditch-ops/minigun/wiki/WebSocket-Features)


## When NOT to use Minigun

Minigun is **not** a web server benchmarking tool. Its sweet spot is performance
testing of applications and APIs with complex transactional scenarios.

Having said that, Minigun is capable of generating 500+ RPS on modest hardware
(a 512MB Digital Ocean droplet). Still though, if you are after raw RPS to
simply hammer a single URL, you may want to use [`wrk`](https://github.com/wg/wrk) instead.

**tldr:**
Benchmarking an Nginx installation? Use [`wrk`](https://github.com/wg/wrk). Testing a Node.js
API, a RoR webapp, or a realtime WebSocket-based app? Use Minigun.

# Design

## Declarative tests

**minigun** test cases are 100% declarative. Your test-case describes _what_
needs to happen, not _how_ it happens.

Benefits of this approach:

- Tests can be 100% reproducible, since there is no custom code.
- Test cases can be auto-generated and analysed by other tools - it's just JSON.
- DSLs can be written for any language. We have a JS DSL on the roadmap, and
  one can be written easily for Ruby, Python, Lua or another language.
- Stronger performance guarantees can be made in absence of custom code.

Further reading:
- [Imperative vs Declarative Programming](http://latentflip.com/imperative-vs-declarative/)

## Statistically-sound testing

### Modeling user arrivals

{'fraction_non_alphanumeric': 0.13031581347622848, 'fraction_numerical': 0.017443849047999088, 'mean_word_length': 3.116377287658376, 'pattern_counts': {'":': 36, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 22, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 6, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4832108', 'n_tokens_mistral': 3013, 'n_tokens_neox': 2809, 'n_words': 869}