blast docs

blast is a config-driven API load tester and mock server written in Rust. Define your endpoints in blast.config.json, then hit every one with a single command — no code, no scripting.

It supports fake data generation via {{fake.*}} placeholders, request chaining using JSON extraction and dot-path rules, fixed-RPS load tests, and stress ramp tests that auto-detect where your API breaks.

Installation

curl -fsSL https://raw.githubusercontent.com/Walon-Foundation/blast/main/install.sh | sh

irm https://raw.githubusercontent.com/Walon-Foundation/blast/main/install.ps1 | iex

cargo install --git https://github.com/Walon-Foundation/blast

Quick start

# 1. Create a starter config in the current directory
blast init

# 2. Verify the config is valid and show all endpoints
blast validate

# 3. Hit every endpoint once to confirm they respond
blast check

# 4. Seed test data (runs endpoints tagged "seed")
blast seed --count 50 --concurrency 10

# 5. Fixed-rate load test (endpoints tagged "run")
blast run --rps 50 --duration 60

# 6. Stress ramp — finds the breaking point
blast stress --min-rps 10 --max-rps 200 --step 20 --step-duration 30

Commands

blast init
blast init ./my-api

blast seed --count 1000 --concurrency 20

blast run --rps 100 --duration 120
blast run --rps 50 --ramp-up 30 --duration 60
blast run --output json
blast run --output html
blast run --rps 200 --assert "p99<300ms" --assert "error-rate<1%"

blast stress --min-rps 10 --max-rps 500 --step 50 --step-duration 20
blast stress --output json
blast stress --assert "p99<500ms"

blast mock
blast mock --port 8080
blast mock --config ./api/blast.config.json

$ blast mock --port 4000

  Loaded blast.config.json

  GET    /api/v1/users               200
  POST   /api/v1/auth/register       201
  POST   /api/v1/auth/login          200
  GET    /api/v1/users/{id}          200
  DELETE /api/v1/users/{id}          204

  5 routes mounted
  Listening on http://localhost:4000

blast trace "login"
blast trace "get user"

$ blast trace "login"

── request ─────────────────────────────────────
POST http://localhost:3000/api/v1/auth/login
  Content-Type: application/json
{ "email": "admin@example.com", "password": "Admin1234!" }

── response (200 ✓ — 14ms) ──────────────────────
  content-type: application/json
{ "data": { "access_token": "eyJ..." } }

blast stage

{
  "stages": [
    { "rps": 10,  "duration": 30  },
    { "rps": 50,  "duration": 60  },
    { "rps": 100, "duration": 120 },
    { "rps": 0,   "duration": 30  }
  ]
}

Configuration

blast reads blast.config.json from the current directory (or the path passed to --config). The file has a flat structure — a base URL, global headers, an optional setup array, and an endpoints array.

{
  "base_url": "http://localhost:3000",
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "Bearer {{token}}"
  },
  "setup": [
    {
      "name": "login",
      "method": "POST",
      "path": "/api/v1/auth/login",
      "body": { "email": "admin@example.com", "password": "Admin1234!" },
      "expect_status": 200,
      "extract": { "token": "data.access_token" }
    }
  ],
  "endpoints": [
    {
      "name": "register user",
      "method": "POST",
      "path": "/api/v1/auth/register",
      "body": {
        "email": "{{fake.email}}",
        "password": "{{fake.password}}",
        "name": "{{fake.name}}"
      },
      "expect_status": 201,
      "tags": ["seed"]
    },
    {
      "name": "list users",
      "method": "GET",
      "path": "/api/v1/users",
      "expect_status": 200,
      "weight": 3,
      "tags": ["run"]
    },
    {
      "name": "get user",
      "method": "GET",
      "path": "/api/v1/users/{{user_id}}",
      "expect_status": 200,
      "tags": ["run"]
    }
  ]
}

Endpoint fields

Stages

The top-level stages array defines a multi-stage load profile for blast stage. Each entry sets a target RPS and duration. A stage with rps: 0 is a cooldown — blast sleeps for the duration and fires no requests.

{
  "base_url": "http://localhost:3000",
  "stages": [
    { "rps": 10,  "duration": 30  },
    { "rps": 50,  "duration": 60  },
    { "rps": 100, "duration": 120 },
    { "rps": 0,   "duration": 30  }
  ],
  "endpoints": [...]
}

Fake data

Use {{fake.*}} placeholders in request body examples or header values. A new value is generated per request — every iteration of blast seed and every request in blast run gets fresh data.

Unknown placeholders produce a warning and are left unchanged in the output so they are easy to spot.

Tags

The tags array on an endpoint controls which blast command picks it up. An endpoint can appear in multiple commands by listing multiple tags.

If no endpoints have any tags, all commands fall back to using every endpoint. Endpoints in the setup array are always excluded from tag matching — they run once before load regardless of tags.

Setup phase

The top-level setup array in blast.config.json lists endpoints that run once in order before any load traffic. Extracted values from setup steps are shared with every subsequent request for the entire test.

If a setup step fails (wrong status code, network error), blast aborts immediately rather than firing load with a broken context. This prevents sending thousands of requests with a missing auth token.

The canonical use case is authentication: add a login endpoint to setup, extract the access token with extract, then include it in every load endpoint via the global headers using {{token}}.

Request chaining

The extract field on any endpoint stores response values in a shared context map keyed by variable name. Later endpoints reference them with {{name}} in any string field — headers, body values, or URL path parameters.

The dot-path walker descends into nested JSON objects (data.user.id) and array indices (items.0.id). Only scalar values (strings, numbers, booleans) are stored — objects and arrays emit a warning and are skipped.

{
  "name": "login",
  "method": "POST",
  "path": "/api/v1/auth/login",
  "body": { "email": "admin@example.com", "password": "Admin1234!" },
  "expect_status": 200,
  "extract": {
    "token":   "data.access_token",
    "user_id": "data.user.id"
  }
}

{
  "name": "get user",
  "method": "GET",
  "path": "/api/v1/users/{{user_id}}",
  "headers": { "Authorization": "Bearer {{token}}" },
  "expect_status": 200,
  "tags": ["run"]
}

Values extracted during setup are available to all subsequent endpoints. Values extracted during load operations are available to later endpoints in the same request round.

Scenarios

Adding scenario: "name" to endpoints groups them into ordered sequences. When scenarios are present in the config, blast run executes one full scenario sequence per iteration rather than round-robining individual endpoints. Each sequence runs with its own local extraction context, so values extracted in step 1 are available to step 2 — enabling realistic user journeys.

{ "name": "register",       "method": "POST", "path": "/auth/register",
  "scenario": "auth-flow",  "expect_status": 201,
  "extract": { "user_id": "data.id" } },
{ "name": "login",          "method": "POST", "path": "/auth/login",
  "scenario": "auth-flow",  "expect_status": 200,
  "extract": { "token": "data.access_token" } },
{ "name": "fetch profile",  "method": "GET",  "path": "/users/{{user_id}}",
  "scenario": "auth-flow",  "headers": { "Authorization": "Bearer {{token}}" },
  "expect_status": 200 }

Variable files

Pass --vars path/to/vars.json to any command to inject a flat JSON object of variables into the template context. These have the lowest precedence — they are overridden by values extracted from responses or set by environment variables.

{
  "base_user": "admin@example.com",
  "org_id":    "acme-corp",
  "tier":      "enterprise"
}

blast run --vars staging.json
blast check --vars ./env/prod.json

Only scalar values (strings, numbers, booleans) are accepted. Nested objects and arrays produce a warning and are skipped.

Threshold assertions

Pass one or more --assert flags to blast run or blast stress to enforce performance thresholds. blast evaluates assertions after the test and exits non-zero if any fail — enabling performance gates in CI pipelines.

blast run --rps 100 --duration 60 \
  --assert "p99<200ms" \
  --assert "error-rate<1%"

# exits 0 if all pass, non-zero with details if any fail

Body assertions (per-endpoint) use the assert field and are evaluated by blast check. See Endpoint fields.

History

After every blast run or blast stress, blast automatically saves the result to ~/.blast/history/. On the next run against the same config, it prints a one-line comparison showing how p50, p95, p99, and p999 changed.

$ blast run --rps 100 --duration 60

  ...

  vs last run:
    p50   42ms → 38ms  (-9%) ▼
    p95   89ms → 91ms  (+2%) →
    p99  142ms → 198ms (+39%) ▲

No flags needed — history runs silently and never affects the exit code. Records are keyed by the canonical config file path.