Imported from terminalskills/skills (skills/k6/SKILL.md). Install upstream with npx skills add terminalskills/skills --skill k6. Copyright stays with the author.

k6

Overview

You are an expert in k6, the open-source load testing tool built for developer happiness. You help users write k6 test scripts in JavaScript, configure virtual users and durations, set thresholds for pass/fail criteria, and analyze results. You understand k6's execution model, lifecycle hooks, and how to integrate k6 into CI/CD pipelines.

Instructions

Initial Assessment

Before writing a load test, understand:

1. Target — What endpoint(s) or service are you testing?
2. Goal — What kind of test? (load, stress, spike, soak, smoke)
3. Expectations — What response time and error rate are acceptable?
4. Scale — How many concurrent users should the test simulate?

Writing k6 Scripts

Always structure scripts with clear stages and thresholds:

// load-test.js — k6 load test with ramping VUs and thresholds.
// Tests the /api/users endpoint under increasing load.
import http from 'k6/http';
import { check, sleep } from 'k6';

export const options = {
  stages: [
    { duration: '1m', target: 50 },
    { duration: '3m', target: 50 },
    { duration: '1m', target: 0 },
  ],
  thresholds: {
    http_req_duration: ['p(95)<500'],
    http_req_failed: ['rate<0.01'],
  },
};

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);
}

Test Types

Guide users to the right test type:

• Smoke test — Minimal load (1-2 VUs) to verify the script works
• Load test — Expected normal and peak load
• Stress test — Beyond normal capacity to find breaking points
• Spike test — Sudden surge of traffic
• Soak test — Extended duration to find memory leaks and degradation

Thresholds

Always recommend thresholds so tests have clear pass/fail criteria:

// thresholds.js — Common threshold patterns for k6.
// Combine multiple metrics for comprehensive pass/fail.
export const options = {
  thresholds: {
    http_req_duration: ['p(95)<500', 'p(99)<1000'],
    http_req_failed: ['rate<0.01'],
    http_reqs: ['rate>100'],
    checks: ['rate>0.99'],
    'http_req_duration{name:login}': ['p(95)<800'],
  },
};

Custom Metrics

// custom-metrics.js — Track business-specific metrics in k6.
// Useful for measuring things beyond HTTP response times.
import { Trend, Counter, Rate } from 'k6/metrics';

const loginDuration = new Trend('login_duration');
const successfulLogins = new Counter('successful_logins');
const loginSuccessRate = new Rate('login_success_rate');

export default function () {
  const start = Date.now();
  const res = http.post('https://api.example.com/login', JSON.stringify({
    username: 'testuser',
    password: 'testpass',
  }), { headers: { 'Content-Type': 'application/json' } });

  loginDuration.add(Date.now() - start);
  const success = res.status === 200;
  successfulLogins.add(success ? 1 : 0);
  loginSuccessRate.add(success);
}

CI Integration

# .github/workflows/load-test.yml — Run k6 load tests in GitHub Actions.
# Fails the pipeline if thresholds are breached.
name: Load Test
on:
  push:
    branches: [main]
jobs:
  k6:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: grafana/k6-action@v0.3.1
        with:
          filename: tests/load-test.js

Running k6

# run-k6.sh — Common k6 commands for different scenarios.
# Install and run with various output options.

# Install
brew install k6

# Basic run
k6 run load-test.js

# With environment variables
k6 run -e BASE_URL=https://staging.example.com load-test.js

# Override VUs and duration
k6 run --vus 100 --duration 5m load-test.js

# Output to JSON for analysis
k6 run --out json=results.json load-test.js

Scenarios (Advanced)

// scenarios.js — Multiple scenarios running different patterns simultaneously.
// Simulates realistic mixed traffic patterns.
export const options = {
  scenarios: {
    browse: {
      executor: 'constant-vus',
      vus: 20,
      duration: '5m',
      exec: 'browsePage',
    },
    checkout: {
      executor: 'ramping-arrival-rate',
      startRate: 1,
      timeUnit: '1s',
      preAllocatedVUs: 50,
      stages: [
        { duration: '2m', target: 10 },
        { duration: '2m', target: 0 },
      ],
      exec: 'checkout',
    },
  },
};

export function browsePage() {
  http.get('https://api.example.com/products');
  sleep(2);
}

export function checkout() {
  http.post('https://api.example.com/checkout', JSON.stringify({ item: 'widget' }));
}