Getting Started with k6 Load Testing: A Step-by-Step Guide

Verify the install with k6 version. If you'd rather skip local setup entirely, the Docker command above works identically in CI.

Your First Load Test

A k6 script needs just two things: an import for the HTTP module, and a default function that describes what each virtual user does per iteration.

// load-test.js
import http from 'k6/http';
import { sleep, check } from 'k6';

export const options = {
  vus: 10,
  duration: '30s',
};

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

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

  sleep(1);
}

Run it with:

k6 run load-test.js

This simulates 10 virtual users hitting the endpoint continuously for 30 seconds, each pausing 1 second between requests, and prints a summary of response times, request rate, and check pass/fail counts when it finishes.

Understanding Virtual Users and Stages

A fixed VU count is fine for a quick smoke check, but real traffic ramps up and down. The stages option lets you model that:

export const options = {
  stages: [
    { duration: '1m', target: 20 },   // ramp up to 20 VUs
    { duration: '3m', target: 20 },   // hold at 20 VUs
    { duration: '1m', target: 50 },   // spike to 50 VUs
    { duration: '2m', target: 50 },   // hold at peak
    { duration: '1m', target: 0 },    // ramp down
  ],
};

This pattern — ramp up, hold, spike, hold, ramp down — mirrors how real traffic behaves and reveals problems a flat VU count won't: connection pool exhaustion under sustained load, or a system that copes fine at steady state but falls over during a sudden spike.

Key k6 Metrics Explained

Averages hide problems. A 200ms average response time sounds healthy, but if the p(95) is 4 seconds, one in twenty real users is having a bad experience — always check percentiles, not just the mean.

Adding Checks and Thresholds

Checks validate individual responses (like an assertion); thresholds validate the entire test run and control the exit code, which is what makes a load test usable as a CI gate.

export const options = {
  stages: [
    { duration: '1m', target: 20 },
    { duration: '3m', target: 20 },
    { duration: '1m', target: 0 },
  ],
  thresholds: {
    http_req_duration: ['p(95)<500'],   // 95% of requests under 500ms
    http_req_failed: ['rate<0.01'],     // error rate under 1%
  },
};

With thresholds set, k6 run exits with a non-zero status if either condition fails — the same signal a CI pipeline checks to decide whether to block a deploy.

Real-World Test Scenarios

Testing multiple endpoints in one script

Real user sessions touch several endpoints, not one. Group related requests inside the default function, and use group() to label them for clearer reporting:

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

export default function () {
  group('browse products', () => {
    http.get('https://api.example.com/products');
    sleep(1);
  });

  group('view product detail', () => {
    http.get('https://api.example.com/products/101');
    sleep(2);
  });
}

Data-driven load with realistic payloads

Load a JSON or CSV file of test data with SharedArray so every virtual user isn't sending the exact same request — closer to how real traffic varies.

Authenticated flows

For APIs behind auth, log in once per virtual user at the start of the script, capture the token, and attach it to subsequent requests via headers — mirroring how a real session behaves rather than testing an unauthenticated endpoint.

Running k6 in CI/CD

Once thresholds are in place, a load test becomes a deployment gate, not a manual chore:

name: Load Test
on:
  workflow_dispatch:
  schedule:
    - cron: '0 3 * * *'
jobs:
  k6-load-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run k6 load test
        uses: grafana/k6-action@v0.3.1
        with:
          filename: load-test.js
        env:
          BASE_URL: ${{ secrets.STAGING_API_URL }}

Heavy load tests usually run on a schedule (nightly) or on demand rather than on every pull request, since they take longer and consume more staging capacity than a functional suite. Teams that want full setup — realistic traffic modeling, staging capacity planning, and dashboards — are exactly who our k6 load testing service is built for.

Best Practices

• Always target staging or a dedicated performance environment — never run heavy load against production.
• Start with low VUs and short duration to validate script correctness before scaling up.
• Check percentiles (p95, p99), not just averages — averages hide the worst experiences.
• Model realistic think time with sleep() between actions instead of hammering endpoints back-to-back.
• Set thresholds so the test can pass or fail automatically, not just produce a report.
• Version-control scripts alongside the API code they test, and review changes like any other test.
• Re-baseline thresholds after intentional infrastructure or scaling changes so old numbers don't cause false failures.

Frequently Asked Questions