Load testing with k6

01Types of performance tests

“Load test” is used loosely, but each type answers a different question. A smoke test runs a tiny load to check the script and system work. An average-load test simulates normal traffic to confirm you meet targets. A stress test pushes beyond normal to see how the system degrades. A spike test jumps suddenly, like a push notification. A soak (endurance) test holds normal load for hours to find memory leaks and slow resource exhaustion. A breakpoint test increases load until something breaks, to find the real capacity. Start with smoke and average load; add others when you know your baseline.

• Throughput: requests or iterations per second the system completes.
• Latency percentiles: p95 means 95% of requests were faster than this value.
• Error rate: share of failed requests, often the first thing to break.

02Your first k6 script

A k6 script is an ES module. The options export describes the load and the pass/fail rules; the default function is what each virtual user (VU) runs in a loop. A VU is a simulated user running your function concurrently with others. check() validates responses without stopping the test; thresholds turn metrics into a pass or fail result, and k6 exits with a non-zero code when a threshold fails, which is what breaks a CI build. sleep() adds think time so a VU behaves like a real person, not a tight loop. k6 runs TypeScript files directly, so you can use types in larger suites.

1import http from "k6/http";
2import { check, sleep } from "k6";
3 
4export const options = {
5  vus: 20,
6  duration: "2m",
7  thresholds: {
8    http_req_failed: ["rate<0.01"],                  // under 1% errors
9    http_req_duration: ["p(95)<400", "p(99)<1000"],  // ms
10  },
11};
12 
13export default function () {
14  const res = http.get("https://staging.example.com/api/products?page=1");
15  check(res, { "status is 200": (r) => r.status === 200 });
16  sleep(1);
17}

03Scenarios and executors: open vs closed models

Scenarios let you shape load precisely and run several patterns at once. Executors decide how. Closed-model executors (constant-vus, ramping-vus) keep a number of VUs busy; if the system slows down, each VU makes fewer requests, which hides the problem. Open-model executors (constant-arrival-rate, ramping-arrival-rate) start new iterations at a fixed rate regardless of response time, which matches real internet traffic: users keep arriving even when your site is slow. For API capacity tests, prefer arrival-rate executors and give them enough preAllocatedVUs and maxVUs to sustain the rate.

1export const options = {
2  scenarios: {
3    browse: {
4      executor: "ramping-arrival-rate",
5      startRate: 10, timeUnit: "1s",
6      preAllocatedVUs: 50, maxVUs: 300,
7      stages: [
8        { target: 100, duration: "3m" }, // ramp to 100 requests/s
9        { target: 100, duration: "10m" }, // hold
10        { target: 0, duration: "2m" },   // ramp down
11      ],
12    },
13  },
14  thresholds: { "http_req_duration{scenario:browse}": ["p(95)<500"] },
15};

04Realistic user journeys

Real users log in, browse, search and check out, with pauses between steps. Model the main journeys with their real proportions from analytics (for example 80% browse, 15% search, 5% checkout). Use group() to name steps, tags to slice metrics, and SharedArray to load test data once and share it between VUs without copying memory. Generate unique data per VU and iteration where writes happen, so you do not hit the same row and create artificial lock contention. Do the setup (create a test account, get a token) in setup(), which runs once, and pass the result to VUs.

1import http from "k6/http";
2import { group, check } from "k6";
3import { SharedArray } from "k6/data";
4 
5const products = new SharedArray("products", () => JSON.parse(open("./products.json")));
6const BASE = __ENV.BASE_URL || "https://staging.example.com";
7 
8export function setup() {
9  const res = http.post(BASE + "/api/login", JSON.stringify({ email: "[email protected]", password: __ENV.TEST_PASSWORD }),
10    { headers: { "Content-Type": "application/json" } });
11  return { token: res.json("token") };
12}
13 
14export default function (data) {
15  const params = { headers: { Authorization: "Bearer " + data.token } };
16  group("product page", () => {
17    const p = products[Math.floor(Math.random() * products.length)];
18    check(http.get(BASE + "/api/products/" + p.slug, params), { "200": (r) => r.status === 200 });
19  });
20}

05Running, reading results and CI

Run k6 run script.js locally or in a container. At the end, k6 prints a summary: request rate, latency percentiles, error rate, data transferred and whether each threshold passed. Look at p95 and p99, not averages, because averages hide the slow tail that users notice. For trends and correlation with server metrics, stream results to Prometheus (remote write) or Grafana Cloud k6 and view them next to CPU, database and queue dashboards. In CI, run a short smoke or average-load test on every release against staging, and keep longer stress and soak tests on a schedule. Never load test production or a third-party API without explicit permission and a plan.

1# Local run with an environment variable
2k6 run -e BASE_URL=https://staging.example.com script.js
3 
4# Docker, no local install
5docker run --rm -i grafana/k6 run - <script.js
6 
7# Stream metrics to Prometheus remote write
8K6_PROMETHEUS_RW_SERVER_URL=http://localhost:9090/api/v1/write \
9  k6 run -o experimental-prometheus-rw script.js

06Little's law and sizing a test

Little's law links three numbers: concurrency = throughput × time in system. If you need 200 requests per second and a request takes 0.25 seconds, the system holds about 50 requests in flight. For k6 arrival-rate tests, the VUs needed ≈ rate × iteration duration (including sleeps), so a 2-second journey at 50 iterations per second needs about 100 VUs; set maxVUs with headroom. The same law explains server limits: a PHP-FPM pool of 40 workers with 200 ms requests caps out near 200 requests per second, and anything above that queues. If latency jumps while throughput flattens, you have hit a concurrency limit somewhere: worker pool, database connections or a lock.

07Finding the bottleneck during a test

k6 tells you that something is slow; server metrics tell you why. Watch, in order: application CPU and worker saturation, database CPU, slow query log and connections, cache hit ratio, queue depth, and external API latency. Use the USE method (utilisation, saturation, errors) for each resource. Tag requests in k6 by endpoint name, so URLs with IDs are grouped (use the name tag), and correlate the slowest endpoints with traces in your APM. Fix one bottleneck at a time and rerun the same test; the next bottleneck usually appears immediately. Keep a results log with the commit, configuration and key numbers for each run, so you can compare honestly.

1// Group dynamic URLs under one metric name
2http.get(BASE + "/api/products/" + id, { tags: { name: "GET /api/products/:id" } });
3 
4// Custom metric for a business step
5import { Trend } from "k6/metrics";
6const checkoutTime = new Trend("checkout_duration", true);
7checkoutTime.add(res.timings.duration);

08Coordinated omission and generator limits

Coordinated omission happens when the load generator waits for slow responses before sending the next request, so it sends fewer requests exactly when the system is struggling, and the measured latency looks better than reality. Closed-model executors suffer from it by design. Arrival-rate executors avoid most of it by starting iterations on schedule, but if they run out of VUs, k6 reports dropped_iterations, which you must treat as a failure signal. Also watch the generator: if its CPU is above roughly 80%, timings become unreliable. For large tests, distribute load across several machines with the k6 Operator on Kubernetes or Grafana Cloud k6, and generate load from the same region as users.

09Testing beyond HTTP: WebSockets, gRPC and extensions

k6 has built-in modules for HTTP/1.1 and HTTP/2, WebSockets, gRPC and the browser, and extensions (built with xk6, and in newer versions resolved automatically for official ones) add protocols such as Kafka, SQL or Redis. This lets you test the parts of a system that HTTP cannot reach: a WebSocket chat under thousands of connections, a gRPC service mesh, or a queue consumer's throughput. Treat these tests like the HTTP ones: realistic message rates, thresholds on latency and errors, and server-side monitoring. For event-driven systems, measure end-to-end time from publish to effect, not only the publish call.