🐂 Stampede

    ╔═══════════════════════════════════════════╗
    ║                                           ║
    ║   🐂  P I T C H F O R K                  ║
    ║                                           ║
    ║   Angry Mob Load Testing                  ║
    ║                                           ║
    ║   How many stampedes can your app        ║
    ║   handle before it falls?                 ║
    ║                                           ║
    ╚═══════════════════════════════════════════╝

A dead-simple load testing CLI. Point it at a URL, send an angry mob of concurrent requests, and find out where your app breaks.

Quick Start

# Storm — steady load (50 users for 30 seconds)
npx stampede-load storm https://your-app.com

# Siege — ramp to failure
npx stampede-load siege https://your-app.com --max-users 500

That's it. No config files. No YAML. No setup.

Install

npm install -g stampede-load

Or just use npx:

npx stampede-load storm https://your-app.com

Modes

⛈️ Storm — Steady Load

Fixed concurrent users for a set duration. The baseline test.

stampede storm https://your-app.com --users 100 --duration 60s

🏰 Siege — Ramp to Failure

Gradually increase users until your app breaks (or survives).

stampede siege https://your-app.com \
  --min-users 10 --max-users 500 --step 10 --step-duration 5s

CLI Reference

Storm Options

| Flag | Default | Description | |------|---------|-------------| | -u, --users <n> | 50 | Concurrent users | | -d, --duration <t> | 30s | Test duration (10s, 5m, 1h) | | -m, --method <m> | GET | HTTP method | | -H, --header <h> | — | HTTP header (repeatable) | | -b, --body <b> | — | Request body | | -t, --timeout <ms> | 10000 | Request timeout in ms | | -f, --format <f> | text | Output format: text or json | | --ci | false | CI mode (exit 1 on failure) | | --max-error-rate <n> | 5 | Max error rate % for CI mode |

Siege Options

| Flag | Default | Description | |------|---------|-------------| | --min-users <n> | 10 | Starting concurrent users | | --max-users <n> | 200 | Maximum concurrent users | | --step <n> | 10 | Users added per step | | --step-duration <t> | 5s | Duration per step | | -m, --method <m> | GET | HTTP method | | -H, --header <h> | — | HTTP header (repeatable) | | -b, --body <b> | — | Request body | | -t, --timeout <ms> | 10000 | Request timeout in ms | | -f, --format <f> | text | Output format: text or json | | --ci | false | CI mode (exit 1 on failure) | | --max-error-rate <n> | 5 | Max error rate % for CI mode |

Examples

Basic GET load test

stampede storm https://api.example.com/health --users 50 --duration 30s

POST with auth headers

stampede storm https://api.example.com/chat \
  --users 20 --duration 30s \
  --method POST \
  --header "Authorization: Bearer your-token" \
  --header "Content-Type: application/json" \
  --body '{"message": "test"}'

CI pipeline (fail on >5% errors)

stampede storm https://staging.example.com --users 100 --duration 60s --ci --max-error-rate 5

JSON output for automation

stampede storm https://api.example.com --users 50 --duration 30s --format json

Find breaking point

stampede siege https://api.example.com \
  --min-users 10 --max-users 1000 --step 25 --step-duration 5s

Sample Output

Storm

🐂 Stampede v0.1.0 — Storm

  Target: https://clawlobby.com/api/health
  Users: 50 | Duration: 30s

  ████████████████████████████████████████ 30.0s / 30.0s  |  2,847 req  |  94.9 req/s

  Results:
    Total requests:     2,847
    Successful (2xx):   2,831 (99.4%)
    Rate limited (429): 14 (0.5%) ✅
    Server errors (5xx): 2 (0.1%)

  Response times:
    Min:       12ms
    Median:    42ms
    p90:       128ms
    p95:       186ms
    p99:       412ms
    Max:       1,204ms

  Throughput:   94.9 req/s
  Data:         12.4 MB received

  Verdict: ✅ SURVIVES (99.4% success rate) at 50 concurrent users
  Rate limiting active ✅ — server protects itself

Siege

🐂 Stampede v0.1.0 — Siege

  Target: https://clawlobby.com
  Ramp: 10 → 500 users | Step: +10 every 5.0s

  Step 49/50  |  500 users  |  12,847 req  |  247.1 req/s

  Results:
    Total requests:     12,847
    Successful (2xx):   12,203 (95.0%)
    Rate limited (429): 312 (2.4%) ✅
    Server errors (5xx): 332 (2.6%)

  Response times:
    Min:       8ms
    Median:    67ms
    p90:       312ms
    p95:       589ms
    p99:       2,104ms
    Max:       5,012ms

  Breaking point: ~250 users (error rate exceeded 50% at step 25)
  Ramp: 10 → 500 users over 245.0s (49 steps × 5.0s)

  Verdict: ⚠️ STRESSED (95.0% success rate)
  Rate limiting active ✅ — server protects itself

Verdicts

| Verdict | Condition | Meaning | |---------|-----------|---------| | ✅ SURVIVES | ≥99% success | Your app handles the load | | ⚠️ STRESSED | 95–99% success | Degraded but functional | | ❌ OVERWHELMED | <95% success | Your app is broken at this load |

Rate limiting (429) is reported separately — it's a sign your server protects itself, not a failure.

Why Stampede?

| | Stampede | k6 | Artillery | wrk | |---|---|---|---|---| | npx-ready | ✅ | ❌ | ❌ | ❌ | | Zero config | ✅ | ❌ | ❌ | ✅ | | Clear verdict | ✅ | ❌ | ❌ | ❌ | | Rate limit aware | ✅ | ❌ | ❌ | ❌ | | Real-time progress | ✅ | ✅ | ✅ | ❌ | | CI mode | ✅ | ✅ | ✅ | ❌ | | JSON output | ✅ | ✅ | ✅ | ❌ | | Scripting | ❌ (coming) | ✅ | ✅ | ❌ | | Distributed | ❌ (coming) | ✅ | ✅ | ❌ |

Stampede isn't trying to replace k6 or Artillery for complex scenarios. It's for when you want a quick, honest answer: can my app handle this?

Roadmap

• [x] v0.1 — Storm + Siege modes, real-time terminal, verdicts
• [ ] v0.5 — Riot (spike), March (soak), Drain (cost attack), JSON reports
• [ ] v1.0 — AI cost estimation, HTML reports, CI integration, scheduled tests

Requirements

• Node.js ≥ 18 (uses native fetch)

License

MIT