Reproducible load tests

Load Test Implementation

When to Use

Use when implementing or modifying load test scripts, benchmark harnesses, fixture seeders, or automated performance scenarios.

Tool Selection & Harness Architecture

Adapt to the repository's existing stack or select the lightest tool that models the protocol accurately:

• k6 (Go/JS): Preferred for HTTP/1.1, HTTP/2, WebSockets, gRPC, and SSE/streaming APIs with built-in constant-arrival-rate, ramping-arrival-rate, and thresholds.
• Locust (Python): Preferred when complex stateful Python workflows or custom client SDKs are required (FastHttpUser for high-throughput HTTP).
• Targeted Benchmark Harness (Node autocannon/undici, Rust oha/criterion, Go testing.B): Preferred for isolated micro-service or local component throughput checks.

Implementation Rules for Accurate Load Generation

1. Prevent Load Generator Self-Bottlenecking

A saturated load generator produces false latency spikes and under-delivers target RPS:

• Monitor load generator CPU, memory, ephemeral ports, and event-loop lag during the run.
• Keep HTTP keep-alive and connection pooling enabled (noConnectionReuse: false in k6) unless explicitly testing TLS handshake capacity.
• Discard response bodies (discardResponseBodies: true in k6) whenever only status/headers are needed, or parse only the fields required for correlation and business assertions.
• Pre-load test data files (SharedArray in k6) once during init—never read files or generate heavy cryptographic signatures synchronously inside the hot VU iteration loop.

2. Separate Setup, Warmup, Steady State, and Cooldown

Structure every test scenario into distinct phases:

1. setup() / Data Seeding: Provision isolated test accounts, tokens, and seed rows before the clock starts.
2. Cold Start & JIT/Cache Warmup: Ramp up over an initial warmup window so JIT compilation, connection pool establishment, and cold caches are observed separately from steady-state percentiles.
3. Steady-State Measurement Window: Hold each load step long enough (at least several multiples of the longest request/queue timeout) to observe equilibrium or queue divergence.
4. Ramp-Down / Recovery Window: Step traffic back down to baseline (never cut off abruptly at peak) so post-overload queue drain and latency recovery are measured.

3. Assert Business Correctness, Not Just HTTP 200

Servers under load frequently return HTTP 200 OK with an error JSON payload, an empty fallback list, a login redirect page, or a stale cached response:

• Assert both HTTP status and semantic payload invariants (check(res, { 'status 200': r => r.status === 200, 'has order id': r => r.json('id') !== undefined })).
• Tag requests by scenario, endpoint template (name: 'GET /api/orders/:id'), and outcome so high-cardinality URL parameters do not explode metric time series.
• Never count failed, timed-out, or rate-limited (429/503) responses as successful business throughput (Goodput $\neq$ raw RPS).

4. Track Dropped Iterations & Client Timeouts Explicitly

• Configure explicit request timeouts (timeout: '10s') on every load client call.
• Assert and report dropped_iterations (when arrival-rate executors cannot allocate a free VU because in-flight requests are stuck) alongside response percentiles.