k6 Basics: Virtual Users, Groups, Checks, and Thresholds

1# macOS
2brew install k6
3
4# Windows
5choco install k6
6
7# Linux (Debian/Ubuntu)
8sudo gpg --no-default-keyring \
9  --keyring /usr/share/keyrings/k6-archive-keyring.gpg \
10  --keyserver hkp://keyserver.ubuntu.com:80 \
11  --recv-keys C5AD17C747E3415A3642D57D77C6C491D6AC1D69
12echo 'deb [signed-by=/usr/share/keyrings/k6-archive-keyring.gpg] https://dl.k6.io/deb stable main' \
13  | sudo tee /etc/apt/sources.list.d/k6.list
14sudo apt-get update && sudo apt-get install k6
15
16# Docker — no install required
17docker run --rm -i grafana/k6 run - < script.js
18
19k6 version  # Verify: k6 v0.54.0 (go1.22.0, linux/amd64)

1project/
2├── src/
3├── tests/
4│   ├── unit/
5│   ├── e2e/
6│   └── perf/
7│       ├── scenarios/      # smoke.js, load.js, stress.js
8│       ├── helpers/        # shared auth, data helpers
9│       └── data/           # CSV test data files
10└── package.json

1{
2  "scripts": {
3    "perf:smoke":  "k6 run tests/perf/scenarios/smoke.js",
4    "perf:load":   "k6 run tests/perf/scenarios/load.js",
5    "perf:stress": "k6 run tests/perf/scenarios/stress.js"
6  }
7}

1import http from 'k6/http';
2import { check, sleep } from 'k6';
3
4// 1. OPTIONS — k6 reads this before starting the test
5export const options = {
6  vus: 10,
7  duration: '30s',
8  // OR stages mode for ramp up/down:
9  // stages: [
10  //   { duration: '2m', target: 20 },
11  //   { duration: '5m', target: 20 },
12  //   { duration: '1m', target: 0 },
13  // ],
14  thresholds: {
15    http_req_duration: ['p(95)<500'],
16    http_req_failed:   ['rate<0.01'],
17  },
18};
19
20// 2. SETUP — runs once before VUs start; return value is passed to default()
21export function setup() {
22  const res = http.post('https://api.example.com/auth/token', {
23    username: 'perf-test-user',
24    password: __ENV.PERF_PASSWORD,
25  });
26  return { token: res.json('access_token') };
27}
28
29// 3. DEFAULT FUNCTION — each VU calls this repeatedly during the test
30export default function (data) {
31  const headers = { Authorization: `Bearer ${data.token}` };
32  const res = http.get('https://api.example.com/dashboard', { headers });
33  check(res, {
34    'status 200': (r) => r.status === 200,
35    'has user': (r) => Boolean(r.json('user')),
36  });
37  sleep(1); // model think time between requests
38}
39
40// 4. TEARDOWN — runs once after all VUs finish
41export function teardown(data) {
42  http.del('https://api.example.com/auth/sessions', null, {
43    headers: { Authorization: `Bearer ${data.token}` },
44  });
45}

1import http from 'k6/http';
2import { check, group, sleep } from 'k6';
3
4export const options = { vus: 20, duration: '1m' };
5
6export default function () {
7  group('User authentication', () => {
8    const loginRes = http.post(
9      'https://api.example.com/auth/login',
10      JSON.stringify({ email: '[email protected]', password: 'Pass123!' }),
11      { headers: { 'Content-Type': 'application/json' } }
12    );
13
14    const loginOk = check(loginRes, {
15      'login status 200': (r) => r.status === 200,
16      'has access token': (r) => typeof r.json('accessToken') === 'string',
17      'token not empty': (r) => r.json('accessToken').length > 0,
18    });
19
20    if (!loginOk) return; // stop if login failed
21
22    const token = loginRes.json('accessToken');
23    const h = { Authorization: `Bearer ${token}` };
24
25    sleep(0.5);
26
27    group('Dashboard fetch', () => {
28      const dashRes = http.get('https://api.example.com/dashboard', { headers: h });
29      check(dashRes, {
30        'dashboard 200': (r) => r.status === 200,
31        'has activity': (r) => Array.isArray(r.json('recentActivity')),
32        'under 300ms': (r) => r.timings.duration < 300,
33      });
34    });
35  });
36
37  sleep(1);
38}
39// Summary shows:
40// group::User authentication....  ✓ 2840/2880 (98.6%)
41// group::Dashboard fetch.........  ✓ 2790/2840 (98.2%)

1export const options = {
2  vus: 50,
3  duration: '10m',
4  thresholds: {
5    // Multiple conditions on built-in metrics
6    http_req_duration: [
7      'p(95)<500',
8      'p(99)<1500',
9      'avg<300',
10      'max<5000',
11    ],
12    http_req_failed: ['rate<0.001'],
13    http_reqs: ['count>1000'],  // verify load was actually sent
14
15    // Per-endpoint thresholds via tags
16    'http_req_duration{name:login}':  ['p(95)<300'],
17    'http_req_duration{name:search}': ['p(95)<800'],
18
19    // Abort early if errors spike — system is failing
20    http_req_failed: [{
21      threshold: 'rate<0.05',
22      abortOnFail: true,
23      delayAbortEval: '30s',  // wait 30s to confirm it is not transient
24    }],
25  },
26};

1- name: Run k6 load test
2  run: k6 run tests/perf/load.js --out json=results.json
3# k6 exits code 99 if any threshold fails
4# GitHub Actions marks the step failed automatically
5# Add: if: always() on result upload to capture failure artifacts

1  scenarios: (100.00%) 1 scenario, 50 max VUs, 10m30s max duration
2           * default: 50 looping VUs for 10m0s
3
4✓ status 200           ← check pass rate
5✓ has user field
6
7     checks.........................: 99.85% ✓ 14977  ✗ 22
8     data_received..................: 45 MB  75 kB/s
9     data_sent......................: 3.2 MB 5.3 kB/s
10     http_req_blocked...............: avg=1.21ms  min=0s    max=312ms
11     http_req_connecting............: avg=0.87ms  min=0s    max=311ms
12   ✓ http_req_duration..............: avg=187ms   min=12ms  max=2.1s   p(90)=380ms  p(95)=450ms
13   ✗ http_req_failed................: 0.14%  ✗ threshold rate<0.001 breached
14     http_reqs......................: 15000  25/s
15     iteration_duration.............: avg=1.19s   min=1.01s max=3.12s
16     vus............................: 50     min=50    max=50
17
18INFO thresholds on metrics 'http_req_failed' have been crossed
19FAIL  (exit code 99)