k6 Scenario Builder

Enforces a consistent, production-ready pattern for k6 load test scripts using JavaScript or TypeScript, covering HTTP/REST, WebSocket, and gRPC protocols.

Output Format

When producing or fixing a script, always deliver three things:

A complete, runnable script file — never a partial snippet.
The exact run command with the environment variables needed.
A one-line explanation of the executor chosen and why it fits the load goal.

When fixing any OOM error or open() misuse, cover both failure modes — even if the user only mentioned one:

Plain variable at init context → OOM (data copied per VU). Fix: SharedArray.
open() inside default() → immediate runtime error (can't call open() in the VU context). Fix: move to init context.

Step 1 — Gather Context

Ask only what is unknown:

Language: JavaScript (default) · TypeScript
Protocol: HTTP/REST · WebSocket · gRPC
Goal: New script · Fix existing script · Specific DSL question
Workload model: Fixed concurrent users (closed) or fixed arrival rate in RPS (open)?

Only load references/EXECUTORS.md when the user asks about executor types, workload models, scenario configuration, multi-scenario orchestration, or startTime/exec/gracefulStop parameters.

Only load references/PROTOCOLS.md when the user mentions WebSocket or gRPC. Contains connection setup, event handling, streaming DSL, and gotchas.

Only load references/DESIGN-PATTERNS.md when the user asks about folder structure, project architecture, sharing data between VUs, TypeScript setup, scaling beyond a single file, modular structure, reusable helpers, multi-step user flows (e-commerce, checkout, login+browse), or multiple scenarios sharing common logic.

Step 2 — Apply the 5-Block Pattern

Every k6 script must have these five blocks in order. Generate the complete skeleton first, then fill in details.

Block 1 → Options     scenarios + thresholds (executor, VUs, duration, SLA gates)
Block 2 → Data        SharedArray for parameterized inputs — loaded once, shared across VUs
Block 3 → Setup       one-time auth or preparation — runs once before VUs start
Block 4 → Default fn  the VU workload: requests, checks, groups, sleep
Block 5 → Teardown    cleanup (optional — required for gRPC/WS connection close)

Common Mistakes — Check Every Script for These

1. No `sleep()` between requests — generates unrealistic load

Without think time, VUs hammer the server at maximum speed. Always add sleep() between logical steps.

// Wrong — zero think time, unrealistic throughput
export default function() {
  http.get(`${BASE_URL}/api/products`);
  http.get(`${BASE_URL}/api/cart`);
}

// Correct — realistic think time between steps
import { sleep } from 'k6';

export default function() {
  http.get(`${BASE_URL}/api/products`);
  sleep(Math.random() * 2 + 1);  // 1–3s think time
  http.get(`${BASE_URL}/api/cart`);
  sleep(1);
}

2. `check()` as a test gate — it never fails the test

check() records pass/fail statistics but never stops or fails the test. This is the most common k6 misconception. Use thresholds to actually fail.

// Wrong — test always exits 0 even if every request returns 500
check(res, { 'status is 200': (r) => r.status === 200 });

// Correct — thresholds fail the test; check() provides per-request diagnostics
export const options = {
  thresholds: {
    http_req_failed:   ['rate<0.01'],   // < 1% errors — fails test if breached
    http_req_duration: ['p(95)<500'],   // p95 < 500ms — fails test if breached
    checks:            ['rate>0.99'],   // > 99% checks pass
  },
};
check(res, { 'status is 200': (r) => r.status === 200 });  // keep for diagnostics

Three failure mechanisms:

check() — per-iteration assertion, records stats, never stops the test
threshold — aggregate SLA gate, fails the test on breach (exit code 99)
fail(msg) — stops the current iteration immediately, use for unrecoverable errors

3. Hardcoded base URL — breaks multi-environment usage

// Wrong
const res = http.get('https://hardcoded-prod.example.com/api/users');

// Correct — parameterize all environment-specific values
const BASE_URL = __ENV.BASE_URL || 'https://staging.example.com';

Run: k6 run --env BASE_URL=https://prod.example.com script.js

4. Storing test data in a plain variable — multiplied per VU

Any variable declared at init context scope is copied once per VU. For a 50 MB JSON file with 200 VUs, that is 10 GB of RAM. Use SharedArray — loaded once, shared across all VUs as read-only.

// Wrong — 50 MB × 200 VUs = 10 GB RAM
import { open } from 'k6';  // open() is init-context only
const users = JSON.parse(open('./data/users.json'));  // per-VU copy

// Correct — 50 MB total regardless of VU count
import { SharedArray } from 'k6/data';
const users = new SharedArray('users', () => JSON.parse(open('./data/users.json')));

Two open() errors to always explain together:

Plain variable at init context → OOM (per-VU copy). Fix: SharedArray.
open() inside default() → runtime error (can't call open() in the VU context). Fix: move to init context.

5. Imports not at the top of the file — breaks convention and readability

All import statements must be the very first lines of the file — before export const options, before SharedArray, before any other code. ES modules technically hoist imports regardless of position, but placing them anywhere else creates scripts that are hard to read and breaks the init-context mental model.

// Wrong — imports scattered between blocks
export const options = { ... };         // ❌ options before imports

import { SharedArray } from 'k6/data'; // ❌ import mid-file
const users = new SharedArray(...);

import http from 'k6/http';            // ❌ another import even later
import { check, sleep } from 'k6';

// Correct — all imports first, then options, then data, then functions
import http                        from 'k6/http';
import { check, group, sleep, fail } from 'k6';
import { SharedArray }             from 'k6/data';

export const options = { ... };

const users = new SharedArray('users', () => JSON.parse(open('./data/users.json')));

export default function() { ... }

6. `ramping-vus` for a fixed RPS target — wrong workload model

ramping-vus controls concurrent users (closed model). Throughput varies with response time. For a fixed RPS goal, use constant-arrival-rate.

// Wrong for "maintain 100 RPS" — actual RPS drops when server is slow
executor: 'ramping-vus', stages: [{ duration: '5m', target: 100 }]

// Correct — arrival rate is constant regardless of response time
executor: 'constant-arrival-rate',
rate: 100,
timeUnit: '1s',
duration: '5m',
preAllocatedVUs: 50,   // rule: ceil(rate × p95_seconds × 1.2)
maxVUs: 200,

7. Under-sized `preAllocatedVUs` — silent dropped iterations

constant-arrival-rate drops iterations when VUs run out. Monitor dropped_iterations in output.

preAllocatedVUs = ceil(rate × p95_response_time_in_seconds × 1.2)
Example: 100 RPS, p95 = 400ms → ceil(100 × 0.4 × 1.2) = 48 → use 50

8. `gracefulStop` shorter than p99 response time — inflated errors

k6 waits gracefulStop duration after the test ends for in-flight iterations to complete. If p99 is 2s and gracefulStop is the default 30s, you are fine. But if p99 is 45s (batch job), set gracefulStop: '60s' explicitly.

scenarios: {
  load: {
    executor: 'constant-vus',
    vus: 100,
    duration: '5m',
    gracefulStop: '60s',   // set to at least 2× p99 response time
  }
}

9. One shared token for all VUs — all users share the same identity

setup() runs once before all VUs start. A token returned from setup() is shared by every VU — they all authenticate as the same user, producing unrealistic server-side behavior (single session, no per-user data isolation).

// Wrong — 100 VUs, all acting as the same user
export function setup() {
  const res = http.post(`${BASE_URL}/auth/login`, JSON.stringify({ username: 'admin', password: 'secret' }), ...);
  return { token: res.json('access_token') };  // shared by all VUs
}

// Correct — each VU logs in with its own credentials from SharedArray
import { SharedArray } from 'k6/data';
const credentials = new SharedArray('creds', () => JSON.parse(open('./data/users.json')));

export default function() {
  const cred = credentials[(__VU - 1) % credentials.length];  // deterministic per VU
  const res = http.post(`${BASE_URL}/auth/login`,
    JSON.stringify({ username: cred.username, password: cred.password }),
    { headers: { 'Content-Type': 'application/json' } }
  );
  const token = res.json('access_token');
  // use token for subsequent requests in this iteration
}

Use setup() only for shared, stateless initialization (e.g., seeding a test dataset via an admin API call).

10. Missing `Content-Type` on POST — server returns 415

// Wrong — 415 Unsupported Media Type
http.post(`${BASE_URL}/api/users`, JSON.stringify({ name: 'Alice' }));

// Correct
http.post(`${BASE_URL}/api/users`, JSON.stringify({ name: 'Alice' }), {
  headers: { 'Content-Type': 'application/json' },
});

The 5-Block Pattern — Reference

Block 1: Options

export const options = {
  scenarios: {
    load: {
      executor:         'ramping-vus',
      startVUs:         0,
      stages: [
        { duration: '2m', target: 50 },   // ramp up
        { duration: '5m', target: 50 },   // hold
        { duration: '2m', target: 0  },   // ramp down
      ],
      gracefulRampDown: '30s',
      gracefulStop:     '30s',
    },
  },
  thresholds: {
    http_req_duration: ['p(95)<500', 'p(99)<1000'],
    http_req_failed:   ['rate<0.01'],
    checks:            ['rate>0.99'],
  },
};

Block 2: Data (SharedArray)

import { SharedArray } from 'k6/data';

// JSON file
const users = new SharedArray('users', () => JSON.parse(open('./data/users.json')));

// CSV file (manual parse — k6 has no built-in CSV parser)
const csvUsers = new SharedArray('csv-users', () =>
  open('./data/users.csv')
    .split('\n')
    .slice(1)                                   // skip header row
    .filter(line => line.trim().length > 0)
    .map(line => {
      const [username, password] = line.split(',');
      return { username: username.trim(), password: password.trim() };
    })
);

// Access pattern — deterministic: each VU always uses the same record
const user = users[(__VU - 1) % users.length];

// Access pattern — random: any VU may pick any record
const user = users[Math.floor(Math.random() * users.length)];

Block 3: Setup

const BASE_URL = __ENV.BASE_URL || 'https://staging.example.com';

export function setup() {
  // Use only for stateless, shared initialization — NOT per-VU auth
  const res = http.post(`${BASE_URL}/api/seed`, null, {
    headers: { Authorization: `Bearer ${__ENV.ADMIN_TOKEN}` },
  });
  if (res.status !== 200) {
    fail(`Seed failed: ${res.status} — aborting test`);
  }
  return { seedId: res.json('id') };
}

Block 4: Default Function (VU workload)

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

export default function(data) {
  const cred  = users[(__VU - 1) % users.length];
  const token = login(cred);   // per-VU auth

  group('Browse', () => {
    const res = http.get(`${BASE_URL}/api/products`, {
      headers: { Authorization: `Bearer ${token}` },
      tags:    { endpoint: 'products' },
    });
    check(res, {
      'products 200':       (r) => r.status === 200,
      'products not empty': (r) => r.json('#') > 0,
      'products < 500ms':   (r) => r.timings.duration < 500,
    });
    sleep(Math.random() * 2 + 1);
  });

  group('Checkout', () => {
    const res = http.post(`${BASE_URL}/api/orders`,
      JSON.stringify({ productId: data.seedId }),
      { headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
        tags: { endpoint: 'checkout' } }
    );
    check(res, {
      'order created 201': (r) => r.status === 201,
      'order has id':      (r) => r.json('id') !== undefined,
    });
    sleep(1);
  });
}

Block 5: Teardown

export function teardown(data) {
  // Clean up seed data
  http.del(`${BASE_URL}/api/seed/${data.seedId}`, null, {
    headers: { Authorization: `Bearer ${__ENV.ADMIN_TOKEN}` },
  });
}

Executor Selection Guide

Closed model — controls concurrent users. Use when connection count or session state matters.

Executor	When to use	Required params
`constant-vus`	Steady-state, fixed concurrency	`vus`, `duration`
`ramping-vus`	Ramp up/down, standard load test	`stages`, `startVUs`
`per-vu-iterations`	Each VU runs exactly N iterations	`vus`, `iterations`, `maxDuration`
`shared-iterations`	Exactly N total iterations across all VUs	`vus`, `iterations`, `maxDuration`

Open model — controls arrival rate. Use for public APIs where RPS is the goal.

Executor	When to use	Required params
`constant-arrival-rate`	Fixed RPS target	`rate`, `timeUnit`, `preAllocatedVUs`, `maxVUs`, `duration`
`ramping-arrival-rate`	Escalating RPS (stress test)	`stages`, `timeUnit`, `preAllocatedVUs`, `maxVUs`
`externally-controlled`	Live VU adjustment via REST API	`vus`, `maxVUs`, `duration`

Default choice: ramping-vus. Switch to constant-arrival-rate when the SLA is expressed in RPS.

Thresholds Reference

export const options = {
  thresholds: {
    // Global response time
    http_req_duration: ['p(95)<500', 'p(99)<1000'],

    // Per-tagged endpoint (tag set on the request)
    'http_req_duration{endpoint:checkout}': ['p(99)<2000'],

    // Error rate
    http_req_failed: ['rate<0.01'],

    // Check pass rate
    checks: ['rate>0.99'],

    // Throughput floor
    http_reqs: ['rate>50'],

    // Custom metric
    'checkout_duration_ms': ['p(95)<300'],
  },
};

// Abort test early if a threshold is breached:
export const options = {
  thresholds: {
    http_req_duration: [
      { threshold: 'p(95)<500', abortOnFail: true, delayAbortEval: '1m' },
      // delayAbortEval: wait 1m before evaluating — avoids aborting during ramp-up
    ],
  },
};

Custom Metrics

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

const checkoutMs   = new Trend('checkout_duration_ms');
const authErrors   = new Counter('auth_errors_total');
const cacheHits    = new Rate('cache_hit_rate');

export default function(data) {
  const start = Date.now();
  const body  = JSON.stringify({ productId: '123' });
  const res   = http.post(`${BASE_URL}/api/orders`, body, {
    headers: { 'Content-Type': 'application/json',
               Authorization: `Bearer ${data.token}` },
    tags: { endpoint: 'checkout' },
  });

  checkoutMs.add(Date.now() - start, { step: 'payment' });
  if (res.status === 401) authErrors.add(1);
  cacheHits.add(res.headers['X-Cache'] === 'HIT');
}

Run Commands

# Basic run
k6 run script.js

# Override VUs and duration from CLI (useful for quick smoke test)
k6 run --vus 2 --duration 30s script.js

# Pass environment variables
k6 run --env BASE_URL=https://staging.example.com \
       --env USERNAME=perf_user \
       --env PASSWORD=secret \
       script.js

# Output to JSON for post-analysis
k6 run --out json=results.json script.js

# Output to InfluxDB + Grafana
k6 run --out influxdb=http://localhost:8086/k6 script.js

# TypeScript — compile first, then run the output
npx esbuild src/load.ts --bundle --outfile=dist/load.js --target=es2015
k6 run dist/load.js

# Grafana Cloud execution
k6 cloud run script.js

k6-best-practices

k6 Scenario Builder

Output Format

Step 1 — Gather Context

Step 2 — Apply the 5-Block Pattern

Common Mistakes — Check Every Script for These

1. No `sleep()` between requests — generates unrealistic load

2. `check()` as a test gate — it never fails the test

3. Hardcoded base URL — breaks multi-environment usage

4. Storing test data in a plain variable — multiplied per VU

5. Imports not at the top of the file — breaks convention and readability

6. `ramping-vus` for a fixed RPS target — wrong workload model

7. Under-sized `preAllocatedVUs` — silent dropped iterations

8. `gracefulStop` shorter than p99 response time — inflated errors

9. One shared token for all VUs — all users share the same identity

10. Missing `Content-Type` on POST — server returns 415

The 5-Block Pattern — Reference

Block 1: Options

Block 2: Data (SharedArray)

Block 3: Setup

Block 4: Default Function (VU workload)

Block 5: Teardown

Executor Selection Guide

Thresholds Reference

Custom Metrics

Run Commands

References

k6-best-practices

k6 Scenario Builder

Output Format

Step 1 — Gather Context

Step 2 — Apply the 5-Block Pattern

Common Mistakes — Check Every Script for These

1. No sleep() between requests — generates unrealistic load

2. check() as a test gate — it never fails the test

3. Hardcoded base URL — breaks multi-environment usage

4. Storing test data in a plain variable — multiplied per VU

5. Imports not at the top of the file — breaks convention and readability

6. ramping-vus for a fixed RPS target — wrong workload model

7. Under-sized preAllocatedVUs — silent dropped iterations

8. gracefulStop shorter than p99 response time — inflated errors

9. One shared token for all VUs — all users share the same identity

10. Missing Content-Type on POST — server returns 415

The 5-Block Pattern — Reference

Block 1: Options

Block 2: Data (SharedArray)

Block 3: Setup

Block 4: Default Function (VU workload)

Block 5: Teardown

Executor Selection Guide

Thresholds Reference

Custom Metrics

Run Commands

References

1. No `sleep()` between requests — generates unrealistic load

2. `check()` as a test gate — it never fails the test

6. `ramping-vus` for a fixed RPS target — wrong workload model

7. Under-sized `preAllocatedVUs` — silent dropped iterations

8. `gracefulStop` shorter than p99 response time — inflated errors

10. Missing `Content-Type` on POST — server returns 415