k6 Load Testing Tutorial 2026: First Test in 15 Min

Last updated: June 29, 2026 · 12 min read · By Avinash Kamble, reviewed by Priyanka G.

The first time I ran a serious k6 load test in anger, it was 11 PM the night before a Black Friday freeze at a payments client. The team was convinced their checkout API could hold 2,000 RPS. k6 took twelve minutes to prove it folded at 740 — a single misconfigured DB connection pool. We shipped the fix at 2 AM, slept three hours, and the launch held. That's the kind of confidence a good load test buys you, and this guide is the playbook I wish I'd had that night.

This k6 load testing tutorial takes you from zero install to production-grade scenarios, thresholds, auth flows, Grafana Cloud, and CI/CD wiring. Pair it with our JMeter Tutorial, k6 vs JMeter Comparison, and Load Testing Tools Comparison.

Key takeaways

• k6 is JavaScript-scripted, Go-powered, and built for engineers — not GUIs.
• Scenarios + thresholds let you encode a release SLO directly into the test.
• One k6 instance comfortably drives 30k+ RPS; Grafana Cloud handles the rest.
• The biggest wins come from CI gating with thresholds, not one-off runs.
• Most teams fail load tests because of test data and ramp-up, not the tool.

k6 is an open-source load testing tool built by Grafana Labs. It scripts in JavaScript (ES2015+) and executes in a Go runtime, which is why a single mid-range laptop can sustain 30k+ requests per second — roughly 15–30× what an equivalent JMeter setup pushes. The official docs live at grafana.com/docs/k6, and the open spec it implements aligns with the W3C Web Performance Working Group metrics most observability stacks consume.

You'll see k6 used for three things in 2026: pre-release load gates in CI, capacity planning ahead of marketing pushes, and SRE-driven chaos and soak testing. If you're new to API-layer testing in general, skim our API Testing Tutorial first — k6 assumes you can already reason about endpoints, auth, and status codes.

macOS

brew install k6

Windows

winget install k6

Linux

sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys C5AD17C747E3415A
echo "deb https://dl.k6.io/deb stable main" | sudo tee /etc/apt/sources.list.d/k6.list
sudo apt-get update
sudo apt-get install k6

Verify:

k6 version
# k6 v0.50.0 (2026)

Pro tip — on CI runners, skip the OS install entirely and use the official Docker image (grafana/k6). It's ~40 MB, pins your k6 version per pipeline, and removes a class of "works on my laptop" Slack threads. I lost half a day once chasing a threshold regression that turned out to be a k6 minor-version bump on a self-hosted runner.

Create load-test.js:

import http from 'k6/http';
import { check, sleep } from 'k6';

export const options = {
  vus: 10,           // 10 virtual users
  duration: '30s',   // run for 30 seconds
};

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

  check(res, {
    'status is 200': (r) => r.status === 200,
    'response time < 500ms': (r) => r.timings.duration < 500,
  });

  sleep(1);  // simulate user pacing
}

Run:

k6 run load-test.js

You'll see real-time metrics as k6 runs. The two numbers that matter on the first read are http_req_duration p(95) (tail latency) and http_req_failed (error rate). Everything else is supporting evidence.

Scenarios let you model complex user patterns. Most production tests combine a baseline smoke check with a ramping load profile so the runtime mirrors a real launch:

export const options = {
  scenarios: {
    smoke: {
      executor: 'constant-vus',
      vus: 1,
      duration: '1m',
    },
    load: {
      executor: 'ramping-vus',
      stages: [
        { duration: '2m', target: 50 },
        { duration: '5m', target: 50 },
        { duration: '2m', target: 0 },
      ],
    },
  },
};

k6 executors — which one when

Picking the wrong executor is the #1 reason load tests lie. This is the cheat-sheet I keep pinned in our team wiki:

Set pass/fail criteria:

export const options = {
  thresholds: {
    http_req_duration: ['p(95)<500'],   // 95th percentile < 500ms
    http_req_failed: ['rate<0.01'],      // error rate < 1%
    http_reqs: ['count>1000'],          // at least 1000 requests
  },
};

If thresholds fail, k6 exits with non-zero status — perfect for CI/CD. See our CI/CD Pipeline Testing Tutorial. The trick most teams miss: write thresholds per scenario with tagged metrics (e.g. http_req_duration{scenario:checkout}) so a slow analytics call doesn't mask a fast checkout SLO breach.

// Check (continues test, tracks pass/fail rate)
check(res, {
  'status is 200': (r) => r.status === 200,
});

// Assertion (stops test on failure)
import { fail } from 'k6';
if (res.status !== 200) fail(`Expected 200, got ${res.status}`);

Use checks for monitoring; assertions for critical failures. In CI I almost always prefer checks + thresholds — a single 502 shouldn't abort a 30-minute soak run, but a 5% sustained error rate absolutely should fail the build.

import { SharedArray } from 'k6/data';

const users = new SharedArray('users', function () {
  return JSON.parse(open('./users.json'));
});

export default function () {
  const user = users[__VU % users.length];
  http.post('https://api.example.com/login', JSON.stringify(user));
}

Share data across VUs efficiently — one copy in memory, not one per VU. For 50k seed users that's the difference between a 200 MB and a 6 GB process. If your test data is sensitive, generate it on the fly with Faker inside setup() instead of shipping a JSON file alongside the test.

import http from 'k6/http';

export default function () {
  // 50% of requests to /users
  if (Math.random() < 0.5) {
    http.get('https://api.example.com/users');
  } else {
    // 50% to /products
    http.get('https://api.example.com/products');
  }
}

For realistic traffic, weight requests by what your production logs actually show — 70/20/10 reads/writes/searches is closer to most SaaS apps than an even split.

export function setup() {
  const loginRes = http.post('https://api.example.com/auth/login', {
    email: 'admin@example.com',
    password: 'Sup3rSecret!',
  });
  return { token: loginRes.json('token') };
}

export default function (data) {
  http.get('https://api.example.com/admin/users', {
    headers: { Authorization: `Bearer ${data.token}` },
  });
}

For deeper API patterns, see our API Testing Tutorial. If you're load-testing OAuth flows, mint tokens in setup() and reuse them — hammering your identity provider with 5k logins per minute almost always gets you rate-limited before the system-under-test does.

k6 cloud load-test.js

This runs in Grafana Cloud with distributed load generation across multiple regions, real-time dashboards, threshold-based alerts, and long-term trend analysis. The free tier covers most pre-release smoke runs; paid plans unlock multi-region and longer soak windows.

GitHub Actions

name: k6 Load Test
on: [pull_request]
jobs:
  load:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run k6
        uses: grafana/k6-action@v0.3.0
        with:
          filename: tests/load/smoke.js

Docker

docker run --rm -v $PWD:/scripts grafana/k6 run /scripts/load-test.js

See our GitHub Actions for Automation Testing guide for full pipeline patterns. For PR gating, run a tight 60-second smoke on every PR and the full ramp-up scenario on nightly main — most teams blow up their CI minutes by running 30-minute soaks per push.

Modular test scripts

// helpers/auth.js
export function login() {
    const res = http.post('https://api.example.com/auth/login',
        JSON.stringify({ email: 'admin@example.com', password: 'Sup3rSecret!' }));
    return res.json('token');
}

// load-test.js
import { login } from './helpers/auth.js';

export default function () {
    const token = login();
    http.get('https://api.example.com/admin/users', {
        headers: { Authorization: `Bearer ${token}` }
    });
}

Custom metrics

import { Trend, Counter } from 'k6/metrics';

const checkoutDuration = new Trend('checkout_duration');
const errorCount = new Counter('errors');

export default function () {
    const start = Date.now();
    const res = http.post('https://api.example.com/checkout', payload);
    checkoutDuration.add(Date.now() - start);
    if (res.status !== 200) errorCount.add(1);
}

Multiple scenarios in parallel

export const options = {
    scenarios: {
        browse: {
            executor: 'constant-vus',
            vus: 100,
            duration: '10m',
            exec: 'browse',
        },
        buy: {
            executor: 'ramping-arrival-rate',
            startRate: 1,
            timeUnit: '1s',
            preAllocatedVUs: 10,
            stages: [{ duration: '10m', target: 10 }],
            exec: 'buy',
        },
    },
};

Stress testing

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: '2m', target: 0 },
    ],
};

Soak testing

export const options = {
    stages: [
        { duration: '5m', target: 100 },
        { duration: '4h', target: 100 },
        { duration: '5m', target: 0 },
    ],
    thresholds: {
        'http_req_duration{scenario:soak}': ['p(99)<500'],
    },
};

I've shipped k6 on three production stacks — a payments API, a high-traffic media CMS, and an internal HR platform. Here's the honest scorecard.

If you're choosing between tools, our k6 vs JMeter comparison walks through the decision matrix with team-size and budget cuts.

Do

• Use scenarios for realistic user patterns
• Use thresholds for pass/fail criteria, tagged per scenario
• Use checks for monitoring, assertions for hard stops
• Use SharedArray for test data
• Run in CLI mode for local dev, Docker for CI
• Use Grafana Cloud for production-scale, multi-region testing

Don't

• Don't run heavy load from your laptop
• Don't add custom timers that fake performance
• Don't test against production unless you've coordinated with SRE
• Don't skip the ramp-up (test in real conditions)
• Don't ignore failed thresholds — fail the build

1 — No ramp-up

// BAD — sudden spike
vus: 1000,
duration: '1m',

// GOOD — gradual ramp-up
stages: [
  { duration: '1m', target: 100 },
  { duration: '5m', target: 100 },
  { duration: '1m', target: 0 },
],

2 — Testing in dev environment

Test in staging that mirrors production. Dev environments are too small to test realistic load and you'll chase ghosts for a week.

3 — Ignoring think time

Add sleep() to simulate user pacing. Real users don't hammer APIs.

4 — Testing the wrong thing

Focus on critical user journeys, not every endpoint. For broader context, see our Load Testing Tools Comparison.

5 — Trusting a single run

Network jitter, autoscaling cold starts, and noisy neighbors all skew one-shot results. Run the same scenario three times and treat the median as truth.

k6 dumps a wall of numbers when a run finishes. Ignore 80% of them and focus on these six:

Pipe results into Grafana + InfluxDB

k6 run --out influxdb=http://localhost:8086/k6 load-test.js

Then import the official k6 Grafana dashboard (ID 2587) and you'll see live percentile bands, error curves, and VU ramps as the test runs. This is the single fastest way to correlate a latency spike with an autoscaling event or a slow DB query.

Save JSON for CI diffing

k6 run --summary-export=summary.json load-test.js

Store the JSON as a CI artifact and diff metrics.http_req_duration.p(95) across the last 10 runs. Trend regressions catch capacity drift long before a threshold hard-fails.

The k6 browser module spins up Chromium instances under the same k6 runtime, so you can measure real browser metrics — First Contentful Paint, LCP, click-to-nav — under load. It's the missing piece if your bottleneck is frontend, not the API.

import { browser } from 'k6/browser';
import { check } from 'k6';

export const options = {
  scenarios: {
    ui: {
      executor: 'shared-iterations',
      options: { browser: { type: 'chromium' } },
      vus: 10,
      iterations: 100,
    },
  },
  thresholds: {
    browser_web_vital_lcp: ['p(95) < 2500'],
    browser_web_vital_fcp: ['p(95) < 1800'],
  },
};

export default async function () {
  const page = await browser.newPage();
  try {
    await page.goto('https://app.example.com/dashboard');
    await page.locator('input[name="email"]').type('demo@example.com');
    await page.locator('input[name="password"]').type('Sup3rSecret!');
    await Promise.all([
      page.locator('button[type="submit"]').click(),
      page.waitForNavigation(),
    ]);
    check(page, { 'dashboard loaded': (p) => p.url().includes('/dashboard') });
  } finally {
    await page.close();
  }
}

Browser VUs are ~50–100× heavier than protocol-level VUs — one Chromium process per VU eats ~150 MB RAM. Rule of thumb: for every 1 browser VU, budget 10 protocol VUs of equivalent machine cost. Use browser mode for critical user-journey validation under moderate load, and protocol mode for the raw stress ceiling. If you already ship Playwright end-to-end tests, the API mirrors Playwright almost 1:1 — see our Playwright complete guide and Playwright vs Selenium 2026 guide for the underlying differences.

These three own the open-source load-testing market. I've shipped all three in the last 24 months. Here's how they actually compare on the axes that matter.

My decision framework

• k6 — you're a dev-first team, ship on GitHub Actions, and want load tests reviewed in PRs alongside code.
• JMeter — you have non-coding perf engineers, need JDBC/JMS/FTP, or already run a JMeter grid.
• Locust — Python is your team's first language and you need to load-test something exotic (MQTT, custom RPC) with the full Python ecosystem.

For a full head-to-head focused on the k6 vs JMeter question, see our k6 vs JMeter 2026 comparison and the wider load testing tools comparison. Preparing for a performance-role interview? Our performance testing interview questions (JMeter, k6, LoadRunner) covers the exact tool trade-off questions hiring managers ask.

• JMeter Tutorial for Beginners — the closest GUI-driven alternative, with a side-by-side learning curve.
• k6 vs JMeter: 2026 Performance Testing Compared — picks a winner per team profile.
• Load Testing Tools Comparison — k6, JMeter, Gatling, Locust and LoadRunner side by side.
• Performance Testing Interview Questions — JMeter, k6 and LoadRunner questions with sample answers.
• CI/CD Pipeline Testing Tutorial — wires k6 thresholds into PR gates.

Official references: k6 docs · Grafana Cloud k6 · k6 engineering blog.

Anchor your performance claims to 2026 SoftwareTestPilot research:

• Shift-left benchmarks (2026) — DORA-style latency & MTTR impact.
• Enterprise tool benchmarks (2026) — how load-test suites compare on flake vs cost.
• Test pyramid benchmarks (2026) — where perf tests fit in the layer mix.
• TDD benchmarks (2026) — ties performance regressions to defect density.

Head-to-head numbers we pulled from three production benchmarks (payments API, media CMS, HR SaaS) and a scan of 4,120 QA/SDET postings in June 2026.

Hiring signal (Jun 2026 posting scan)

Bottom line: k6 wins on RPS-per-dollar and CI ergonomics; JMeter wins on GUI, protocol breadth, and legacy corporate footprints. If your team already runs Grafana, k6 is the shorter migration. See our k6 vs JMeter comparison for the full decision matrix.