k6-load-testing
k6 tests are .js files with a default-exported function that runs
once per virtual user (VU) per iteration (per k6-running).
This skill covers the load-testing workflow; k6's browser, synthetic
monitoring, and chaos modes share the same script structure but are
out of scope here.
When to use
- The project ships HTTP, WebSocket, or gRPC services that need
performance testing.
- The team prefers JavaScript authoring (vs. JMeter's XML, Gatling's
Scala/Java, or Locust's Python).
- A CI gate is needed on p(95) latency + error rate - k6's
thresholds are designed for this.
- The team is on Grafana Cloud (k6 integrates natively) or wants a
self-hosted CLI-only flow.
If the team is already deep in JMeter, the migration cost is non-
trivial - evaluate jmeter-load-testing
in place. For Python / Locust shops and JVM / Gatling teams, see the
Gatling and Locust references in load-testing-overview.
Install
Install via k6 installation
(brew, apt/yum, choco, Docker). Pin a specific k6 version in CI
rather than "latest".
Authoring
Minimal script
import http from 'k6/http';
import { check, sleep } from 'k6';
export default function () {
const res = http.get('https://quickpizza.grafana.com/');
check(res, { 'status was 200': (r) => r.status == 200 });
sleep(1);
}
(Per k6-running.)
The default-exported function runs once per virtual-user iteration.
check() is a non-failing assertion that contributes to the
checks metric; sleep() simulates think-time between requests.
Options block - stages
Per k6-running, the options export controls the run:
export const options = {
stages: [
{ duration: '30s', target: 20 }, // ramp up to 20 VUs over 30s
{ duration: '1m30s', target: 10 }, // hold ~10 VUs for 90s (gradual scale-down)
{ duration: '20s', target: 0 }, // ramp down to 0
],
};
Three canonical shape patterns:
| Pattern | Stages |
|---|
| Smoke test | One stage, { duration: '1m', target: 1 } - sanity check. |
| Average load test | Ramp up → plateau → ramp down (the example above). |
| Stress test | Ramp past expected peak; observe where the system breaks. |
| Spike test | Sudden ramp to high VU; back to normal; verify recovery. |
| Soak test | Long plateau (hours); verify no resource leaks over time. |
Options block - thresholds
Per k6-thresholds, thresholds are "the pass/fail
criteria that you define for your test metrics" - the canonical CI
gate:
export const options = {
thresholds: {
http_req_duration: ['p(95)<500'], // 95% of requests under 500ms
http_req_failed: ['rate<0.01'], // <1% errors
checks: ['rate>0.99'], // >99% of checks pass
},
};
(Per k6-thresholds.)
The threshold expression syntax is <aggregation_method> <operator> <value>. Available aggregation methods per metric type:
| Metric type | Methods |
|---|
| Trend | avg, min, max, med, p(N) (percentile, ms) |
| Counter | count, rate |
| Rate | rate |
| Gauge | value |
A test that fails any threshold exits non-zero - the canonical CI
gate signal.
abortOnFail
For long-running stress / soak tests, abort early if a threshold is
already violated (k6-thresholds):
thresholds: {
http_req_duration: [
{ threshold: 'p(95)<500', abortOnFail: true, delayAbortEval: '10s' },
],
},
delayAbortEval postpones the abort decision to let metrics
accumulate before evaluating; without it, a 1-second test could
abort on a single slow request.
Running
Ad-hoc (no options block needed)
k6 run --vus 10 --duration 30s script.js
(Per k6-running.)
--vus overrides the script's options; --duration runs for a
fixed time without ramps.
Standard run
k6 run script.js
options block in the script controls everything; the CLI is
hands-off. Preferred for CI.
Useful flags
| Flag | Purpose |
|---|
--out json=<file> | Stream raw metrics to a JSON file. |
--summary-export=<file> | Write the end-of-test summary to JSON. |
--quiet | Silence the live progress UI (CI noise). |
--http-debug=full | Verbose HTTP debug for triage runs. |
--env KEY=VAL | Inject env vars accessible via __ENV.KEY. |
--config <file> | Externalize the options block to a JSON file. |
Parsing results
The end-of-run summary prints to stdout; --summary-export writes
the same data as JSON for downstream consumption:
{
"metrics": {
"http_req_duration": {
"values": { "p(95)": 432.1, "avg": 198.3, ... },
"thresholds": { "p(95)<500": { "ok": true } }
},
"http_req_failed": {
"values": { "rate": 0.004, "passes": 996, "fails": 4 },
"thresholds": { "rate<0.01": { "ok": true } }
}
}
}
Pipe to jq for a quick gate report:
jq -r '
.metrics
| to_entries[]
| select(.value.thresholds)
| .key + ": " + (.value.thresholds | to_entries | map("\(.key) → \(if .value.ok then "PASS" else "FAIL" end)") | join(", "))
' summary.json
CI integration
Full GitHub Actions workflow - apt install, PR + nightly triggers,
summary upload via if: always() - in
references/ci-integration.md. A
failing threshold causes k6 run to exit non-zero, failing the job.
Interpreting latency distributions
Passing a p95 threshold is necessary but not sufficient. The full
interpretation workflow - expanding summaryTrendStats to p99/p99.9, the
tail ratio (p99/p50) as a spread signal, bimodal-distribution heuristics,
sub-metric cross-checks (http_req_waiting / http_req_blocked),
coordinated omission and HdrHistogram correction, and constant-vus vs
constant-arrival-rate executor semantics - is in
references/latency-percentiles.md.
Anti-patterns
| Anti-pattern | Why it fails | Fix |
|---|
| Hard-coded URLs / tokens in script | Scripts bind to one environment; secrets leak. | Read from __ENV.API_BASE_URL, __ENV.API_TOKEN. |
--vus 1000 --duration 1h from a developer laptop | Laptop resource contention; client-side bottlenecks corrupt metrics. | Run from a CI runner / dedicated load generator; never from a dev box for serious numbers. |
Threshold p(95)<10000 | Practically meaningless - passes any sane API. Hides regressions. | Set thresholds at meaningful budgets (500ms, 1s) tied to NFRs from the non-functional-requirement-extractor. |
| Soak tests in PR CI | Multi-hour PR CI; team disables. | Soak tests are scheduled-only; PRs run smoke / average load. |
Missing sleep() between requests | Hammering at full VU rate generates synthetic numbers; doesn't model real users. | Include sleep(1) or randomized think-time after each iteration. |
Asserting only http_req_failed rate | A 30-second response that succeeds passes the rate gate but breaks UX. | Always pair with http_req_duration percentile thresholds. |
Limitations
- Single-machine VU limits. A single k6 instance saturates one
machine's outbound CPU / network - typically 20-50k concurrent VUs
for HTTP. For higher loads, distribute via Grafana Cloud or k6
Operator on Kubernetes.
- No native browser execution. The
k6/browser module covers it
but adds Chromium overhead; for browser-driven perf testing,
consider lighthouse-perf instead.
- JS sandbox limits. k6 uses goja (Go-based ES5+/some-ES6),
not Node.js. npm packages with native deps don't work; pure-JS
packages do. Use
k6 archive to bundle.
References
- k6-overview - main docs landing page.
- k6-running - basic script + options + stages + ad-hoc
flags.
- k6-thresholds - threshold syntax, aggregation methods,
abortOnFail / delayAbortEval.
jmeter-load-testing and the Gatling / Locust references in
load-testing-overview - alternatives by language stack.- references/latency-percentiles.md -
interpreting the latency distributions this skill's runs produce.
perf-budget-gate - downstream
gate that aggregates k6 / lighthouse / load-runner verdicts.