Load Testing with k6 skill for Claude Code

A load test answers a written question (“can checkout sustain 300 req/s at p95 < 400 ms with < 0.5% errors?”) with a pass/fail verdict and a named bottleneck. Running load without a target, thresholds, and server-side metrics produces numbers, not answers.

Ground rules

• Never load test production or third-party APIs without explicit written permission from the owner, a time window, and a stop plan. Default to a production-like staging stack.
• Write the goal and thresholds before the script.
• Use arrival-rate executors (open model) for request-rate goals. VU-based loops slow down when the server slows down and hide latency (coordinated omission).
• Watch server metrics (CPU, memory, DB connections, queue depth, GC) during the run; client numbers alone cannot locate the bottleneck.
• Run the load generator close to the target network-wise and confirm the generator itself is not saturated (CPU < ~80%, no dropped_iterations).

Workflow

- [ ] 1. Define goal: traffic model, target rate, SLO thresholds, test type
- [ ] 2. Confirm environment, permission, data, and monitoring
- [ ] 3. Write the script with scenarios, tags, checks, thresholds
- [ ] 4. Smoke test (1–2 VUs, 1 min) to validate the script
- [ ] 5. Run the real test; watch server dashboards live
- [ ] 6. Analyze: thresholds, percentiles over time, saturation point
- [ ] 7. Write the capacity report

1. Choose the test type

Question	Type	Shape
Does the script work?	Smoke	1–2 VUs, 1 min
Does it meet SLO at expected peak?	Load	Ramp to peak, hold 10–30 min
Where does it break and how?	Stress / breakpoint	Increase rate in steps until thresholds fail; abortOnFail
Can it absorb a sudden burst?	Spike	Jump to 5–10x in seconds, hold briefly, drop
Does it degrade over hours (leaks, pool exhaustion)?	Soak	Expected load for 2–8 h

Derive the target rate from data: peak requests/s from access logs or APM, multiplied by expected growth and a headroom factor (commonly 1.5–2x). Model the request mix per endpoint from real traffic proportions.

3. Script

// load/checkout.js
import http from 'k6/http';
import { check, sleep } from 'k6';

const BASE = __ENV.BASE_URL || 'https://staging.example.com';

export const options = {
  scenarios: {
    browse: {
      executor: 'ramping-arrival-rate',
      exec: 'browse',
      startRate: 20, timeUnit: '1s',
      preAllocatedVUs: 100, maxVUs: 500,
      stages: [
        { duration: '3m', target: 200 },   // ramp
        { duration: '15m', target: 200 },  // hold at peak
        { duration: '2m', target: 0 },
      ],
    },
    checkout: {
      executor: 'constant-arrival-rate',
      exec: 'checkout',
      rate: 20, timeUnit: '1s', duration: '20m',
      preAllocatedVUs: 50, maxVUs: 200,
    },
  },
  thresholds: {
    http_req_failed: ['rate<0.005'],
    'http_req_duration{name:product}': ['p(95)<300', 'p(99)<800'],
    'http_req_duration{name:checkout}': [{ threshold: 'p(95)<500', abortOnFail: true, delayAbortEval: '2m' }],
    checks: ['rate>0.99'],
  },
  summaryTrendStats: ['avg', 'med', 'p(90)', 'p(95)', 'p(99)', 'max'],
};

export function setup() {
  const res = http.post(`${BASE}/api/test/tokens`, JSON.stringify({ count: 500 }),
    { headers: { 'Content-Type': 'application/json' } });
  return { tokens: res.json('tokens') };
}

export function browse() {
  const id = Math.floor(Math.random() * 10000) + 1;
  const res = http.get(`${BASE}/api/products/${id}`, { tags: { name: 'product' } });
  check(res, { 'status 200': (r) => r.status === 200 });
  sleep(Math.random() * 2);  // think time; does not reduce arrival rate in open model
}

export function checkout(data) {
  const token = data.tokens[__ITER % data.tokens.length];
  const res = http.post(`${BASE}/api/checkout`, JSON.stringify({ sku: 'A-1', qty: 1 }), {
    headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
    tags: { name: 'checkout' },
  });
  check(res, { 'order created': (r) => r.status === 201 });
}

export function handleSummary(data) {
  return { 'summary.json': JSON.stringify(data, null, 2) };
}

Script rules:

• Tag every request with a stable name; URLs with IDs otherwise explode into thousands of metric series.
• Thresholds per critical endpoint, not just global. A fast health endpoint can hide a slow checkout in the aggregate.
• Use realistic data: varied IDs, auth tokens for many users, cache-busting where real traffic would miss caches. Hitting one ID measures your cache.
• Keep check for correctness (status, body), thresholds for SLOs.
• Default handleSummary output to stdout is replaced when you define it; add stdout: textSummary(...) from the k6 jslib if you want both.

4–5. Run

k6 run load/checkout.js -e BASE_URL=https://staging.example.com
k6 run --vus 1 --iterations 5 load/checkout.js          # quick script check
K6_WEB_DASHBOARD=true k6 run load/checkout.js           # live dashboard on localhost:5665
k6 run --out json=raw.json load/checkout.js             # per-request data points (large)

k6 exits non-zero when any threshold fails, which makes it a CI gate. Stop the test if error rates spike in a way that risks shared infrastructure.

6. Analyze

python3 scripts/k6_summary.py summary.json
python3 scripts/k6_summary.py summary.json --baseline previous/summary.json --max-regression 10

The script prints throughput, error rate, per-endpoint percentiles, threshold verdicts, dropped iterations, and p95 regressions against a baseline; it exits 1 on any failure.

Interpretation rules:

• p95/p99, never averages. Averages hide the tail users feel.
• Find the knee. In a stepped test, the capacity limit is the last step where latency is flat and errors are under threshold. Past it, latency climbs sharply while throughput plateaus.
• Little’s law sanity check: concurrent requests in flight = throughput x latency. 200 req/s at 0.25 s means ~50 in flight; if the DB pool is 20, expect queueing.
• dropped_iterations > 0 means the generator could not start iterations on schedule: results understate load. Raise maxVUs or add generators.
• Errors first. A fast p95 with 5% 503s is a failure; fast errors pull latency down.
• Correlate the knee with server metrics to name the bottleneck: CPU-bound app, DB connection pool exhaustion, lock contention, downstream rate limits, GC pauses.

Gotchas

• Testing from a laptop over Wi-Fi measures the Wi-Fi.
• Autoscaling targets need a ramp longer than scale-up time; otherwise you test cold capacity. Note min/max replicas in the report.
• Staging with a 10x smaller DB or warm caches yields optimistic numbers. Record the environment differences.
• Rate limiting or WAF rules on the target will return 429/403 and look like capacity limits. Allowlist the generator IPs with the owner.
• sleep in arrival-rate scenarios increases needed VUs but not request rate; in VU scenarios it directly lowers request rate.

Capacity report

# Load test: checkout API — 2026-03-14
**Question:** Sustain 200 req/s browse + 20 req/s checkout at p95 < 300/500 ms, errors < 0.5%?
**Verdict:** PASS at target. Breaking point ~340 req/s total.
**Environment:** staging, 4 x 2 vCPU app pods (HPA off), db.r6g.large, same region as generator
| Endpoint | Rate | p95 | p99 | Errors |
|---|---|---|---|---|
| product | 200/s | 182 ms | 410 ms | 0.02% |
| checkout | 20/s | 390 ms | 720 ms | 0.10% |
**Bottleneck:** DB connection pool (20/pod) saturated at ~340 req/s; app CPU 55%.
**Recommendations:** raise pool to 40 with PgBouncer; re-test. Add index on orders(user_id).
**Raw:** summary.json, dashboard export, Grafana snapshot link