Monthly Downloads: 18
Programming language: Elm
License: BSD 3-clause "New" or "Revised" License
Tags: Web     Wrecker    
Latest version: v3.3.1
Add another 'wrecker' Package



This tool contains a small HTTP server and javascript application that can be used to store the results of different wrecker runs and plot them.

Wrecker is a library for building performance test suites that shines when testing REST APIs, where the result of one step needs to be used for the following one.

It is meant to be used as a way to track progress between various runs of wrecker so it can be said confidently that the performance of a particular work flow was affected in between code changes.


The easiest way to use this tool is to download a binary from the releases page


You first need to start the HTTP server. It will automatically create a wrecker.db sqlite3 database in the current directory:


Typically, you would use wrecker-ui paired with a wrecker executable CLI command, containing your own tests. By default, wrecker-ui looks for wrecker command present in PATH, but you can customize it by providing the WRECKER_EXECUTABLE environment variable. The value of the variable needs to have the name of the executable in it:

WRECKER_EXECUTABLE="/path/to/wrecker-cli" wrecker-ui

If you want to run from a folder where the assets directory is not present. Then set the WRECKER_ASSETS env variable

WRECKER_ASSETS="/path/to/assets" wrecker-ui

The server will start in port 3000. You can then visit http://localhost:3000/ to start using the UI. It wil not contain any data the first time. So you need to populate it yourself:

Alternatively you can change the default port using the WRECKER_UI_PORT env variable

WRECKER_UI_PORT=8000 wrecker-ui

Using PostgreSQL

Wrecker-UI uses SQLite by default for storing the runs results. You can alternatively use PostgreSQL for this purpose when passing a connection string via the WRECKER_DB env variable:

WRECKER_DB="postgres://user:[email protected]/db_name" wrecker-ui

Executing load testing runs

The Web interface is able to execute runs using wrecker. For this purpose it is required that your wrecker to provide test groups, that is, the web interface is only usefule when you have used wrecker as a library to creat your own test suite.

Click on the Schedule Test link to see a list of tests available to wrecker and set the options for the run. Results should shortly appear in the plot for the given test name.

Manually storing runs in the database

Use the --output-path option when executing wrecker to produce a JSON file. This file will be parsed and stored by this application. Then, create the first run with the options you provided to wrecker:

curl -X POST 'http://localhost:3000/runs' \
    -d title="My Title" \
    -d groupName="Optional Group Name" \
    -d concurrency=100

The groupName param is used to display runs under the same group with the same color in the UI. This is handy when you are calling wrecker in a batch script in order to figure out the application behavior under different concurrency loads.

This will return an id you can use for future requests:

{"success": true, "id": 1}

Now, use the id to store the JSON result from the wrecker run:

curl -X POST 'http://localhost:3000/runs/1' \
    --data-binary @/path/to/file.json

You can now see you results in the web interface.

Distributing load testing accross nodes

Wrecker is limited by the amount of memory and CPU available to a single machine. For slow pages (triple digit milliseconds) it is usually not a problem, as Haskell can very intelligently save memory while it is waiting for results to be transmitted over the wire. But for a big concurrency number, specially in the presence of fast responding pages, it is easy to exhaust the available resources.

Wrecker-UI allows you to distribute the testing load across nodes in the network, once the concurrency level for a test exceeds 2000 threads.

In order to distribute the load you need to first create the worker nodes, by starting wrecker-ui in slave mode in another machine:


The WRECKER_HOST env var is the IP or hostname that the worker will be bound to. If no variable is provided, it will bind itself to which is generally not very useful unless you are testing in a single machine.

You can start as many slaves as you need. Generally it makes no sense to start more than one node per physical machine. After starting the worker nodes, you can start the master node. The master node is also the node that will display the web interface.

You start the master node as described in the previous sections. Upon start, it should show something like this:

Found the following slave servers: [nid://]

Note: All nodes where wrecker-ui is running, will also need wrecker to be in the $PATH

Static list of workers

Wrecker-UI uses a unicast broadcast to discover the workers in the network. This is sometimes not possible or desirable, for example when deploying it in AWS EC2 servers. The workaround is to specify a static list of worker servers when starting the master node:

WRECKER_SLAVES=, wrecker-ui

Wrecker-UI does not currently verify that the slaves can actaully respond when specifying a static list. This is oftentimes convenient as it does not impose any restrictions in the order the nodes need to be started.

Building from source


Install the stack tool from the link above. Then cd to the root folder of this repo and execute:

stack setup
stack install

If it is the first time, it will take a lot of time. Don't worry, it's only once you need to pay this price.

Currently, we require a fork of an official Elm package. Therefore, we are unable to use elm-package to install dependencies. Instead, use elm-install. just executed it to the the Elm dependencies:


The UI is built using the elm-make command

elm-make UI.elm --output=assets/app.js


During development, it is recommended that you use elm-live for a quick feedback loop after changing the Elm files:

npm install -g elm-live

Then you can run

elm-live UI/UI.elm --dir=assets/ --output=assets/app.js

Now you can use wrecker-ui as usual, but it will automatically reload the browser on any change done to the .elm files.