$devvkit learn --librarie k6-guide

k6 Guide

[load-testing][performance][javascript][grafana]

Performance & Profiling

Install

# macOS
brew install k6
# Windows
winget install k6
# Linux
sudo apt install k6  # or download from grafana.com

k6 is built for developers who write tests in JavaScript/TypeScript. Unlike GUI load testers, your test scripts live in version control, run in CI, and produce metrics (requests/s, latency p95/p99, error rate) that feed into Grafana dashboards.

Virtual users (VUs) execute your script concurrently. Use `__VU` and `__ITER` built-in variables to vary behavior per user. The `check()` API asserts responses, `trend()` tracks custom timings, and `thresholds()` automatically fail the test if SLAs are breached.

k6 outputs real-time metrics to stdout, JSON, or Prometheus. Combine with Grafana Cloud or `k6 new` to scaffold tests. GUI alternatives: Grafana k6 Cloud UI, Postman collection runner, or Apache JMeter for non-developers.

Setup

Run test— Execute a k6 script.

k6 run script.js
k6 run --vus 10 --duration 30s script.js
k6 run --vus 100 --duration 5m --rps 500 script.js

Scripting

Basic script— GET request load test.

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

export default function () {
  const res = http.get('https://api.example.com/users')
  sleep(1)
}

Stages ramp— Gradually ramp VUs.

export const options = {
  stages: [
    { duration: '30s', target: 20 },   // Ramp up
    { duration: '1m', target: 20 },    // Stay
    { duration: '30s', target: 0 },    // Ramp down
  ],
}

Checks & Thresholds

Checks— Assert response quality.

import { check } from 'k6'

const res = http.get('https://api.example.com/users')
check(res, {
  'status is 200': (r) => r.status === 200,
  'response time < 200ms': (r) => r.timings.duration < 200,
  'body has users': (r) => r.body.includes('users'),
})

Thresholds— Fail test on SLA breach.

export const options = {
  thresholds: {
    http_req_duration: ['p(95)<500'],      // 95% under 500ms
    http_req_failed: ['rate<0.01'],          // <1% errors
    'checks{type:login}': ['rate>0.95'],    // login check passes
  },
}

Scenarios

Scenarios— Multiple load patterns.

export const options = {
  scenarios: {
    smoke: { executor: 'constant-vus', vus: 1, duration: '1m' },
    load: {
      executor: 'ramping-arrival-rate',
      preAllocatedVUs: 50,
      startRate: 10,
      stages: [
        { duration: '2m', target: 100 },
        { duration: '5m', target: 100 },
      ],
    },
  },
}

CI Integration

CI integration— Fail pipeline on thresholds.

k6 run --out json=results.json script.js
# Parse results, fail if thresholds breached
k6 run --summary-trend-stats="avg,p(95),p(99)" script.js
# GitHub Actions:
# - run: k6 run script.js
#   env:
#     K6_OUT: cloud  # stream to Grafana Cloud

Advanced

Custom metrics— Track business KPIs.

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

const loginDuration = new Trend('login_duration')
const loginFailRate = new Rate('login_fail_rate')

export default function () {
  const res = http.post('https://api.example.com/login', { email: 'a@b.com', pass: 'x' })
  loginDuration.add(res.timings.duration)
  loginFailRate.add(res.status !== 200)
}