Loopback Load Tester
A local and distributed HTTP load-testing CLI for measuring throughput, latency percentiles, success rates, and server failures under controlled concurrent traffic.
Software Engineer
Project context
A CLI tool to measure API behavior under growing concurrency, designed for both local and distributed testing.
The problem
Development teams need a reproducible way to understand how an API behaves as concurrency grows, while keeping tests scriptable for local workflows and scalable across several load-generating machines.
Technical approach
Engineered a Node.js CLI with run, master, and worker commands; multi-process local execution; synchronized Socket.IO workers; weighted YAML/JSON scenarios; Bearer and custom-header support; p50, p95, and p99 latency metrics; configurable p95 and 5xx thresholds; CI-friendly exit codes; and sanitized JSON reports.
Design goal
Make an HTTP workload repeatable from the command line and usable in automation. A scenario describes the requests, execution settings control concurrency, and output exposes the measurements and threshold decisions needed to compare runs.
Execution architecture
The CLI separates run, master, and worker commands. Local execution can use multiple processes, while distributed execution coordinates load-generating workers through Socket.IO. Undici handles HTTP traffic and YAML or JSON scenarios describe weighted requests, allowing a workload to be expressed as configuration rather than a custom script.
Scenario configuration
Weighted YAML or JSON scenarios describe the request mix. Bearer authentication and custom headers allow requests to represent authenticated endpoints. Keeping this information in scenario configuration makes the workload explicit and easier to reproduce across local and distributed execution.
Master and worker boundaries
The command structure distinguishes direct execution from coordination and load generation. Socket.IO synchronizes distributed workers, while local runs can use multiple processes. These execution modes address different load-generation needs without changing the purpose of the measurements.
Measurement workflow
A test can progress through warm-up, ramp-up, and steady-state phases. Reports describe throughput, success rates, server errors, and latency percentiles including p50, p95, and p99. Configurable p95 and 5xx thresholds produce exit codes suitable for CI, while sanitized JSON reports make results easier to retain and compare.
Warm-up and steady-state phases
Warm-up separates initial behavior from the measured workload, and ramp-up increases traffic before the steady-state phase. Reading results alongside these phases helps distinguish startup effects from sustained behavior. Phase settings are therefore part of the test conditions that should accompany a benchmark report.
Thresholds and CI reports
The p95 and 5xx thresholds turn measurements into configurable pass or fail decisions. Exit codes allow a CI job to consume that decision, while JSON reports retain structured output. Percentiles complement throughput by describing how request duration is distributed across the run.
Key capabilities
- Local and distributed load generation
- Warm-up, ramp-up, and steady-state phases
- p50, p95, and p99 latency reporting
- CI-friendly thresholds and JSON reports
Outcome
Enabled reproducible performance benchmarks with CI-friendly exit codes and detailed latency reports.
Interpreting the results
A benchmark describes the scenario and environment in which it ran. Worker capacity, network conditions, request mix, and target configuration all affect the measurements. Reproducible comparisons therefore require consistent inputs and test conditions; the tool’s output should be read alongside those conditions rather than as a universal capacity figure.
Measurement limits
The generator is part of the experiment: CPU saturation or network limits on a worker can constrain the traffic reaching the target. Comparisons should preserve scenario, worker resources, and target settings. A higher request count alone does not establish a better user-facing latency profile.
