k6 Complete Guide: The Modern Load Testing Tool for Developers 🚀

# macOS (Homebrew)
brew install k6

# Windows (Chocolatey)
choco install k6

# Windows (Winget)
winget install k6

# Linux (Debian/Ubuntu)
sudo gpg -k
sudo gpg --no-default-keyring --keyring /usr/share/keyrings/k6-archive-keyring.gpg --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys C5AD17C747E3415A3642D57D77C6C491D6AC1D69
echo "deb [signed-by=/usr/share/keyrings/k6-archive-keyring.gpg] 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

# Docker
docker pull grafana/k6

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

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

// Main test function
export default function () {
  const response = http.get('https://test-api.example.com/users');
  
  // Response validation
  check(response, {
    'status is 200': (r) => r.status === 200,
    'response time < 500ms': (r) => r.timings.duration < 500,
  });
  
  sleep(1); // Wait 1 second
}

k6 run first-test.js

export const options = {
  stages: [
    { duration: '2m', target: 100 },   // Ramp-up: Increase to 100 VUs over 2 minutes
    { duration: '5m', target: 100 },   // Steady state: Maintain 100 VUs for 5 minutes
    { duration: '2m', target: 400 },   // Spike: Jump to 400 VUs over 2 minutes
    { duration: '5m', target: 400 },   // Spike sustain: Maintain 400 VUs for 5 minutes
    { duration: '3m', target: 0 },     // Ramp-down: Gradually stop over 3 minutes
  ],
  thresholds: {
    http_req_duration: ['p(95)<500'],  // 95% of requests under 500ms
    http_req_failed: ['rate<0.1'],     // Failure rate under 0.1%
  },
};

export const options = {
  scenarios: {
    // Scenario 1: Regular browsing users
    browsing: {
      executor: 'constant-vus',
      vus: 50,
      duration: '10m',
      exec: 'browseProducts',
    },
    // Scenario 2: Purchase conversion users (higher priority)
    purchasing: {
      executor: 'ramping-vus',
      startVUs: 0,
      stages: [
        { duration: '2m', target: 10 },
        { duration: '8m', target: 10 },
      ],
      exec: 'completePurchase',
      gracefulRampDown: '30s',
    },
    // Scenario 3: API clients (arrival-rate based)
    api_calls: {
      executor: 'constant-arrival-rate',
      rate: 1000,
      timeUnit: '1m', // 1000 requests per minute
      duration: '10m',
      preAllocatedVUs: 20,
      maxVUs: 100,
      exec: 'apiRequests',
    },
  },
};

export function browseProducts() {
  http.get('https://shop.example.com/products');
  sleep(Math.random() * 3 + 1); // Random wait 1-4 seconds
}

export function completePurchase() {
  const payload = JSON.stringify({ product: 'laptop', qty: 1 });
  http.post('https://shop.example.com/cart', payload, {
    headers: { 'Content-Type': 'application/json' },
  });
  sleep(2);
}

export function apiRequests() {
  http.get('https://api.example.com/v1/data');
}

import { SharedArray } from 'k6/data';
import papaparse from 'https://jslib.k6.io/papaparse/5.1.1/index.js';

// Load CSV file
const csvData = new SharedArray('users', function () {
  return papaparse.parse(open('./users.csv'), { header: true }).data;
});

export default function () {
  const user = csvData[Math.floor(Math.random() * csvData.length)];
  
  const payload = JSON.stringify({
    username: user.username,
    password: user.password,
  });
  
  const response = http.post('https://api.example.com/login', payload, {
    headers: { 'Content-Type': 'application/json' },
  });
  
  check(response, {
    'login successful': (r) => r.status === 200 && r.json('token') !== '',
  });
}

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

// Custom metric definitions
const loginDuration = new Trend('login_duration');
const checkoutErrorRate = new Rate('checkout_errors');
const itemsAdded = new Counter('items_added_to_cart');
const activeUsers = new Gauge('concurrent_shoppers');

export default function () {
  const start = Date.now();
  
  const loginRes = http.post('https://shop.example.com/login', credentials);
  loginDuration.add(Date.now() - start);
  
  if (loginRes.status !== 200) {
    checkoutErrorRate.add(1);
  }
  
  // Add item to cart
  const cartRes = http.post('https://shop.example.com/cart/add', item);
  if (cartRes.status === 200) {
    itemsAdded.add(1);
  }
  
  activeUsers.add(1);
  sleep(5);
  activeUsers.add(-1);
}

# Install xk6
go install go.k6.io/xk6/cmd/xk6@latest

# Build k6 with browser extension
xk6 build --with github.com/grafana/xk6-browser

# Include multiple extensions
xk6 build \
  --with github.com/grafana/xk6-browser \
  --with github.com/grafana/xk6-sql \
  --with github.com/grafana/xk6-faker

# .github/workflows/performance.yml
name: Performance Tests

on:
  pull_request:
    branches: [main, develop]
  push:
    branches: [main]

jobs:
  smoke-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup k6
        uses: grafana/setup-k6-action@v1
      
      - name: Run smoke tests
        uses: grafana/run-k6-action@v1
        with:
          path: ./tests/smoke.js
          flags: --env ENV=staging
        env:
          K6_CLOUD_TOKEN: ${{ secrets.K6_CLOUD_TOKEN }}
      
      - name: Upload results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: k6-report
          path: ./summary.html

# .gitlab-ci.yml
performance_test:
  image: grafana/k6:latest
  stage: test
  script:
    - k6 run --out json=results.json tests/load.js
  artifacts:
    paths:
      - results.json
    expire_in: 1 week
  only:
    - merge_requests
    - main

// Jenkinsfile
pipeline {
    agent any
    
    environment {
        K6_TOKEN = credentials('k6-cloud-token')
    }
    
    stages {
        stage('Performance Test') {
            steps {
                sh '''
                    docker run --rm -v $(pwd):/tests \
                      -e K6_CLOUD_TOKEN=$K6_TOKEN \
                      grafana/k6:latest cloud /tests/load.js
                '''
            }
        }
    }
    
    post {
        always {
            publishHTML([
                allowMissing: false,
                alwaysLinkToLastBuild: true,
                keepAll: true,
                reportDir: 'results',
                reportFiles: 'index.html',
                reportName: 'k6 Performance Report'
            ])
        }
    }
}

export const options = {
  thresholds: {
    // HTTP request criteria
    http_req_duration: ['p(95)<500', 'p(99)<1000'],
    http_req_failed: ['rate<0.05'],
    
    // Business logic criteria
    checks: ['rate>=0.95'],
    
    // Custom metric criteria
    login_duration: ['avg<300', 'p(95)<600'],
    checkout_errors: ['rate<0.01'],
  },
  
  // Stop test on threshold failure
  abortOnFail: true,
};

# Login
k6 cloud login --token YOUR_TOKEN

# Run test in cloud
k6 cloud script.js

# Run in specific load zones
k6 cloud --ext-load-impact distribution='{"amazon:us:ashburn": 0.5, "amazon:de:frankfurt": 0.5}' script.js

// ❌ Bad example: Memory leak occurs
const allResponses = [];

export default function () {
  const res = http.get('https://api.example.com/data');
  allResponses.push(res); // Memory keeps increasing per VU
}

// ✅ Good example: Extract only needed data
export default function () {
  const res = http.get('https://api.example.com/data');
  
  // Extract only necessary values and validate immediately
  check(res, {
    'has valid data': (r) => r.json('status') === 'ok',
  });
  
  // Record only in global metrics
  myMetric.add(res.timings.duration);
}

export const options = {
  // Enable DNS caching
  dns: {
    ttl: '5m', // Cache for 5 minutes
    select: 'first', // Use only first IP
    policy: 'preferIPv4',
  },
};

export const options = {
  // Connection keep-alive settings
  batch: 20, // Batch requests
  batchPerHost: 6, // Max concurrent connections per host
  noConnectionReuse: false, // Enable connection reuse
  tlsAuth: null, // Disable TLS mutual auth (if not needed)
};

# Verbose logging
k6 run --verbose script.js

# HTTP debugging
k6 run --http-debug="full" script.js

# Run only specific VU (for debugging)
k6 run --vus 1 --iterations 1 script.js

# Export results as JSON
k6 run --out json=results.json script.js