k6: VUs, Scenarios, Thresholds and HTTP Load Testing Reference Guide

# Install — pick one
brew install k6                                # macOS
choco install k6                               # Windows
docker pull grafana/k6                         # container
# Linux: see https://k6.io/docs/get-started/installation/ (apt / dnf repo)

# Hello-world script
cat > test.js <<'EOF'
import http from "k6/http";
import { sleep, check } from "k6";

export const options = { vus: 10, duration: "30s" };

export default function () {
  const res = http.get("https://test.k6.io");
  check(res, { "status is 200": (r) => r.status === 200 });
  sleep(1);
}
EOF

# Run
k6 run test.js                                 # local
k6 run --vus 50 --duration 1m test.js          # CLI overrides
k6 run -e API_URL=https://stg.example.com t.js # env vars
k6 cloud test.js                               # run on Grafana Cloud k6 (paid)

# Output / observability
k6 run --out json=run.json test.js
k6 run --out csv=metrics.csv test.js
k6 run --out experimental-prometheus-rw test.js
k6 run --summary-export=summary.json test.js

# Docker run (mount your script)
docker run --rm -i grafana/k6 run - < test.js

// test.js — multiple scenarios, each with its own executor
import http from "k6/http";

export const options = {
  // Per-scenario tagging propagates to every metric
  scenarios: {
    smoke: {
      executor: "constant-vus",
      vus: 1,
      duration: "1m",
      exec: "browse",                        // function below
      tags: { kind: "smoke" },
    },
    ramp: {
      executor: "ramping-vus",
      startVUs: 0,
      stages: [
        { duration: "30s", target: 50 },     // ramp up
        { duration: "2m",  target: 50 },     // hold
        { duration: "30s", target: 0  },     // ramp down
      ],
      gracefulRampDown: "10s",
      exec: "browse",
    },
    spike: {
      executor: "ramping-arrival-rate",      // req/s, not VUs
      startRate: 10,
      timeUnit: "1s",
      preAllocatedVUs: 100,
      maxVUs: 500,
      stages: [
        { duration: "10s", target: 500 },    // 500 req/s
        { duration: "30s", target: 500 },
        { duration: "10s", target: 10  },
      ],
      exec: "checkout",
    },
  },
  thresholds: {
    "http_req_failed{kind:smoke}": ["rate<0.01"],
    "http_req_duration{scenario:ramp}": ["p(95)<400"],
  },
};

export function browse()   { http.get("https://stg.example.com/items"); }
export function checkout() { http.post("https://stg.example.com/orders", "{}"); }

// Thresholds: SLOs that fail the run if violated.
import http from "k6/http";
import { Trend, Rate, Counter } from "k6/metrics";

const loginLatency = new Trend("login_latency", true);   // true = time-typed
const errorRate    = new Rate("custom_errors");
const requests     = new Counter("requests_total");

export const options = {
  vus: 20,
  duration: "1m",
  thresholds: {
    // Built-in metrics
    http_req_failed:   ["rate<0.01"],                 // <1% failures overall
    http_req_duration: ["p(95)<300", "p(99)<800"],    // latency SLO

    // Custom metric — fail the run AND abort early
    login_latency: [{ threshold: "p(95)<200", abortOnFail: true, delayAbortEval: "30s" }],

    // Tag-scoped threshold
    "http_req_duration{name:GET /api/items}": ["avg<150"],

    // Counter target
    "requests_total": ["count>1000"],
  },
};

export default function () {
  const t0 = Date.now();
  const res = http.get("https://stg.example.com/login", { tags: { name: "GET /api/login" } });
  loginLatency.add(Date.now() - t0);
  errorRate.add(res.status !== 200);
  requests.add(1);
}

// e2e.js — login → list → checkout, with grouping, checks, thresholds
import http from "k6/http";
import { group, check, sleep, fail } from "k6";
import { SharedArray } from "k6/data";

const users = new SharedArray("users", () => JSON.parse(open("./users.json"))); // one shared copy

export const options = {
  stages: [
    { duration: "30s", target: 25 },
    { duration: "2m",  target: 25 },
    { duration: "20s", target: 0  },
  ],
  thresholds: {
    http_req_failed:   ["rate<0.01"],
    http_req_duration: ["p(95)<500"],
    "checks{step:login}": ["rate>0.99"],
  },
};

const BASE = __ENV.API_URL || "https://stg.example.com";

export default function () {
  const u = users[__VU % users.length];
  let token;

  group("login", () => {
    const res = http.post(`${BASE}/api/login`, JSON.stringify(u), {
      headers: { "Content-Type": "application/json" },
      tags:    { step: "login" },
    });
    if (!check(res, { "200": (r) => r.status === 200 }, { step: "login" })) fail("login failed");
    token = res.json("token");
  });

  const auth = { headers: { Authorization: `Bearer ${token}` } };

  group("browse", () => {
    const r = http.get(`${BASE}/api/items`, auth);
    check(r, { "list ok": (r) => r.status === 200 && r.json().length > 0 });
  });

  group("checkout", () => {
    const r = http.post(`${BASE}/api/orders`, "{}", auth);
    check(r, { "created": (r) => r.status === 201 });
  });

  sleep(1);
}