@assertrx/dino 1.0.10 → 1.0.11

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

@@ -0,0 +1,369 @@
+# k6 WebSocket API Reference
+
+## Overview
+
+k6 provides two WebSocket modules:
+- **`k6/websockets`** (recommended) — Uses global event loop, supports multiple concurrent connections per VU
+- **`k6/ws`** (legacy) — Uses local event loop, one connection per VU
+
+This reference covers the recommended `k6/websockets` module.
+
+## Quick Start
+
+```javascript
+import { WebSocket } from 'k6/websockets';
+import { check } from 'k6';
+
+export const options = {
+  vus: 10,
+  duration: '30s',
+};
+
+export default function () {
+  const url = 'wss://echo.websocket.org';
+  const ws = new WebSocket(url);
+
+  ws.onopen = () => {
+    console.log('Connected');
+    ws.send('Hello from k6!');
+  };
+
+  ws.onmessage = (event) => {
+    console.log('Received:', event.data);
+    ws.close();
+  };
+
+  ws.onerror = (event) => {
+    console.error('Error:', event.error());
+  };
+
+  ws.onclose = (event) => {
+    console.log('Disconnected:', event.code);
+  };
+}
+```
+
+## Creating a WebSocket Connection
+
+```javascript
+import { WebSocket } from 'k6/websockets';
+
+// Basic connection
+const ws = new WebSocket('wss://example.com/ws');
+
+// With subprotocols
+const ws = new WebSocket('wss://example.com/ws', ['graphql-ws', 'json']);
+
+// With connection parameters
+const ws = new WebSocket('wss://example.com/ws', null, {
+  headers: {
+    'Authorization': 'Bearer token123',
+    'X-Custom-Header': 'value',
+  },
+  tags: { name: 'MyWebSocket' },
+  jar: http.cookieJar(),        // Custom cookie jar
+  compression: 'deflate',       // Enable compression
+});
+```
+
+## Connection Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `headers` | object | Custom HTTP headers for the initial handshake |
+| `tags` | object | Custom metric tags |
+| `jar` | CookieJar | Custom cookie jar for the handshake |
+| `compression` | string | `'deflate'` for per-message compression |
+
+## WebSocket Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `readyState` | number | `0` CONNECTING, `1` OPEN, `2` CLOSING, `3` CLOSED |
+| `url` | string | Resolved connection URL |
+| `bufferedAmount` | number | Bytes queued but not yet sent |
+| `binaryType` | string | `'blob'` (default) or `'arraybuffer'` |
+
+## Event Handlers
+
+### onopen — Connection Established
+
+```javascript
+ws.onopen = () => {
+  console.log('Connection established');
+  ws.send('Initial message');
+};
+
+// Alternative: addEventListener
+ws.addEventListener('open', (event) => {
+  console.log('Connected');
+});
+```
+
+### onmessage — Message Received
+
+```javascript
+ws.onmessage = (event) => {
+  const data = event.data;
+
+  // Text message
+  if (typeof data === 'string') {
+    const json = JSON.parse(data);
+    console.log('JSON message:', json);
+  }
+};
+
+// Multiple handlers via addEventListener
+ws.addEventListener('message', (event) => {
+  console.log('Handler 1:', event.data);
+});
+ws.addEventListener('message', (event) => {
+  console.log('Handler 2:', event.data);
+});
+```
+
+### onclose — Connection Closed
+
+```javascript
+ws.onclose = (event) => {
+  console.log('Closed with code:', event.code);
+  // Common close codes:
+  // 1000 - Normal closure
+  // 1001 - Going away
+  // 1006 - Abnormal closure (no close frame)
+  // 1011 - Server error
+};
+```
+
+### onerror — Error Occurred
+
+```javascript
+ws.onerror = (event) => {
+  console.error('WebSocket error:', event.error());
+};
+```
+
+### onping / onpong — Ping/Pong Frames
+
+```javascript
+ws.addEventListener('ping', () => {
+  console.log('Received ping from server');
+});
+
+ws.addEventListener('pong', () => {
+  console.log('Received pong from server');
+});
+```
+
+## Sending Messages
+
+```javascript
+// Text message
+ws.send('Hello, server!');
+
+// JSON message
+ws.send(JSON.stringify({ type: 'subscribe', channel: 'updates' }));
+
+// Binary data
+const buffer = new ArrayBuffer(4);
+const view = new Uint8Array(buffer);
+view[0] = 0x01;
+ws.send(buffer);
+```
+
+## Closing Connection
+
+```javascript
+// Normal close
+ws.close();
+
+// Close with code
+ws.close(1000); // Normal closure
+
+// Common close codes:
+// 1000 - Normal
+// 1001 - Going away
+// 1008 - Policy violation
+// 1011 - Server error
+```
+
+## Ping
+
+```javascript
+ws.ping(); // Send ping to server (pong is automatic)
+```
+
+## Patterns
+
+### Request-Response Pattern
+
+```javascript
+export default function () {
+  const ws = new WebSocket('wss://api.example.com/ws');
+  let responseReceived = false;
+
+  ws.onopen = () => {
+    ws.send(JSON.stringify({ action: 'getData', id: 123 }));
+  };
+
+  ws.onmessage = (event) => {
+    const data = JSON.parse(event.data);
+    check(data, {
+      'has result': (d) => d.result !== undefined,
+      'status is success': (d) => d.status === 'success',
+    });
+    responseReceived = true;
+    ws.close();
+  };
+
+  ws.onerror = (event) => {
+    console.error('Error:', event.error());
+  };
+}
+```
+
+### Subscription Pattern (Pub/Sub)
+
+```javascript
+import { setTimeout } from 'k6/timers';
+
+export default function () {
+  const ws = new WebSocket('wss://api.example.com/ws');
+  let messageCount = 0;
+
+  ws.onopen = () => {
+    // Subscribe to channels
+    ws.send(JSON.stringify({ type: 'subscribe', channel: 'prices' }));
+    ws.send(JSON.stringify({ type: 'subscribe', channel: 'trades' }));
+
+    // Close after 10 seconds
+    setTimeout(() => {
+      ws.send(JSON.stringify({ type: 'unsubscribe', channel: 'prices' }));
+      ws.send(JSON.stringify({ type: 'unsubscribe', channel: 'trades' }));
+      ws.close();
+    }, 10000);
+  };
+
+  ws.onmessage = (event) => {
+    messageCount++;
+    const data = JSON.parse(event.data);
+    check(data, {
+      'valid message': (d) => d.channel !== undefined && d.data !== undefined,
+    });
+  };
+}
+```
+
+### Chat/Interactive Pattern
+
+```javascript
+import { setTimeout } from 'k6/timers';
+
+export default function () {
+  const ws = new WebSocket('wss://chat.example.com/ws');
+
+  ws.onopen = () => {
+    ws.send(JSON.stringify({ type: 'join', room: 'loadtest' }));
+
+    // Simulate periodic messages
+    let i = 0;
+    const interval = setInterval(() => {
+      ws.send(JSON.stringify({
+        type: 'message',
+        text: `Hello from VU ${__VU}, message ${i}`,
+      }));
+      i++;
+      if (i >= 5) {
+        clearInterval(interval);
+        ws.send(JSON.stringify({ type: 'leave', room: 'loadtest' }));
+        ws.close();
+      }
+    }, 1000);
+  };
+
+  ws.onmessage = (event) => {
+    const msg = JSON.parse(event.data);
+    if (msg.type === 'message') {
+      console.log(`${msg.user}: ${msg.text}`);
+    }
+  };
+}
+```
+
+### Multiple Concurrent Connections
+
+The `k6/websockets` module supports multiple connections per VU:
+
+```javascript
+export default function () {
+  const ws1 = new WebSocket('wss://api.example.com/stream1');
+  const ws2 = new WebSocket('wss://api.example.com/stream2');
+
+  ws1.onmessage = (event) => {
+    console.log('Stream 1:', event.data);
+  };
+
+  ws2.onmessage = (event) => {
+    console.log('Stream 2:', event.data);
+  };
+
+  ws1.onopen = () => ws1.send('subscribe');
+  ws2.onopen = () => ws2.send('subscribe');
+
+  setTimeout(() => {
+    ws1.close();
+    ws2.close();
+  }, 10000);
+}
+```
+
+## WebSocket Metrics
+
+k6 automatically emits these metrics for WebSocket connections:
+
+| Metric | Type | Description |
+|--------|------|-------------|
+| `ws_connecting` | Trend | Time to establish WebSocket connection |
+| `ws_session_duration` | Trend | Total session duration |
+| `ws_msgs_sent` | Counter | Number of messages sent |
+| `ws_msgs_received` | Counter | Number of messages received |
+| `ws_ping` | Trend | Ping round-trip time |
+| `ws_sessions` | Counter | Number of sessions started |
+
+## Legacy Module (k6/ws)
+
+The `k6/ws` module uses a callback-based pattern with a local event loop:
+
+```javascript
+import ws from 'k6/ws';
+
+export default function () {
+  const res = ws.connect('wss://echo.websocket.org', {}, function (socket) {
+    socket.on('open', () => {
+      socket.send('Hello');
+      socket.setInterval(() => {
+        socket.send('Periodic message');
+      }, 1000);
+      socket.setTimeout(() => {
+        socket.close();
+      }, 5000);
+    });
+
+    socket.on('message', (data) => {
+      console.log('Received:', data);
+    });
+
+    socket.on('close', () => {
+      console.log('Disconnected');
+    });
+  });
+
+  check(res, { 'status is 101': (r) => r && r.status === 101 });
+}
+```
+
+Key differences from `k6/websockets`:
+- Uses callback function wrapping all logic
+- `socket.setInterval()` and `socket.setTimeout()` instead of `k6/timers`
+- Only one connection per VU at a time
+- Returns response object with status 101

package/skills/generating-browser-tests/SKILL.md

@@ -0,0 +1,269 @@
+---
+name: generating-browser-tests
+description: Use when creating k6 browser-based performance tests, testing frontend performance, measuring Web Vitals (LCP, FCP, CLS, INP, TTFB), or automating browser interactions for load testing. Use when the user mentions browser testing, page load testing, E2E performance, or Chromium-based testing with k6.
+---
+
+# Generating k6 Browser Tests
+
+Generate browser-based E2E performance tests using the k6/browser module. Tests real browser interactions with Chromium, measures Web Vitals, and supports hybrid protocol+browser testing.
+
+## Quick Start
+
+```javascript
+import { browser } from 'k6/browser';
+import { check } from 'k6';
+
+export const options = {
+  scenarios: {
+    ui: {
+      executor: 'shared-iterations',
+      iterations: 5,
+      vus: 1,
+      options: {
+        browser: {
+          type: 'chromium',
+        },
+      },
+    },
+  },
+  thresholds: {
+    browser_web_vital_lcp: ['p(90)<2500'],
+    browser_web_vital_fcp: ['p(90)<1800'],
+    browser_web_vital_cls: ['p(95)<0.1'],
+  },
+};
+
+export default async function () {
+  const page = await browser.newPage();
+
+  try {
+    await page.goto('https://example.com');
+    await page.waitForLoadState('networkidle');
+
+    const title = await page.title();
+    check(null, { 'page title loaded': () => title !== '' });
+
+    await page.screenshot({ path: 'screenshot.png' });
+  } finally {
+    await page.close(); // Always close pages
+  }
+}
+```
+
+## Key Concepts
+
+- **All browser functions are `async`** — use `await` and `async function`
+- **Always close pages** — use `try/finally` to ensure `page.close()` is called
+- **Browser type** — only `'chromium'` is supported
+- **Browser scenario** — requires `options.browser.type` in scenario config
+- **Avoid `networkidle`** — `waitForLoadState('networkidle')` may never fire on chatty pages; prefer `'load'` or `locator.waitFor()` when possible
+- **Resource intensive** — browser VUs consume more resources; start with few VUs
+
+## Element Selection
+
+### Locator API (Recommended)
+
+```javascript
+// CSS selector
+const btn = page.locator('button.submit');
+
+// Semantic selectors (preferred for resilience)
+const submitBtn = page.getByRole('button', { name: 'Submit' });
+const email = page.getByLabel('Email');
+const search = page.getByPlaceholder('Search...');
+const heading = page.getByText('Welcome');
+const card = page.getByTestId('user-card');
+```
+
+### Common Interactions
+
+```javascript
+// Click
+await page.locator('button').click();
+
+// Fill text input
+await page.getByLabel('Username').fill('testuser');
+
+// Select dropdown option
+await page.locator('select#country').selectOption('US');
+
+// Checkbox
+await page.getByRole('checkbox', { name: 'Terms' }).check();
+
+// Type character by character (with key events)
+await page.locator('#search').type('search query', { delay: 50 });
+
+// Press key
+await page.locator('#search').press('Enter');
+
+// Hover
+await page.locator('.menu-item').hover();
+```
+
+### Query Element State
+
+```javascript
+const isVisible = await page.locator('.modal').isVisible();
+const isEnabled = await page.locator('button').isEnabled();
+const text = await page.locator('.message').textContent();
+const value = await page.locator('input').inputValue();
+const count = await page.locator('li.item').count();
+```
+
+## Web Vitals
+
+k6/browser automatically collects Core Web Vitals:
+
+| Metric | Name | Good Threshold |
+|--------|------|----------------|
+| `browser_web_vital_lcp` | Largest Contentful Paint | < 2500ms |
+| `browser_web_vital_fcp` | First Contentful Paint | < 1800ms |
+| `browser_web_vital_cls` | Cumulative Layout Shift | < 0.1 |
+| `browser_web_vital_inp` | Interaction to Next Paint | < 200ms |
+| `browser_web_vital_ttfb` | Time to First Byte | < 600ms |
+
+```javascript
+export const options = {
+  thresholds: {
+    'browser_web_vital_lcp': ['p(90)<2500'],
+    'browser_web_vital_fcp': ['p(90)<1800'],
+    'browser_web_vital_cls': ['p(95)<0.1'],
+    'browser_web_vital_inp': ['p(90)<200'],
+  },
+};
+```
+
+## Common Test Patterns
+
+### Login Flow
+
+```javascript
+export default async function () {
+  const page = await browser.newPage();
+  try {
+    await page.goto('https://app.example.com/login');
+
+    await page.getByLabel('Email').fill('test@example.com');
+    await page.getByLabel('Password').fill('password123');
+    await page.getByRole('button', { name: 'Sign in' }).click();
+
+    await page.waitForNavigation();
+
+    check(null, {
+      'redirected to dashboard': () => page.url().includes('/dashboard'),
+    });
+  } finally {
+    await page.close();
+  }
+}
+```
+
+### Form Submission
+
+```javascript
+export default async function () {
+  const page = await browser.newPage();
+  try {
+    await page.goto('https://app.example.com/contact');
+
+    await page.getByLabel('Name').fill('Load Test User');
+    await page.getByLabel('Email').fill('test@example.com');
+    await page.getByLabel('Message').fill('Performance test submission');
+    await page.locator('select#department').selectOption('support');
+    await page.getByRole('checkbox', { name: 'Subscribe' }).check();
+
+    await page.getByRole('button', { name: 'Submit' }).click();
+    await page.waitForLoadState('networkidle');
+
+    const confirmation = await page.locator('.success-message').textContent();
+    check(null, {
+      'form submitted': () => confirmation.includes('Thank you'),
+    });
+  } finally {
+    await page.close();
+  }
+}
+```
+
+### Page Navigation with Screenshots
+
+```javascript
+export default async function () {
+  const page = await browser.newPage();
+  try {
+    await page.goto('https://app.example.com');
+    await page.screenshot({ path: 'home.png', fullPage: true });
+
+    await page.locator('a[href="/products"]').click();
+    await page.waitForNavigation();
+    await page.screenshot({ path: 'products.png' });
+
+    await page.locator('.product-card').first().click();
+    await page.waitForLoadState('networkidle');
+    await page.screenshot({ path: 'product-detail.png' });
+  } finally {
+    await page.close();
+  }
+}
+```
+
+## Hybrid Testing (Browser + Protocol)
+
+Combine browser tests with protocol-level load tests:
+
+```javascript
+import { browser } from 'k6/browser';
+import http from 'k6/http';
+import { check } from 'k6';
+
+export const options = {
+  scenarios: {
+    // High-volume API load
+    api_load: {
+      exec: 'apiTest',
+      executor: 'constant-arrival-rate',
+      rate: 100,
+      timeUnit: '1s',
+      duration: '5m',
+      preAllocatedVUs: 50,
+    },
+    // Low-volume browser tests (resource intensive)
+    browser_test: {
+      exec: 'browserTest',
+      executor: 'constant-vus',
+      vus: 2,
+      duration: '5m',
+      options: { browser: { type: 'chromium' } },
+    },
+  },
+};
+
+export function apiTest() {
+  const res = http.get('https://api.example.com/products');
+  check(res, { 'API 200': (r) => r.status === 200 });
+}
+
+export async function browserTest() {
+  const page = await browser.newPage();
+  try {
+    await page.goto('https://app.example.com');
+    // Browser interactions...
+  } finally {
+    await page.close();
+  }
+}
+```
+
+## Advanced Features
+
+For detailed API reference including BrowserContext, Keyboard, Mouse, Touchscreen, and advanced patterns:
+
+See [reference/browser-api.md](reference/browser-api.md) — Complete Page, Locator, BrowserContext API with all methods and parameters
+
+See [reference/web-vitals.md](reference/web-vitals.md) — Web Vitals metrics explanation, threshold guidance, and custom performance measurement
+
+## Related Skills
+
+- For protocol-level load tests (HTTP, gRPC, WebSocket): `/k6:generating-api-load-tests`
+- For scenario and executor configuration: `/k6:designing-test-scenarios`
+- For interpreting test results: `/k6:analyzing-test-results`