# `mix stampede.run`
[🔗](https://github.com/mandar1045/stampede/blob/v0.2.0/lib/mix/tasks/stampede.run.ex#L1)

Runs the load test scenarios defined in a file.

    $ mix stampede.run loadtest/lobby.exs
    $ mix stampede.run loadtest/lobby.exs --vus 100 --duration 1m
    $ mix stampede.run loadtest/api.exs --rate 200 --duration 5m --out results.json

Every module in the file that implements `Stampede.Scenario` runs, one
after the other, with a progress line every second and a summary at the
end. The task exits with status 1 when a threshold fails, so it can gate CI.

Your project is compiled and configured, but its application is not
started, since the system under test usually runs somewhere else. Start
it in `c:Stampede.Scenario.setup/1` if a scenario needs it.

## Options

  * `--vus` - how many VUs to run at once
  * `--rate` - how many iterations to start per second, instead of `--vus`
  * `--duration` - how long to run, such as `500ms`, `30s`, `5m` or `1h`
  * `--max-vus` - how many iterations a `--rate` run may have in progress
  * `--out` - a file to write the results to, as a JSON array with one
    object per scenario, in the format of `Stampede.Reporter.to_json/1`
  * `--nodes` - other nodes to run VUs on too, separated by commas

`--vus` and `--rate` replace the scenario's own VUs, rate and stages, and
`--duration` replaces its stages.

## Running on several machines

Start a node on every machine, from the same project, and the task with
a name and the same cookie:

    $ iex --sname worker --cookie load -S mix
    $ elixir --sname loader --cookie load -S mix stampede.run loadtest/lobby.exs --nodes worker@host

The VUs are split evenly between the task's node and the given ones, and
the scenarios in the file are loaded on all of them.

---

*Consult [api-reference.md](api-reference.md) for complete listing*