k6: Zero to Hero

Load testing as code. k6 lets you write performance tests in JavaScript, run thousands of virtual users from a single lightweight binary, and gate releases on hard thresholds tied to your SLOs. You'll install k6, write your first test, shape realistic load profiles, assert on latency and error budgets, parameterize data, and wire it into CI. Hands-on throughout.

The journey:

1. Why load testing (and why k6)
2. Install k6
3. Your first test
4. Virtual users, iterations, and duration
5. Checks — assert on responses
6. Thresholds — pass/fail gates for SLOs
7. Load profiles — smoke, load, stress, spike, soak
8. Metrics — built-in and custom
9. Parameterizing test data
10. k6 in CI
11. Production practices

---

Prerequisites

⚠️ Only load-test systems you own or have written permission to test. A stress test is indistinguishable from a denial-of-service attack. Never point k6 at third-party production without authorization.

---

Part 1 — Why load testing

Functional tests answer "does it work?". Load tests answer "does it still work at 500 requests/second, and how does it fail?". You're hunting for the point where latency spikes, error rates climb, or a resource saturates — before your users find it.

k6 stands out because:

• Tests are code — versioned, reviewed, and reusable, not clicks in a GUI.
• One efficient binary — written in Go, it drives huge concurrency from modest hardware; the test script is JavaScript.
• Built for CI/CD — first-class thresholds give a clean exit code to gate a pipeline.
• Goal-oriented — you assert on p95 latency and error rate, not just eyeball a graph.

The four questions a load test answers: How fast? How many? How does it degrade? When does it break?

---

Part 2 — Install k6

# macOS
brew install k6

# Debian/Ubuntu
sudo gpg -k
sudo gpg --no-default-keyring --keyring /usr/share/keyrings/k6-archive-keyring.gpg \
  --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys C5AD17C747E3415A3642D57D77C6C491D6AC1D69
echo "deb [signed-by=/usr/share/keyrings/k6-archive-keyring.gpg] https://dl.k6.io/deb stable main" \
  | sudo tee /etc/apt/sources.list.d/k6.list
sudo apt-get update && sudo apt-get install k6

# Docker
docker run --rm -i grafana/k6 run - <script.js

Confirm it works:

k6 version

---

Part 3 — Your first test

Every k6 script exports a default function — the code each virtual user (VU) runs, over and over, for the duration of the test.

// script.js
import http from 'k6/http'
import { sleep } from 'k6'

export default function () {
  http.get('https://test.k6.io')
  sleep(1) // think time — don't hammer without pause
}

Run it:

k6 run script.js

You get a summary: request count, requests/second, and the all-important http_req_duration (with avg, min, med, p90, p95, max). That p95 is usually what your SLO is written against.

---

Part 4 — Virtual users, iterations, and duration

A VU is a concurrent, parallel user looping your default function. Control the load with options:

export const options = {
  vus: 10,          // 10 concurrent virtual users
  duration: '30s',  // for 30 seconds
}

Or run a fixed number of iterations instead of a duration:

export const options = { vus: 5, iterations: 100 } // 100 total iterations, shared across 5 VUs

Flags override options, which is handy for quick sweeps: k6 run --vus 50 --duration 1m script.js.

💡 VUs ≠ requests/second. Throughput depends on how long each iteration takes. 10 VUs where each iteration takes 200 ms yields ~50 req/s; if the server slows down, throughput drops even though VUs stay fixed. To pin a request rate, use the constant-arrival-rate executor (Part 7).

---

Part 5 — Checks — assert on responses

A check validates a response. Unlike a failed assertion in unit tests, a failed check does not stop the test — it's recorded as a rate you can inspect and threshold on. That's what you want under load: keep going, measure the failure rate.

import http from 'k6/http'
import { check } from 'k6'

export default function () {
  const res = http.get('https://test.k6.io')
  check(res, {
    'status is 200': (r) => r.status === 200,
    'body has title': (r) => r.body.includes('Collection'),
    'fast enough (<500ms)': (r) => r.timings.duration < 500,
  })
}

The summary shows the pass rate for each check. Group related requests with group() to organize the output by user journey.

---

Part 6 — Thresholds — pass/fail gates for SLOs

Thresholds are the feature that makes k6 a CI gate. If a threshold is breached, k6 run exits non-zero and your pipeline fails. Express your SLOs directly:

export const options = {
  vus: 20,
  duration: '1m',
  thresholds: {
    http_req_duration: ['p(95)<500', 'p(99)<1000'], // 95% under 500ms, 99% under 1s
    http_req_failed: ['rate<0.01'],                  // error rate under 1%
    checks: ['rate>0.99'],                           // 99%+ of checks pass
  },
}

You can also abort early to save time when things are clearly broken:

thresholds: {
  http_req_failed: [{ threshold: 'rate<0.05', abortOnFail: true, delayAbortEval: '10s' }],
}

---

Part 7 — Load profiles — smoke, load, stress, spike, soak

Real tests ramp load rather than slamming it on. Use stages (or the richer scenarios/executors) to shape the profile.

export const options = {
  stages: [
    { duration: '2m', target: 100 }, // ramp up to 100 VUs
    { duration: '5m', target: 100 }, // hold (steady state)
    { duration: '2m', target: 0 },   // ramp down
  ],
}

The standard test types, each answering a different question:

To hold a request rate regardless of latency, use an arrival-rate executor:

export const options = {
  scenarios: {
    steady: {
      executor: 'constant-arrival-rate',
      rate: 200, timeUnit: '1s',   // 200 iterations/sec
      duration: '5m',
      preAllocatedVUs: 50, maxVUs: 200,
    },
  },
}

---

Part 8 — Metrics — built-in and custom

k6 collects built-in metrics automatically. The ones you'll live in:

Add custom metrics to measure business-level things:

import { Trend, Counter, Rate } from 'k6/metrics'

const loginTime = new Trend('login_time', true)
const errors = new Rate('business_errors')

export default function () {
  const res = http.post('https://api.example.com/login', /* … */)
  loginTime.add(res.timings.duration)
  errors.add(res.status !== 200)
}

Trend (timings/distributions), Counter (running totals), Rate (percentage true), and Gauge (last value) cover almost everything.

---

Part 9 — Parameterizing test data

Hitting the same URL with the same body isn't realistic (and may just test your cache). Load data once and share it across all VUs with SharedArray — it parses the file a single time instead of once per VU:

import { SharedArray } from 'k6/data'
import http from 'k6/http'

const users = new SharedArray('users', () => JSON.parse(open('./users.json')))

export default function () {
  const u = users[Math.floor(Math.random() * users.length)]
  http.post('https://api.example.com/login', JSON.stringify(u), {
    headers: { 'Content-Type': 'application/json' },
  })
}

Pass secrets and config via environment variables, never hard-coded: k6 run -e BASE_URL=https://staging.example.com script.js, read with __ENV.BASE_URL.

---

Part 10 — k6 in CI

Because a breached threshold returns a non-zero exit code, wiring k6 into a pipeline is trivial:

# .github/workflows/load-test.yml
name: Load test
on: [workflow_dispatch]
jobs:
  k6:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: grafana/setup-k6-action@v1
      - run: k6 run --quiet tests/load.js
        env:
          BASE_URL: ${{ secrets.STAGING_URL }}

Run smoke tests on every PR (fast, catches broken scripts and gross regressions); run the heavier load/stress/soak profiles on a schedule or manual trigger against a staging environment that mirrors production.

---

Part 11 — Production practices

• Test staging, not production — unless you have a deliberate, well-scoped production performance test with stakeholders informed.
• Write thresholds first. A test with no thresholds is a graph nobody reads. Encode the SLO.
• One scenario, one question. Keep smoke/load/stress as separate, named configs.
• Include think time (sleep) to model real users; back-to-back requests over-estimate load and under-estimate concurrency.
• Watch the load generator too — if the machine running k6 is CPU-bound, your numbers are wrong. Scale out or use k6 Cloud/distributed mode.
• Correlate with server metrics — pair k6's client-side view with Prometheus/Grafana on the server to find which resource saturates.

Common mistakes

Practice exercises

1. Smoke → load: Write a 1-VU smoke test, then convert it to a 3-stage load test ramping to 50 VUs with a p(95)<800 threshold.
2. Break it: Turn that into a stress test that ramps past the breaking point and note where http_req_failed first crosses 1%.
3. Realistic data: Add a SharedArray of users and randomize each iteration's login payload.
4. Custom metric: Add a Trend for a checkout endpoint and threshold its p95 separately from the global one.
5. CI gate: Add a GitHub Actions job that runs the smoke test on every PR and fails on a breached threshold.

---

You can now write realistic load tests as code, express SLOs as enforceable thresholds, shape smoke/load/stress/spike/soak profiles, and gate releases on performance in CI. Pair this with the Prometheus and Grafana tutorials to watch the server side while k6 drives the load.