Grafana k6 is a modern open-source load testing tool scripted in JavaScript. A developer-friendly CLI, powerful metrics, and easy CI/CD integration let you stand up performance tests quickly.
k6 Practical Examples
Example code for Load, Stress, and Spike scenarios, Thresholds, and CI/CD integration.
View practical examples →Grafana k6 is an open-source performance testing tool in which developers write load test scripts in JavaScript. It is implemented in Go and can simulate tens of thousands of virtual users (VUs) on a single machine.
| Feature | Description |
|---|---|
| JavaScript scripts | Write test scenarios in familiar JS |
| High performance | Go-based engine, low resource usage |
| CLI-first | Fits naturally into CI/CD pipelines |
| Rich metrics | Automatically collects response time, error rate, throughput, and more |
brew install k6sudo 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 k6docker pull grafana/k6
docker run --rm -i grafana/k6 run - < script.jschoco install k6import http from 'k6/http';
import { sleep, check } from 'k6';
export const options = {
vus: 10, // number of virtual users
duration: '30s', // test duration
};
export default function () {
const res = http.get('https://httpbin.test.k6.io/');
check(res, {
'status is 200': (r) => r.status === 200,
'response time < 500ms': (r) => r.timings.duration < 500,
});
sleep(1);
}k6 run script.jshttpbin.test.k6.io is the official k6 test server. Replace it with your own server address.
A VU (Virtual User) is a virtual thread that mimics a real user. Each VU runs the script independently and keeps its own cookies and session.
The number of times each VU runs export default function(). The test ends when duration elapses or iterations is reached.
| Metric | Description |
|---|---|
http_req_duration | Total response time of a request |
http_req_failed | Failure rate (4xx, 5xx) |
vus | Number of currently active VUs |
iterations | Number of completed iterations |
Checks system performance under normal or expected peak load.
export const options = {
stages: [
{ duration: '2m', target: 100 }, // ramp up to 100 VUs
{ duration: '5m', target: 100 }, // hold at 100 VUs
{ duration: '2m', target: 0 }, // ramp down to 0
],
};Increases the load gradually to find the breaking point of the system.
export const options = {
stages: [
{ duration: '2m', target: 100 },
{ duration: '5m', target: 100 },
{ duration: '2m', target: 200 },
{ duration: '5m', target: 200 },
{ duration: '2m', target: 300 },
{ duration: '5m', target: 300 },
{ duration: '10m', target: 0 },
],
};Simulates a sudden surge in traffic.
export const options = {
stages: [
{ duration: '10s', target: 100 },
{ duration: '1m', target: 100 },
{ duration: '10s', target: 1400 }, // spike!
{ duration: '3m', target: 1400 },
{ duration: '10s', target: 100 },
{ duration: '3m', target: 100 },
{ duration: '10s', target: 0 },
],
};import http from 'k6/http';
import { check, sleep } from 'k6';
export const options = {
thresholds: {
'http_req_duration': ['p(95)<500'], // 95%ile < 500ms
'http_req_failed': ['rate<0.01'], // error rate below 1%
'checks': ['rate>0.99'], // check success rate of 99% or higher
},
};
export default function () {
const res = http.get('https://your-api.com/health');
check(res, {
'status 200': (r) => r.status === 200,
'body not empty': (r) => r.body.length > 0,
'fast response': (r) => r.timings.duration < 200,
});
sleep(1);
}If a Threshold is not met, k6 exits with exit code 99. CI/CD can treat that as a failure.
import http from 'k6/http';
export default function () {
// GET
http.get('https://api.example.com/users');
// POST (JSON)
const payload = JSON.stringify({ username: 'user1', password: 'secret' });
const params = { headers: { 'Content-Type': 'application/json' } };
const loginRes = http.post('https://api.example.com/login', payload, params);
// Authorization header
const token = loginRes.json('token');
http.get('https://api.example.com/profile', {
headers: { Authorization: `Bearer ${token}` },
});
}# JSON output
k6 run --out json=result.json script.js
# CSV output
k6 run --out csv=result.csv script.js
# Stream to Grafana Cloud
k6 run --out cloud script.jsname: Load Test
on: [push]
jobs:
k6-load-test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: grafana/setup-k6-action@v1
- run: k6 run scripts/load-test.js
env:
K6_CLOUD_TOKEN: ${{ secrets.K6_CLOUD_TOKEN }}