API Load Testing with k6

k6 is the developer-first load testing tool that runs JavaScript scripts, scales to millions of requests, and integrates cleanly into CI/CD. This guide covers everything from first run to production SLA enforcement.

Installation

# macOS
brew install k6

# Ubuntu/Debian
sudo apt-get install k6

# Windows (via Chocolatey)
choco install k6

# Docker (no install needed)
docker run --rm -i grafana/k6 run - < script.js

Basic Load Test Script

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

export const options = {
  // Ramp up: 0 → 50 VUs in 1m, hold 5m, ramp down 1m
  stages: [
    { duration: '1m', target: 50 },
    { duration: '5m', target: 50 },
    { duration: '1m', target: 0  },
  ],
  // SLA thresholds — test fails if any is breached
  thresholds: {
    'http_req_duration': ['p(95) < 500', 'p(99) < 1000'],  // ms
    'http_req_failed':   ['rate < 0.01'],                   // < 1% errors
  },
};

export default function () {
  const BASE_URL = 'https://api.example.com';

  // GET request
  const res = http.get(`${BASE_URL}/users`, {
    headers: { Authorization: 'Bearer test-token' },
  });

  check(res, {
    'status is 200':         (r) => r.status === 200,
    'response time OK':      (r) => r.timings.duration < 500,
    'has users array':       (r) => JSON.parse(r.body).users !== undefined,
  });

  sleep(1); // think time between iterations
}

# Run the test
k6 run load-test.js

# Quick smoke test (1 VU, 10 iterations)
k6 run --vus 1 --iterations 10 load-test.js

# Output results as JSON
k6 run --out json=results.json load-test.js

POST with Authentication Flow

// auth-flow.js
import http from 'k6/http';
import { check, sleep } from 'k6';

export const options = {
  vus: 100,
  duration: '5m',
  thresholds: {
    'http_req_duration{name:login}':     ['p(95) < 300'],
    'http_req_duration{name:dashboard}': ['p(95) < 200'],
  },
};

export default function () {
  // Step 1: Login
  const loginRes = http.post(
    'https://api.example.com/auth/login',
    JSON.stringify({ email: '[email protected]', password: 'pass123' }),
    {
      headers: { 'Content-Type': 'application/json' },
      tags: { name: 'login' },   // tag for per-endpoint thresholds
    }
  );
  check(loginRes, { 'login 200': (r) => r.status === 200 });

  const token = loginRes.json('token');

  // Step 2: Authenticated request
  const dashRes = http.get(
    'https://api.example.com/dashboard',
    {
      headers: { Authorization: `Bearer ${token}` },
      tags: { name: 'dashboard' },
    }
  );
  check(dashRes, { 'dashboard 200': (r) => r.status === 200 });

  sleep(2);
}

Load Test Types and When to Use Each

CI/CD Integration (GitHub Actions)

# .github/workflows/load-test.yml
name: API Load Test
on:
  workflow_dispatch:  # manual trigger
  schedule:
    - cron: '0 2 * * 1'  # every Monday at 2am
jobs:
  k6-load-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: grafana/setup-k6-action@v1  # official k6 action
      - name: Run load test
        run: k6 run --out json=results.json load-test.js
        env:
          API_BASE_URL: ${{ vars.STAGING_API_URL }}
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: k6-results
          path: results.json