perf-skills 1.0.3 → 2.0.0

package/skills/perf/references/tools/k6.md

@@ -1,269 +1,269 @@
-# k6 Reference
-
-> Targets: k6 v0.50+, xk6 extensions ecosystem
-
-k6 is a developer-centric, open-source load testing tool built by Grafana Labs. Tests are written in JavaScript/TypeScript and executed with a Go runtime — making it fast, scriptable, and CI/CD-friendly.
-
----
-
-## Core Concepts
-
-| Concept | Description |
-|---|---|
-| **Virtual User (VU)** | A single simulated user executing the script |
-| **Iteration** | One full execution of the default function |
-| **Scenario** | Named execution profile with its own executor and config |
-| **Executor** | Controls how VUs and iterations are scheduled |
-| **Metric** | Built-in or custom measurement (counters, gauges, rates, trends) |
-| **Check** | Inline assertion — does NOT fail the test; records pass/fail rate |
-| **Threshold** | SLA definition — FAILS the test if breached |
-| **Group** | Logical grouping of requests for metric aggregation |
-
----
-
-## Script Structure
-
-```javascript
-import http from 'k6/http';
-import { check, sleep, group } from 'k6';
-import { Counter, Trend } from 'k6/metrics';
-
-// Custom metrics
-const loginErrors = new Counter('login_errors');
-const checkoutDuration = new Trend('checkout_duration_ms');
-
-// Test configuration
-export const options = {
-  scenarios: {
-    ramp_up: {
-      executor: 'ramping-vus',
-      startVUs: 0,
-      stages: [
-        { duration: '2m', target: 50 },
-        { duration: '5m', target: 50 },
-        { duration: '2m', target: 0 },
-      ],
-    },
-  },
-  thresholds: {
-    http_req_duration: ['p(95)<500', 'p(99)<1000'],
-    http_req_failed: ['rate<0.01'],
-    login_errors: ['count<5'],
-  },
-};
-
-// Setup (runs once before VUs start)
-export function setup() {
-  const res = http.post('https://api.example.com/auth/token', {
-    client_id: 'perf-test',
-    client_secret: __ENV.API_SECRET,
-  });
-  return { token: res.json('access_token') };
-}
-
-// Default VU function
-export default function (data) {
-  group('Login Flow', () => {
-    const res = http.post('https://api.example.com/login', JSON.stringify({
-      username: `user_${__VU}@example.com`,
-      password: 'testpass',
-    }), {
-      headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${data.token}` },
-    });
-
-    const ok = check(res, {
-      'login status 200': (r) => r.status === 200,
-      'has userId': (r) => r.json('userId') !== undefined,
-    });
-    if (!ok) loginErrors.add(1);
-  });
-
-  sleep(Math.random() * 3 + 1); // Think time: 1–4 seconds
-}
-
-// Teardown (runs once after all VUs finish)
-export function teardown(data) {
-  // Cleanup, invalidate tokens, etc.
-}
-```
-
----
-
-## Executors
-
-| Executor | Use Case | Key Options |
-|---|---|---|
-| `ramping-vus` | Ramp up/down | `stages: [{duration, target}]` |
-| `constant-vus` | Fixed concurrency | `vus`, `duration` |
-| `per-vu-iterations` | Each VU runs N times | `vus`, `iterations` |
-| `shared-iterations` | Total N iterations split across VUs | `vus`, `iterations` |
-| `constant-arrival-rate` | Fixed RPS (open model) | `rate`, `duration`, `preAllocatedVUs` |
-| `ramping-arrival-rate` | Ramping RPS (open model) | `stages`, `preAllocatedVUs` |
-| `externally-controlled` | Controlled via k6 REST API in real-time | — |
-
-> For closed vs open model guidance and when to use each, see `../topics/workload-design.md`.
-
----
-
-## Checks vs Thresholds
-
-```javascript
-// Check: logs pass/fail but does NOT fail the test
-check(res, { 'status 200': (r) => r.status === 200 });
-
-// Threshold: FAILS the test run (non-zero exit code) if breached
-// Put these in options.thresholds
-thresholds: {
-  http_req_duration: ['p(95)<500'],  // p95 must be under 500ms
-  checks: ['rate>0.99'],             // At least 99% of checks must pass
-}
-```
-
-Use thresholds for SLA enforcement in CI/CD pipelines.
-
----
-
-## Parameterization
-
-### Environment variables
-```bash
-k6 run -e USERNAME=testuser -e PASSWORD=secret script.js
-```
-```javascript
-const username = __ENV.USERNAME;
-```
-
-### SharedArray (CSV / JSON data files)
-```javascript
-import { SharedArray } from 'k6/data';
-import papaparse from 'https://jslib.k6.io/papaparse/5.1.1/index.js';
-
-const users = new SharedArray('users', function () {
-  return papaparse.parse(open('./data/users.csv'), { header: true }).data;
-});
-
-export default function () {
-  const user = users[__VU % users.length]; // Round-robin by VU
-  // use user.username, user.password
-}
-```
-
-**SharedArray loads data once and shares it across all VUs** — critical for memory efficiency at high concurrency.
-
----
-
-## Correlation (Session Handling)
-
-```javascript
-// Extract value from JSON response
-const token = res.json('data.access_token');
-
-// Extract from HTML (regex)
-const csrfToken = res.html().find('input[name="_token"]').attr('value');
-
-// Extract from headers
-const sessionId = res.headers['Set-Cookie'].match(/JSESSIONID=([^;]+)/)[1];
-
-// Use in next request
-http.get('https://api.example.com/profile', {
-  headers: { 'Authorization': `Bearer ${token}` },
-});
-```
-
----
-
-## Custom Metrics
-
-```javascript
-import { Counter, Gauge, Rate, Trend } from 'k6/metrics';
-
-const checkoutErrors    = new Counter('checkout_errors');    // cumulative count
-const activeUsers       = new Gauge('active_users');         // current value
-const successRate       = new Rate('success_rate');          // ratio
-const transactionTime   = new Trend('transaction_time_ms'); // distribution (p50/p95/p99)
-
-// Usage inside default()
-transactionTime.add(res.timings.duration);
-successRate.add(res.status === 200);
-```
-
----
-
-## Modules & Extensions
-
-### Built-in k6 modules
-- `k6/http` — HTTP/1.1 and HTTP/2
-- `k6/ws` — WebSocket
-- `k6/grpc` — gRPC
-- `k6/browser` — Browser-based testing (Chromium)
-- `k6/experimental/redis` — Redis client
-- `k6/crypto` — Hashing and HMAC
-- `k6/encoding` — Base64
-
-### Popular xk6 extensions (require custom build)
-- `xk6-kafka` — Kafka load testing
-- `xk6-sql` — SQL database testing
-- `xk6-output-prometheus-remote` — Push metrics to Prometheus
-
-Build custom k6: `xk6 build --with github.com/grafana/xk6-kafka`
-
----
-
-## Running k6
-
-```bash
-# Local run
-k6 run script.js
-
-# With options override
-k6 run --vus 50 --duration 5m script.js
-
-# With env vars
-k6 run -e BASE_URL=https://staging.example.com script.js
-
-# Output to multiple sinks
-k6 run --out json=results.json --out influxdb=http://localhost:8086/k6 script.js
-
-# Cloud run (Grafana Cloud k6)
-k6 cloud script.js
-```
-
----
-
-## Output and Observability
-
-| Output | Command |
-|---|---|
-| Terminal summary | Default |
-| JSON | `--out json=results.json` |
-| InfluxDB (Grafana stack) | `--out influxdb=http://influx:8086/k6` |
-| Prometheus | `--out experimental-prometheus-rw` |
-| Grafana Cloud | `k6 cloud` or `--out cloud` |
-| CSV | `--out csv=results.csv` |
-
-### InfluxDB + Grafana Dashboard
-The canonical observability stack: k6 → InfluxDB → Grafana with the official k6 Grafana dashboard (ID: 2587).
-
----
-
-## TypeScript Support
-
-```bash
-# Use k6 template with TypeScript
-npx create-k6-app@latest --template typescript my-test
-```
-
-Benefits: Type safety, IDE autocomplete, better refactoring for large test suites.
-
----
-
-## k6-Specific Tips
-
-- **Always use `SharedArray`** for data files — loading data inside `default()` causes massive per-iteration overhead.
-- **Use `for` loops only for sequential steps**, not concurrency — use VUs and executors for parallel load.
-- **Remove `console.log` from hot paths** — dramatically reduces throughput during load runs.
-- **Use `__ENV.BASE_URL`** for environment portability — never hardcode base URLs.
-- **Prefer thresholds over checks alone** — without thresholds, the test always "passes" in CI/CD.
-
-> For CI/CD integration (GitHub Actions, GitLab CI, Jenkins), see `../topics/test-execution.md`.
-> For anti-patterns, assertions, think time, and parameterization principles, see **Key Principles** in `SKILL.md`.
+# k6 Reference
+
+> Targets: k6 v0.50+, xk6 extensions ecosystem
+
+k6 is a developer-centric, open-source load testing tool built by Grafana Labs. Tests are written in JavaScript/TypeScript and executed with a Go runtime - making it fast, scriptable, and CI/CD-friendly.
+
+---
+
+## Core Concepts
+
+| Concept | Description |
+|---|---|
+| **Virtual User (VU)** | A single simulated user executing the script |
+| **Iteration** | One full execution of the default function |
+| **Scenario** | Named execution profile with its own executor and config |
+| **Executor** | Controls how VUs and iterations are scheduled |
+| **Metric** | Built-in or custom measurement (counters, gauges, rates, trends) |
+| **Check** | Inline assertion - does NOT fail the test; records pass/fail rate |
+| **Threshold** | SLA definition - FAILS the test if breached |
+| **Group** | Logical grouping of requests for metric aggregation |
+
+---
+
+## Script Structure
+
+```javascript
+import http from 'k6/http';
+import { check, sleep, group } from 'k6';
+import { Counter, Trend } from 'k6/metrics';
+
+// Custom metrics
+const loginErrors = new Counter('login_errors');
+const checkoutDuration = new Trend('checkout_duration_ms');
+
+// Test configuration
+export const options = {
+  scenarios: {
+    ramp_up: {
+      executor: 'ramping-vus',
+      startVUs: 0,
+      stages: [
+        { duration: '2m', target: 50 },
+        { duration: '5m', target: 50 },
+        { duration: '2m', target: 0 },
+      ],
+    },
+  },
+  thresholds: {
+    http_req_duration: ['p(95)<500', 'p(99)<1000'],
+    http_req_failed: ['rate<0.01'],
+    login_errors: ['count<5'],
+  },
+};
+
+// Setup (runs once before VUs start)
+export function setup() {
+  const res = http.post('https://api.example.com/auth/token', {
+    client_id: 'perf-test',
+    client_secret: __ENV.API_SECRET,
+  });
+  return { token: res.json('access_token') };
+}
+
+// Default VU function
+export default function (data) {
+  group('Login Flow', () => {
+    const res = http.post('https://api.example.com/login', JSON.stringify({
+      username: `user_${__VU}@example.com`,
+      password: 'testpass',
+    }), {
+      headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${data.token}` },
+    });
+
+    const ok = check(res, {
+      'login status 200': (r) => r.status === 200,
+      'has userId': (r) => r.json('userId') !== undefined,
+    });
+    if (!ok) loginErrors.add(1);
+  });
+
+  sleep(Math.random() * 3 + 1); // Think time: 1–4 seconds
+}
+
+// Teardown (runs once after all VUs finish)
+export function teardown(data) {
+  // Cleanup, invalidate tokens, etc.
+}
+```
+
+---
+
+## Executors
+
+| Executor | Use Case | Key Options |
+|---|---|---|
+| `ramping-vus` | Ramp up/down | `stages: [{duration, target}]` |
+| `constant-vus` | Fixed concurrency | `vus`, `duration` |
+| `per-vu-iterations` | Each VU runs N times | `vus`, `iterations` |
+| `shared-iterations` | Total N iterations split across VUs | `vus`, `iterations` |
+| `constant-arrival-rate` | Fixed RPS (open model) | `rate`, `duration`, `preAllocatedVUs` |
+| `ramping-arrival-rate` | Ramping RPS (open model) | `stages`, `preAllocatedVUs` |
+| `externally-controlled` | Controlled via k6 REST API in real-time | - |
+
+> For closed vs open model guidance and when to use each, see `../topics/workload-design.md`.
+
+---
+
+## Checks vs Thresholds
+
+```javascript
+// Check: logs pass/fail but does NOT fail the test
+check(res, { 'status 200': (r) => r.status === 200 });
+
+// Threshold: FAILS the test run (non-zero exit code) if breached
+// Put these in options.thresholds
+thresholds: {
+  http_req_duration: ['p(95)<500'],  // p95 must be under 500ms
+  checks: ['rate>0.99'],             // At least 99% of checks must pass
+}
+```
+
+Use thresholds for SLA enforcement in CI/CD pipelines.
+
+---
+
+## Parameterization
+
+### Environment variables
+```bash
+k6 run -e USERNAME=testuser -e PASSWORD=secret script.js
+```
+```javascript
+const username = __ENV.USERNAME;
+```
+
+### SharedArray (CSV / JSON data files)
+```javascript
+import { SharedArray } from 'k6/data';
+import papaparse from 'https://jslib.k6.io/papaparse/5.1.1/index.js';
+
+const users = new SharedArray('users', function () {
+  return papaparse.parse(open('./data/users.csv'), { header: true }).data;
+});
+
+export default function () {
+  const user = users[__VU % users.length]; // Round-robin by VU
+  // use user.username, user.password
+}
+```
+
+**SharedArray loads data once and shares it across all VUs** - critical for memory efficiency at high concurrency.
+
+---
+
+## Correlation (Session Handling)
+
+```javascript
+// Extract value from JSON response
+const token = res.json('data.access_token');
+
+// Extract from HTML (regex)
+const csrfToken = res.html().find('input[name="_token"]').attr('value');
+
+// Extract from headers
+const sessionId = res.headers['Set-Cookie'].match(/JSESSIONID=([^;]+)/)[1];
+
+// Use in next request
+http.get('https://api.example.com/profile', {
+  headers: { 'Authorization': `Bearer ${token}` },
+});
+```
+
+---
+
+## Custom Metrics
+
+```javascript
+import { Counter, Gauge, Rate, Trend } from 'k6/metrics';
+
+const checkoutErrors    = new Counter('checkout_errors');    // cumulative count
+const activeUsers       = new Gauge('active_users');         // current value
+const successRate       = new Rate('success_rate');          // ratio
+const transactionTime   = new Trend('transaction_time_ms'); // distribution (p50/p95/p99)
+
+// Usage inside default()
+transactionTime.add(res.timings.duration);
+successRate.add(res.status === 200);
+```
+
+---
+
+## Modules & Extensions
+
+### Built-in k6 modules
+- `k6/http` - HTTP/1.1 and HTTP/2
+- `k6/ws` - WebSocket
+- `k6/grpc` - gRPC
+- `k6/browser` - Browser-based testing (Chromium)
+- `k6/experimental/redis` - Redis client
+- `k6/crypto` - Hashing and HMAC
+- `k6/encoding` - Base64
+
+### Popular xk6 extensions (require custom build)
+- `xk6-kafka` - Kafka load testing
+- `xk6-sql` - SQL database testing
+- `xk6-output-prometheus-remote` - Push metrics to Prometheus
+
+Build custom k6: `xk6 build --with github.com/grafana/xk6-kafka`
+
+---
+
+## Running k6
+
+```bash
+# Local run
+k6 run script.js
+
+# With options override
+k6 run --vus 50 --duration 5m script.js
+
+# With env vars
+k6 run -e BASE_URL=https://staging.example.com script.js
+
+# Output to multiple sinks
+k6 run --out json=results.json --out influxdb=http://localhost:8086/k6 script.js
+
+# Cloud run (Grafana Cloud k6)
+k6 cloud script.js
+```
+
+---
+
+## Output and Observability
+
+| Output | Command |
+|---|---|
+| Terminal summary | Default |
+| JSON | `--out json=results.json` |
+| InfluxDB (Grafana stack) | `--out influxdb=http://influx:8086/k6` |
+| Prometheus | `--out experimental-prometheus-rw` |
+| Grafana Cloud | `k6 cloud` or `--out cloud` |
+| CSV | `--out csv=results.csv` |
+
+### InfluxDB + Grafana Dashboard
+The canonical observability stack: k6 → InfluxDB → Grafana with the official k6 Grafana dashboard (ID: 2587).
+
+---
+
+## TypeScript Support
+
+```bash
+# Use k6 template with TypeScript
+npx create-k6-app@latest --template typescript my-test
+```
+
+Benefits: Type safety, IDE autocomplete, better refactoring for large test suites.
+
+---
+
+## k6-Specific Tips
+
+- **Always use `SharedArray`** for data files - loading data inside `default()` causes massive per-iteration overhead.
+- **Use `for` loops only for sequential steps**, not concurrency - use VUs and executors for parallel load.
+- **Remove `console.log` from hot paths** - dramatically reduces throughput during load runs.
+- **Use `__ENV.BASE_URL`** for environment portability - never hardcode base URLs.
+- **Prefer thresholds over checks alone** - without thresholds, the test always "passes" in CI/CD.
+
+> For CI/CD integration (GitHub Actions, GitLab CI, Jenkins), see `../topics/test-execution.md`.
+> For anti-patterns, assertions, think time, and parameterization principles, see **Key Principles** in `SKILL.md`.