@assertrx/dino 1.0.10 → 1.0.11

package/skills/generating-api-load-tests/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: generating-api-load-tests
+description: Use when creating k6 load test scripts for HTTP REST APIs, gRPC services, or WebSocket connections. Use when the user mentions load testing, performance testing, stress testing, API testing, or k6 script generation for protocol-level endpoints.
+---
+
+# Generating API Load Tests with k6
+
+Generate k6 load test scripts for protocol-level APIs. Covers HTTP/REST, gRPC, and WebSocket protocols with authentication, data parameterization, checks, and thresholds.
+
+## Quick Start — HTTP Load Test
+
+```javascript
+import http from 'k6/http';
+import { check, sleep } from 'k6';
+
+export const options = {
+  vus: 10,
+  duration: '30s',
+  thresholds: {
+    http_req_duration: ['p(95)<500'],
+    http_req_failed: ['rate<0.01'],
+  },
+};
+
+export default function () {
+  const res = http.get('https://test-api.k6.io/public/crocodiles/');
+
+  check(res, {
+    'status is 200': (r) => r.status === 200,
+    'response time < 500ms': (r) => r.timings.duration < 500,
+  });
+
+  sleep(1);
+}
+```
+
+## Test Lifecycle
+
+Every k6 script follows a 4-stage lifecycle:
+
+```
+1. init     — Runs once per VU. Import modules, load files, define options.
+              Cannot make HTTP requests.
+2. setup()  — Runs once before VU stage. Prepare test data, authenticate.
+              Can make HTTP requests. Return value passed to default() and teardown().
+3. default  — Runs repeatedly per VU. The main test logic.
+              Each iteration resets cookies and tears down connections.
+4. teardown — Runs once after all VUs finish. Cleanup resources.
+```
+
+```javascript
+import http from 'k6/http';
+
+export const options = { vus: 5, duration: '10s' };
+
+export function setup() {
+  const loginRes = http.post('https://api.example.com/login', JSON.stringify({
+    username: 'testuser', password: 'testpass',
+  }), { headers: { 'Content-Type': 'application/json' } });
+  return { token: loginRes.json('token') };
+}
+
+export default function (data) {
+  http.get('https://api.example.com/items', {
+    headers: { Authorization: `Bearer ${data.token}` },
+  });
+}
+
+export function teardown(data) {
+  http.post('https://api.example.com/logout', null, {
+    headers: { Authorization: `Bearer ${data.token}` },
+  });
+}
+```
+
+## Protocol-Specific Guides
+
+Choose the protocol matching your API:
+
+- **HTTP/REST API**: See [reference/http.md](reference/http.md) — GET/POST/PUT/DELETE, authentication (Basic, Bearer, OAuth, API Key), CRUD patterns, batch requests, file uploads, correlation, cookie handling, HTML forms
+- **gRPC**: See [reference/grpc.md](reference/grpc.md) — Client setup, proto loading, unary/streaming calls, metadata, status codes
+- **WebSocket**: See [reference/websocket.md](reference/websocket.md) — Connection lifecycle, message handling, event-driven patterns, binary data
+
+## Data Parameterization
+
+For loading test data from external files and generating dynamic data:
+
+See [reference/data-parameterization.md](reference/data-parameterization.md) — SharedArray, CSV/JSON loading, per-VU data, environment variables, dynamic data generation
+
+## Checks
+
+Checks are assertions that do not stop execution on failure. They track pass/fail rates as metrics.
+
+```javascript
+import { check } from 'k6';
+
+check(res, {
+  'status is 200': (r) => r.status === 200,
+  'body contains expected': (r) => r.body.includes('success'),
+  'response is JSON': (r) => r.headers['Content-Type'].includes('application/json'),
+  'has required field': (r) => r.json('data.id') !== undefined,
+});
+```
+
+Combine checks with thresholds to enforce pass/fail:
+
+```javascript
+export const options = {
+  thresholds: {
+    checks: ['rate>0.99'], // 99% of checks must pass
+  },
+};
+```
+
+## Basic Thresholds
+
+```javascript
+export const options = {
+  thresholds: {
+    http_req_duration: ['p(95)<500', 'p(99)<1000'],  // 95th percentile < 500ms
+    http_req_failed: ['rate<0.01'],                    // Error rate < 1%
+    http_reqs: ['rate>100'],                           // At least 100 RPS
+    checks: ['rate>0.99'],                             // 99% checks pass
+  },
+};
+```
+
+## Common Patterns
+
+### Tags for Filtering
+
+```javascript
+const res = http.get('https://api.example.com/users', {
+  tags: { name: 'GetUsers', type: 'api' },
+});
+```
+
+### Groups for Organization
+
+```javascript
+import { group } from 'k6';
+
+export default function () {
+  group('User API', function () {
+    http.get('https://api.example.com/users');
+    http.get('https://api.example.com/users/1');
+  });
+
+  group('Product API', function () {
+    http.get('https://api.example.com/products');
+  });
+}
+```
+
+### Sleep Between Iterations
+
+```javascript
+import { sleep } from 'k6';
+
+export default function () {
+  // test logic...
+  sleep(Math.random() * 3 + 1); // Random 1-4 second pause (realistic user think time)
+}
+```
+
+### Custom Metrics
+
+```javascript
+import { Trend, Counter, Rate } from 'k6/metrics';
+
+const apiLatency = new Trend('api_latency');
+const apiErrors = new Counter('api_errors');
+const apiSuccessRate = new Rate('api_success_rate');
+
+export default function () {
+  const res = http.get('https://api.example.com/data');
+  apiLatency.add(res.timings.duration);
+  apiSuccessRate.add(res.status === 200);
+  if (res.status !== 200) apiErrors.add(1);
+}
+```
+
+## Script Generation Workflow
+
+When generating a k6 test script, follow this process:
+
+1. **Identify the target**: URL, protocol (HTTP/gRPC/WebSocket), endpoints
+2. **Determine authentication**: Does the API require auth? What type? Generate setup() for token/session acquisition
+3. **Define test data**: What parameters vary? Load from CSV/JSON or generate dynamically
+4. **Write the default function**: Main test logic with requests, checks, and sleeps
+5. **Configure options**: VUs, duration, thresholds based on test goals
+6. **Add organization**: Use groups, tags, and custom metrics as needed
+
+## Related Skills
+
+- For advanced load profile configuration (executors, VU patterns, multi-scenario): `/k6:designing-test-scenarios`
+- For interpreting test output and optimizing performance: `/k6:analyzing-test-results`
+- To generate tests from existing API source code: `/k6:generating-tests-from-code`
+- To generate tests from OpenAPI specifications: `/k6:generating-tests-from-openapi`

package/skills/generating-api-load-tests/reference/data-parameterization.md

@@ -0,0 +1,343 @@
+# k6 Data Parameterization Reference
+
+## Overview
+
+Data parameterization allows k6 tests to use external data files, environment variables, and dynamically generated data. This makes tests more realistic and avoids hardcoded values.
+
+## SharedArray
+
+`SharedArray` stores data once in memory and shares it across all VUs. Essential for large datasets to avoid excessive memory usage.
+
+```javascript
+import { SharedArray } from 'k6/data';
+
+// Must be created in init context
+const users = new SharedArray('users', function () {
+  return JSON.parse(open('./users.json'));
+});
+
+export default function () {
+  // Access by index (read-only)
+  const user = users[Math.floor(Math.random() * users.length)];
+  console.log(user.name, user.email);
+}
+```
+
+### SharedArray Rules
+
+- **Must be in init context** (top-level code, not inside default/setup)
+- **Load data inside constructor function** — not before it
+- **Read-only** — cannot modify after construction
+- **Supported operations**: `length`, `[index]`, `for...of` loops
+- **Do NOT** use `.filter()`, `.map()`, `.forEach()` on SharedArray (creates regular array, defeats purpose)
+- **Do NOT** pass SharedArray from `setup()` to `default()` (gets marshalled)
+- **Do NOT** `JSON.stringify()` the entire array (creates regular copy)
+
+```javascript
+// CORRECT: Load and filter inside constructor
+const activeUsers = new SharedArray('active-users', function () {
+  const all = JSON.parse(open('./users.json'));
+  return all.filter(u => u.active); // Filter returns regular array, stored as SharedArray
+});
+
+// WRONG: Loading outside constructor
+const rawData = open('./users.json'); // Loaded for every VU
+const users = new SharedArray('users', function () {
+  return JSON.parse(rawData); // rawData already duplicated
+});
+```
+
+## CSV Files
+
+### Using k6/experimental/csv (Native)
+
+> **Note:** These modules are experimental and may change in future k6 versions. Check [k6 release notes](https://grafana.com/docs/k6/latest/release-notes/) for graduation status.
+
+```javascript
+import { open } from 'k6/experimental/fs';
+import csv from 'k6/experimental/csv';
+import { SharedArray } from 'k6/data';
+
+// Full parse into SharedArray
+const csvFile = open('./data.csv');
+const data = new SharedArray('csv-data', function () {
+  return csv.parse(csvFile, { delimiter: ',', skipFirstLine: false });
+});
+
+export default function () {
+  const row = data[0]; // Access row as object (column headers as keys)
+}
+```
+
+### Using Papa Parse (jslib)
+
+```javascript
+import papaparse from 'https://jslib.k6.io/papaparse/5.1.1/index.js';
+import { SharedArray } from 'k6/data';
+
+const csvData = new SharedArray('csv', function () {
+  return papaparse.parse(open('./data.csv'), { header: true }).data;
+});
+
+export default function () {
+  const record = csvData[Math.floor(Math.random() * csvData.length)];
+  console.log(record.username, record.password);
+}
+```
+
+### CSV File Example
+
+```csv
+username,password,email
+user1,pass1,user1@test.com
+user2,pass2,user2@test.com
+user3,pass3,user3@test.com
+```
+
+## JSON Files
+
+```javascript
+import { SharedArray } from 'k6/data';
+
+const testData = new SharedArray('json-data', function () {
+  return JSON.parse(open('./test-data.json'));
+});
+
+export default function () {
+  const item = testData[__ITER % testData.length]; // Sequential per iteration
+  console.log(item.name);
+}
+```
+
+### JSON File Example
+
+```json
+[
+  { "id": 1, "name": "Item A", "price": 29.99 },
+  { "id": 2, "name": "Item B", "price": 49.99 },
+  { "id": 3, "name": "Item C", "price": 19.99 }
+]
+```
+
+## Data Access Patterns
+
+### Random Selection
+
+```javascript
+const item = data[Math.floor(Math.random() * data.length)];
+```
+
+### Sequential Per Iteration (Across All VUs)
+
+```javascript
+import exec from 'k6/execution';
+
+const item = data[exec.scenario.iterationInTest % data.length];
+```
+
+### Unique Per VU
+
+```javascript
+import exec from 'k6/execution';
+
+// Each VU gets a different data item
+const item = data[exec.vu.idInTest - 1]; // VU IDs are 1-based
+```
+
+### Sequential Per VU Iteration
+
+```javascript
+import exec from 'k6/execution';
+
+// Each VU cycles through data independently
+const item = data[exec.vu.iterationInInstance % data.length];
+```
+
+### Unique Per Iteration (No Repeats)
+
+```javascript
+import exec from 'k6/execution';
+
+// Each iteration gets unique data (requires enough data rows)
+const item = data[exec.scenario.iterationInTest];
+if (!item) {
+  console.warn('Ran out of test data');
+  return;
+}
+```
+
+## Environment Variables
+
+### Passing Variables
+
+```bash
+# Via command line
+k6 run -e BASE_URL=https://staging.example.com -e API_KEY=abc123 script.js
+
+# Via k6 options environment variable
+K6_VUS=10 K6_DURATION=30s k6 run script.js
+```
+
+### Accessing Variables
+
+```javascript
+const BASE_URL = __ENV.BASE_URL || 'https://api.example.com';
+const API_KEY = __ENV.API_KEY;
+
+export default function () {
+  http.get(`${BASE_URL}/users`, {
+    headers: { 'X-API-Key': API_KEY },
+  });
+}
+```
+
+## Dynamic Data Generation
+
+### Using xk6-faker Extension
+
+```javascript
+import faker from 'k6/x/faker';
+
+export default function () {
+  const user = {
+    name: faker.person.firstName() + ' ' + faker.person.lastName(),
+    email: faker.internet.email(),
+    phone: faker.phone.number(),
+    address: faker.location.streetAddress(),
+  };
+
+  http.post('https://api.example.com/users',
+    JSON.stringify(user),
+    { headers: { 'Content-Type': 'application/json' } }
+  );
+}
+```
+
+### Manual Generation
+
+```javascript
+function randomString(length) {
+  const chars = 'abcdefghijklmnopqrstuvwxyz0123456789';
+  let result = '';
+  for (let i = 0; i < length; i++) {
+    result += chars.charAt(Math.floor(Math.random() * chars.length));
+  }
+  return result;
+}
+
+function randomInt(min, max) {
+  return Math.floor(Math.random() * (max - min + 1)) + min;
+}
+
+export default function () {
+  const payload = {
+    username: `user_${randomString(8)}`,
+    age: randomInt(18, 65),
+    score: Math.random() * 100,
+    timestamp: new Date().toISOString(),
+  };
+}
+```
+
+## File Reading with open()
+
+```javascript
+// Text file (default)
+const textData = open('./data.txt');
+
+// Binary file
+const binaryData = open('./image.png', 'b');
+
+// JSON file
+const jsonData = JSON.parse(open('./config.json'));
+
+// CSV file (raw text)
+const csvRaw = open('./data.csv');
+```
+
+**Rules for `open()`:**
+- Must be called in init context (top-level code)
+- Cannot be called inside `default()`, `setup()`, or `teardown()`
+- Paths are relative to the script location
+- Use mode `'b'` for binary files (returns ArrayBuffer)
+
+## Complete Example: Parameterized API Test
+
+```javascript
+import http from 'k6/http';
+import { check, sleep } from 'k6';
+import { SharedArray } from 'k6/data';
+import exec from 'k6/execution';
+
+const users = new SharedArray('users', function () {
+  return JSON.parse(open('./users.json'));
+  // Expected format: [{ "username": "user1", "password": "pass1" }, ...]
+});
+
+const products = new SharedArray('products', function () {
+  return JSON.parse(open('./products.json'));
+  // Expected format: [{ "id": 1, "name": "Product A" }, ...]
+});
+
+const BASE_URL = __ENV.BASE_URL || 'https://api.example.com';
+
+export const options = {
+  scenarios: {
+    browse_and_buy: {
+      executor: 'ramping-vus',
+      startVUs: 0,
+      stages: [
+        { duration: '1m', target: 20 },
+        { duration: '3m', target: 20 },
+        { duration: '1m', target: 0 },
+      ],
+    },
+  },
+  thresholds: {
+    http_req_duration: ['p(95)<800'],
+    http_req_failed: ['rate<0.05'],
+  },
+};
+
+export function setup() {
+  // Login with first user to verify API is reachable
+  const res = http.post(`${BASE_URL}/auth/login`,
+    JSON.stringify(users[0]),
+    { headers: { 'Content-Type': 'application/json' } }
+  );
+  check(res, { 'login works': (r) => r.status === 200 });
+}
+
+export default function () {
+  // Each VU uses a different user
+  const user = users[exec.vu.idInTest % users.length];
+
+  // Login
+  const loginRes = http.post(`${BASE_URL}/auth/login`,
+    JSON.stringify(user),
+    { headers: { 'Content-Type': 'application/json' } }
+  );
+  const token = loginRes.json('token');
+  const authHeaders = {
+    'Content-Type': 'application/json',
+    'Authorization': `Bearer ${token}`,
+  };
+
+  // Browse random product
+  const product = products[Math.floor(Math.random() * products.length)];
+  const productRes = http.get(`${BASE_URL}/products/${product.id}`, {
+    headers: authHeaders,
+    tags: { name: 'GetProduct' },
+  });
+  check(productRes, { 'product loaded': (r) => r.status === 200 });
+
+  // Add to cart
+  const cartRes = http.post(`${BASE_URL}/cart/items`,
+    JSON.stringify({ productId: product.id, quantity: 1 }),
+    { headers: authHeaders, tags: { name: 'AddToCart' } }
+  );
+  check(cartRes, { 'added to cart': (r) => r.status === 201 });
+
+  sleep(Math.random() * 2 + 1); // Realistic think time
+}
+```