@assertrx/dino 1.0.10 → 1.0.12

package/skills/generating-api-load-tests/reference/grpc.md

@@ -0,0 +1,315 @@
+# k6 gRPC API Reference
+
+## Overview
+
+k6 supports gRPC load testing via the `k6/net/grpc` module. Supports unary RPCs, client/server/bidirectional streaming, TLS, metadata, and server reflection.
+
+## Quick Start
+
+```javascript
+import grpc from 'k6/net/grpc';
+import { check, sleep } from 'k6';
+
+const client = new grpc.Client();
+client.load(['definitions'], 'hello.proto'); // Load in init context
+
+export const options = {
+  vus: 5,
+  duration: '30s',
+  thresholds: {
+    grpc_req_duration: ['p(95)<500'],
+  },
+};
+
+export default function () {
+  client.connect('localhost:50051', { plaintext: true });
+
+  const response = client.invoke('hello.HelloService/SayHello', {
+    greeting: 'k6',
+  });
+
+  check(response, {
+    'status is OK': (r) => r && r.status === grpc.StatusOK,
+    'message contains greeting': (r) => r && r.message.reply.includes('k6'),
+  });
+
+  client.close();
+  sleep(1);
+}
+```
+
+## Client Setup
+
+### Creating and Loading Protos
+
+```javascript
+const client = new grpc.Client();
+
+// Load from proto files (must be in init context)
+client.load(['path/to/import/dir'], 'service.proto');
+client.load([], 'another.proto'); // No additional import paths
+
+// Load from compiled protoset file
+client.loadProtoset('path/to/service.protoset');
+```
+
+### Connecting
+
+```javascript
+// Plaintext (no TLS)
+client.connect('localhost:50051', { plaintext: true });
+
+// TLS with default settings
+client.connect('api.example.com:443');
+
+// TLS with custom certificates
+client.connect('api.example.com:443', {
+  tls: {
+    cacerts: open('ca.pem'),       // CA certificate
+    cert: open('client.pem'),       // Client certificate
+    key: open('client-key.pem'),    // Client key
+    password: 'keyfile-password',   // Key password (optional)
+  },
+});
+
+// With server reflection (no proto files needed)
+client.connect('localhost:50051', {
+  plaintext: true,
+  reflect: true,
+});
+
+// With timeout
+client.connect('localhost:50051', {
+  plaintext: true,
+  timeout: '10s',
+});
+
+// Max message sizes
+client.connect('localhost:50051', {
+  plaintext: true,
+  maxReceiveSize: 16 * 1024 * 1024, // 16MB (default 4MB)
+  maxSendSize: 16 * 1024 * 1024,
+});
+```
+
+## Connection Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `plaintext` | boolean | `false` | Use insecure connection (no TLS) |
+| `reflect` | boolean | `false` | Use gRPC server reflection |
+| `reflectMetadata` | object | `null` | Metadata for reflection request |
+| `timeout` | string/number | `'60s'` | Connection timeout |
+| `maxReceiveSize` | number | 4MB | Max message size to receive |
+| `maxSendSize` | number | ~2GB | Max message size to send |
+| `tls` | object | `null` | TLS settings (cert, key, password, cacerts) |
+
+## Unary RPC Calls
+
+```javascript
+// Basic invoke
+const response = client.invoke('package.Service/Method', {
+  field1: 'value1',
+  field2: 42,
+});
+
+// With metadata (headers)
+const response = client.invoke('package.Service/Method', requestMessage, {
+  metadata: {
+    'authorization': 'Bearer token123',
+    'x-request-id': 'abc-123',
+    'bin-data-bin': encoding.b64encode('binary data'), // Binary metadata (key ends with -bin)
+  },
+});
+
+// With custom tags and timeout
+const response = client.invoke('package.Service/Method', requestMessage, {
+  tags: { name: 'MyRPC' },
+  timeout: '5s',
+});
+
+// Async invoke
+const promise = client.asyncInvoke('package.Service/Method', requestMessage);
+// ... do other work ...
+const response = await promise;
+```
+
+## Invoke Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `metadata` | object | Custom metadata headers |
+| `tags` | object | Custom metric tags |
+| `timeout` | string/number | Request timeout |
+| `authority` | string | `:authority` pseudo-header override |
+| `discardResponseMessage` | boolean | Discard response to reduce memory |
+
+## Response Object
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `status` | number | gRPC status code |
+| `message` | object | Response message as JSON (null if error) |
+| `headers` | object | Response metadata headers |
+| `trailers` | object | Response metadata trailers |
+| `error` | object | Error details (if status != OK) |
+
+## gRPC Status Codes
+
+| Constant | Code | Description |
+|----------|------|-------------|
+| `grpc.StatusOK` | 0 | Success |
+| `grpc.StatusCanceled` | 1 | Operation cancelled |
+| `grpc.StatusUnknown` | 2 | Unknown error |
+| `grpc.StatusInvalidArgument` | 3 | Invalid argument |
+| `grpc.StatusDeadlineExceeded` | 4 | Deadline exceeded |
+| `grpc.StatusNotFound` | 5 | Resource not found |
+| `grpc.StatusAlreadyExists` | 6 | Resource already exists |
+| `grpc.StatusPermissionDenied` | 7 | Permission denied |
+| `grpc.StatusResourceExhausted` | 8 | Resource exhausted |
+| `grpc.StatusFailedPrecondition` | 9 | Failed precondition |
+| `grpc.StatusAborted` | 10 | Operation aborted |
+| `grpc.StatusOutOfRange` | 11 | Out of range |
+| `grpc.StatusUnimplemented` | 12 | Not implemented |
+| `grpc.StatusInternal` | 13 | Internal error |
+| `grpc.StatusUnavailable` | 14 | Service unavailable |
+| `grpc.StatusDataLoss` | 15 | Data loss |
+| `grpc.StatusUnauthenticated` | 16 | Unauthenticated |
+
+## Streaming
+
+### Client Streaming
+
+```javascript
+const stream = new grpc.Stream(client, 'package.Service/ClientStreamMethod');
+
+stream.on('data', (response) => {
+  check(response, {
+    'stream response OK': (r) => r.status === grpc.StatusOK,
+  });
+});
+
+stream.on('error', (err) => {
+  console.error('Stream error:', JSON.stringify(err));
+});
+
+stream.on('end', () => {
+  console.log('Stream ended');
+});
+
+// Send multiple messages
+stream.write({ data: 'message 1' });
+stream.write({ data: 'message 2' });
+stream.write({ data: 'message 3' });
+stream.end(); // Signal end of client stream
+```
+
+### Server Streaming
+
+```javascript
+const stream = new grpc.Stream(client, 'package.Service/ServerStreamMethod');
+
+stream.on('data', (message) => {
+  console.log('Received:', JSON.stringify(message));
+});
+
+stream.on('error', (err) => {
+  console.error('Error:', JSON.stringify(err));
+});
+
+stream.on('end', () => {
+  console.log('All messages received');
+});
+
+// Send single request to start server stream
+stream.write({ query: 'search term' });
+```
+
+### Bidirectional Streaming
+
+```javascript
+const stream = new grpc.Stream(client, 'package.Service/BidiStreamMethod', {
+  metadata: { 'authorization': 'Bearer token123' },
+});
+
+stream.on('data', (message) => {
+  console.log('Server:', JSON.stringify(message));
+  // Respond to server messages
+  if (message.needsReply) {
+    stream.write({ reply: 'acknowledged' });
+  }
+});
+
+stream.on('error', (err) => {
+  console.error('Error:', JSON.stringify(err));
+});
+
+stream.on('end', () => {
+  console.log('Stream ended');
+});
+
+stream.write({ action: 'subscribe', topic: 'updates' });
+```
+
+## Stream API
+
+| Method/Event | Description |
+|-------------|-------------|
+| `new grpc.Stream(client, url, [params])` | Create stream |
+| `stream.write(message)` | Send message to server |
+| `stream.end()` | Signal end of client messages |
+| `stream.on('data', handler)` | Handle incoming messages |
+| `stream.on('error', handler)` | Handle errors |
+| `stream.on('end', handler)` | Handle stream completion |
+
+## Complete Example: Authenticated gRPC Test
+
+```javascript
+import grpc from 'k6/net/grpc';
+import { check, sleep } from 'k6';
+
+const client = new grpc.Client();
+client.load(['proto'], 'user_service.proto');
+
+export const options = {
+  scenarios: {
+    grpc_test: {
+      executor: 'constant-arrival-rate',
+      rate: 50,
+      timeUnit: '1s',
+      duration: '1m',
+      preAllocatedVUs: 20,
+    },
+  },
+  thresholds: {
+    grpc_req_duration: ['p(95)<300', 'p(99)<500'],
+  },
+};
+
+export function setup() {
+  client.connect('auth.example.com:443');
+  const authRes = client.invoke('auth.AuthService/Login', {
+    username: 'loadtest',
+    password: 'secret',
+  });
+  client.close();
+  return { token: authRes.message.token };
+}
+
+export default function (data) {
+  client.connect('api.example.com:443');
+
+  const res = client.invoke('user.UserService/GetUser', { id: 1 }, {
+    metadata: { authorization: `Bearer ${data.token}` },
+    tags: { name: 'GetUser' },
+  });
+
+  check(res, {
+    'status OK': (r) => r && r.status === grpc.StatusOK,
+    'user found': (r) => r && r.message !== null,
+  });
+
+  client.close();
+  sleep(0.5);
+}
+```

package/skills/generating-api-load-tests/reference/http.md

@@ -0,0 +1,380 @@
+# k6 HTTP API Reference
+
+## HTTP Methods
+
+```javascript
+import http from 'k6/http';
+
+http.get(url, [params])                    // GET request
+http.post(url, [body], [params])           // POST request
+http.put(url, [body], [params])            // PUT request
+http.patch(url, [body], [params])          // PATCH request
+http.del(url, [body], [params])            // DELETE request
+http.head(url, [params])                   // HEAD request
+http.options(url, [body], [params])        // OPTIONS request
+http.request(method, url, [body], [params]) // Any HTTP method
+http.asyncRequest(method, url, [body], [params]) // Async (returns Promise)
+```
+
+## Request Parameters (Params Object)
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `auth` | string | `'basic'`, `'digest'`, or `'ntlm'` |
+| `cookies` | object | Request-scoped cookies `{ name: 'value' }` or `{ name: { value: 'v', replace: true } }` |
+| `headers` | object | HTTP headers `{ 'Content-Type': 'application/json' }` |
+| `jar` | CookieJar | Override default VU cookie jar |
+| `redirects` | number | Max redirects to follow (default: follow all) |
+| `tags` | object | Custom metric tags `{ name: 'MyRequest' }` |
+| `timeout` | string/number | Max wait time (default: `'60s'`) |
+| `compression` | string | `'gzip'`, `'deflate'`, `'br'`, `'zstd'` or combinations |
+| `responseType` | string | `'text'` (default), `'binary'`, or `'none'` |
+| `responseCallback` | function | Custom response callback (e.g., `http.expectedStatuses(200, 201)`) |
+
+## Response Object
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `status` | number | HTTP status code |
+| `statusText` | string | HTTP status text |
+| `body` | string | Response body |
+| `headers` | object | Response headers (canonical key format) |
+| `cookies` | object | Response cookies with metadata |
+| `error` | string | Error message (non-HTTP errors) |
+| `error_code` | number | Error code |
+| `proto` | string | HTTP protocol (`'HTTP/1.0'`, `'HTTP/1.1'`, `'HTTP/2.0'`) |
+| `remote_ip` | string | Server IP address |
+| `remote_port` | number | Server port number |
+| `url` | string | Final URL (after redirects) |
+| `request` | object | Request details (body, cookies, headers, method, url) |
+| `timings` | object | See Timings below |
+| `tls_version` | string | TLS version (e.g., `'tls1.2'`) |
+| `tls_cipher_suite` | string | Cipher suite used |
+
+### Timings
+
+| Property | Description |
+|----------|-------------|
+| `timings.blocked` | Time spent blocked before starting request (DNS lookup, connection queue) |
+| `timings.connecting` | Time spent establishing TCP connection |
+| `timings.tls_handshaking` | Time spent on TLS handshake |
+| `timings.sending` | Time spent sending request body |
+| `timings.waiting` | Time spent waiting for server response (TTFB) |
+| `timings.receiving` | Time spent receiving response body |
+| `timings.duration` | Total request time (sending + waiting + receiving) |
+
+### Methods
+
+```javascript
+res.json()                    // Parse body as JSON
+res.json('path.to.field')     // Parse JSON with gjson selector
+res.html()                    // Parse body as HTML (returns Selection)
+res.submitForm({              // Submit an HTML form
+  formSelector: 'form',
+  fields: { username: 'test' },
+  submitSelector: '[type="submit"]',
+  params: {},
+})
+res.clickLink({ selector: 'a' })  // Click a link in HTML response
+```
+
+## Authentication Patterns
+
+### Basic Auth
+
+```javascript
+// Method 1: Using auth param
+const res = http.get('https://api.example.com/protected', {
+  headers: {
+    Authorization: 'Basic ' + encoding.b64encode('user:pass'),
+  },
+});
+
+// Method 2: Using built-in auth
+const res = http.get('https://user:pass@api.example.com/protected', {
+  auth: 'basic',
+});
+```
+
+### Bearer Token
+
+```javascript
+export function setup() {
+  const loginRes = http.post('https://api.example.com/auth/login',
+    JSON.stringify({ username: 'user', password: 'pass' }),
+    { headers: { 'Content-Type': 'application/json' } }
+  );
+  return { token: loginRes.json('access_token') };
+}
+
+export default function (data) {
+  const params = {
+    headers: { Authorization: `Bearer ${data.token}` },
+  };
+  http.get('https://api.example.com/protected', params);
+}
+```
+
+### OAuth 2.0 (Client Credentials)
+
+```javascript
+import encoding from 'k6/encoding';
+
+export function setup() {
+  const res = http.post('https://auth.example.com/oauth/token',
+    'grant_type=client_credentials&scope=read',
+    {
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+        Authorization: `Basic ${encoding.b64encode('client_id:client_secret')}`,
+      },
+    }
+  );
+  return { token: res.json('access_token') };
+}
+
+export default function (data) {
+  http.get('https://api.example.com/resource', {
+    headers: { Authorization: `Bearer ${data.token}` },
+  });
+}
+```
+
+### API Key
+
+```javascript
+// In header
+http.get('https://api.example.com/data', {
+  headers: { 'X-API-Key': 'your-api-key-here' },
+});
+
+// In query parameter
+http.get('https://api.example.com/data?api_key=your-api-key-here');
+```
+
+### Cookie-Based Session
+
+Note: `setup()` runs in a separate VU, so cookies set during `setup()` do **not** transfer to VUs running `default()`. For cookie-based auth, login inside `default()`:
+
+```javascript
+export default function () {
+  // Login per VU — cookies are stored in this VU's cookie jar
+  const loginRes = http.post('https://app.example.com/login', {
+    username: 'user',
+    password: 'pass',
+  });
+
+  // Subsequent requests in this VU automatically include session cookies
+  http.get('https://app.example.com/dashboard');
+}
+```
+
+## CRUD Patterns
+
+```javascript
+import http from 'k6/http';
+import { check } from 'k6';
+
+const BASE_URL = 'https://api.example.com';
+const HEADERS = { 'Content-Type': 'application/json' };
+
+export default function () {
+  // CREATE
+  const createRes = http.post(`${BASE_URL}/items`,
+    JSON.stringify({ name: 'Test Item', value: 42 }),
+    { headers: HEADERS }
+  );
+  check(createRes, { 'created': (r) => r.status === 201 });
+  const itemId = createRes.json('id');
+
+  // READ
+  const getRes = http.get(`${BASE_URL}/items/${itemId}`);
+  check(getRes, { 'fetched': (r) => r.status === 200 });
+
+  // UPDATE
+  const updateRes = http.put(`${BASE_URL}/items/${itemId}`,
+    JSON.stringify({ name: 'Updated Item', value: 99 }),
+    { headers: HEADERS }
+  );
+  check(updateRes, { 'updated': (r) => r.status === 200 });
+
+  // DELETE
+  const deleteRes = http.del(`${BASE_URL}/items/${itemId}`);
+  check(deleteRes, { 'deleted': (r) => r.status === 204 });
+}
+```
+
+## Batch Requests
+
+Send multiple requests in parallel:
+
+```javascript
+// Array format
+const responses = http.batch([
+  ['GET', 'https://api.example.com/users'],
+  ['GET', 'https://api.example.com/products'],
+  ['POST', 'https://api.example.com/logs', JSON.stringify({ event: 'test' }), { headers: HEADERS }],
+]);
+
+// Named object format (easier to reference results)
+const responses = http.batch({
+  users: { method: 'GET', url: 'https://api.example.com/users' },
+  products: { method: 'GET', url: 'https://api.example.com/products' },
+});
+check(responses.users, { 'users ok': (r) => r.status === 200 });
+check(responses.products, { 'products ok': (r) => r.status === 200 });
+```
+
+## File Uploads
+
+### Simple File Upload
+
+```javascript
+import http from 'k6/http';
+
+const file = open('test-file.png', 'b'); // Binary mode, in init context
+
+export default function () {
+  const res = http.post('https://api.example.com/upload', {
+    file: http.file(file, 'test-file.png', 'image/png'),
+  });
+}
+```
+
+### Multipart Form Data
+
+```javascript
+const imgFile = open('photo.jpg', 'b');
+const docFile = open('report.pdf', 'b');
+
+export default function () {
+  const res = http.post('https://api.example.com/upload', {
+    profile_photo: http.file(imgFile, 'photo.jpg', 'image/jpeg'),
+    document: http.file(docFile, 'report.pdf', 'application/pdf'),
+    description: 'Test upload',
+  });
+}
+```
+
+## Correlation (Extracting Dynamic Values)
+
+### From JSON Response
+
+```javascript
+const res = http.get('https://api.example.com/session');
+const sessionId = res.json('data.session_id');
+const items = res.json('data.items.#.id'); // Array of IDs (gjson syntax)
+
+http.get(`https://api.example.com/data?session=${sessionId}`);
+```
+
+### From HTML Response
+
+```javascript
+const res = http.get('https://app.example.com/form');
+const doc = res.html();
+const csrfToken = doc.find('input[name="csrf_token"]').attr('value');
+
+http.post('https://app.example.com/submit', {
+  csrf_token: csrfToken,
+  data: 'test',
+});
+```
+
+### From Headers
+
+```javascript
+const res = http.post('https://api.example.com/resource', payload);
+const location = res.headers['Location'];
+http.get(location); // Follow redirect manually
+```
+
+## Cookie Handling
+
+### Manual Cookie Jar
+
+```javascript
+const jar = http.cookieJar();
+
+// Set cookies
+jar.set('https://api.example.com', 'session', 'abc123', {
+  domain: 'api.example.com',
+  path: '/',
+  secure: true,
+  max_age: 3600,
+});
+
+// Get cookies
+const cookies = jar.cookiesForURL('https://api.example.com');
+console.log(cookies.session); // ['abc123']
+
+// Clear cookies
+jar.clear('https://api.example.com');
+
+// Delete specific cookie
+jar.delete('https://api.example.com', 'session');
+```
+
+### Per-Request Cookies
+
+```javascript
+http.get('https://api.example.com/data', {
+  cookies: {
+    session: 'abc123',
+    preference: { value: 'dark', replace: true }, // replace VU jar cookie
+  },
+});
+```
+
+## HTML Form Submission
+
+```javascript
+// Load the page with the form
+const res = http.get('https://app.example.com/login');
+
+// Submit the form
+const submitRes = res.submitForm({
+  formSelector: 'form#login',
+  fields: {
+    username: 'testuser',
+    password: 'testpass',
+  },
+  submitSelector: 'button[type="submit"]',
+});
+```
+
+## Expected Statuses
+
+```javascript
+// Mark specific statuses as expected (affects http_req_failed metric)
+const res = http.get('https://api.example.com/maybe-404', {
+  responseCallback: http.expectedStatuses(200, 404),
+});
+
+// Range of statuses
+http.get(url, {
+  responseCallback: http.expectedStatuses({ min: 200, max: 299 }),
+});
+
+// Set globally
+http.setResponseCallback(http.expectedStatuses({ min: 200, max: 399 }));
+```
+
+## URL Grouping with Name Tag
+
+Prevent dynamic URLs from creating separate metric entries:
+
+```javascript
+// Without grouping: each user ID creates a separate metric
+http.get(`https://api.example.com/users/${userId}`);
+
+// With grouping: all requests grouped under one metric
+http.get(`https://api.example.com/users/${userId}`, {
+  tags: { name: 'GetUser' },
+});
+
+// Using http.url template literal (auto-groups)
+http.get(http.url`https://api.example.com/users/${userId}`);
+```