# Load Test Harness

> Builds repeatable load tests and benchmarks for hot paths, measuring latency, throughput, and failures under load. Use when validating a throughput/latency target, a scalability concern, or asked for a load/stress/soak test or benchmark.

- Skill: `rockclaver/load-test-harness` (Agent Skill)
- Install (CLI): `npx skillmds@latest add rockclaver/load-test-harness`
- Raw SKILL.md: https://api.skillmd.com/api/skills/rockclaver/load-test-harness/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: rockclaver (https://skillmd.com/u/rockclaver)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/rockclaver/load-test-harness

---


# Load Test Harness

Turn "will it scale?" into a measured answer. Arm of `scale-readiness-review`; use `deterministic-test-harness` for seeded data.

## Quick Start

1. Define the target: path, throughput, p95/p99 latency, error budget.
2. Seed realistic data at scale; isolate the env.
3. Pick an available load tool.
4. Run baseline, then target load, then push to breaking point.
5. Report percentiles and the first bottleneck -- not averages.

## Choose the Tool

- HTTP APIs: `k6`, `vegeta`, `wrk`, `locust`, or the language's lib.
- Workers/queues: enqueue a burst, measure drain rate.
- Database/query: `EXPLAIN ANALYZE` plus a timed batch loop.
- Pure functions: benchmark framework (`go test -bench`, `pytest-benchmark`).

## Run the Right Profiles

- **Baseline**: low, steady load; healthy latency.
- **Target**: expected peak; confirm it meets the goal.
- **Stress**: ramp until it breaks; find the ceiling and first bottleneck.
- **Soak**: sustained load over time; catch leaks, pool exhaustion, drift.

## Measure and Report

Report throughput vs target, latency p50/p95/p99, and error rate/types. Pair with `observability-instrumentation` metrics to see the first saturated resource (CPU, connections, pool, queue, locks).

```text
Result: checkout endpoint, target 200 rps
Throughput: 210 rps sustained
Latency: p50 40ms, p95 180ms, p99 850ms
Errors: 0.2% (timeouts at peak)
Bottleneck: DB connection pool saturated at ~190 rps; p99 spikes follow pool waits.
Next: raise pool size / add read replica; re-run to confirm p99.
```

## Guardrails

- Do not run load tests against production without approval, or on toy data -- small datasets hide real bottlenecks.
- Do not conclude from a single run, or optimize before the harness shows the bottleneck.