Introduction

test-scale is an open-source distributed load testing platform. You describe a single HTTP request and a traffic shape in YAML; the platform spins up workers, generates load, merges histogram-correct latency metrics, and stores every run for comparison.

The problem it solves

Traditional load tools often leave you managing generators yourself: provisioning VMs, syncing scripts, and guessing how many processes you need for a target RPS. test-scale inverts that:

• You declare intent — target URL, method, headers, auth, target_rps, duration_sec, ramp pattern.
• The platform scales workers — before the run starts, not after latency already spiked.
• You get comparable reports — same plan, new run, diff against a baseline slug.

That workflow matches release gates and performance regression checks more than one-off stress experiments.

What test-scale is good at

Use case	Why it fits
CI smoke load	Fixed plan, zero errors, make docker-smoke
API regression	test-scale diff --fail-on-regression vs baseline
Pre-launch sanity	JWT/session auth, JSON POST, expected status codes
Team dashboards	Built-in UI + Grafana for live RPS and percentiles

What test-scale is not (v0.1)

• Not a browser or multi-step journey tool — one HTTP request per plan.
• Not synthetic uptime monitoring — runs are on-demand.
• Not APM inside your service — metrics are what workers observe from the outside.
• Not geo-distributed clients yet — Docker Compose uses one host; Kubernetes spreads workers across nodes.

Core components

Component	Role
CLI / UI	Submit plans, watch runs, compare results
Control plane	API, orchestrator, Postgres persistence
NATS	Job queue between control plane and workers
Autoscaler	Brain (how many workers?) + scaler (Docker or KEDA)
Workers	Stateless HTTP load generators
Aggregator	Merges per-worker histograms (OTel → Prometheus)
Grafana	Live and historical dashboards

See Architecture for data flow and failure handling.

Next steps

1. Install test-scale (Docker, Homebrew, or Helm).
2. First run — make quickstart on a clean machine.
3. Web UI — submit and compare runs in the browser.
4. Test plans — full YAML reference.
5. Interpreting results — when to trust local numbers.