qa-skills 3.0.0

package/skills/qa-k6-writer/references/best-practices.md

@@ -0,0 +1,236 @@
+# k6 Best Practices
+
+## Realistic Load
+
+### Think Time (sleep)
+Simulate user think time between actions to avoid unrealistic burst patterns.
+
+```javascript
+import { sleep } from 'k6';
+
+export default function () {
+  http.get('https://example.com/');
+  sleep(Math.random() * 3 + 1);  // 1–4 seconds
+  http.get('https://example.com/dashboard');
+  sleep(2);
+}
+```
+
+### Ramp Up Gradually
+Avoid instant load spikes; use stages to ramp up and down.
+
+```javascript
+// Good: gradual ramp
+stages: [
+  { duration: '2m', target: 50 },
+  { duration: '5m', target: 50 },
+  { duration: '2m', target: 0 },
+]
+
+// Avoid: instant spike (unless testing spike scenario)
+vus: 500,
+duration: '1m',
+```
+
+---
+
+## Correlation
+
+Extract dynamic values from responses for subsequent requests.
+
+```javascript
+const loginRes = http.post('https://api.example.com/login', JSON.stringify(creds), {
+  headers: { 'Content-Type': 'application/json' },
+});
+const token = loginRes.json('access_token');
+
+const apiRes = http.get('https://api.example.com/protected', {
+  headers: { Authorization: `Bearer ${token}` },
+});
+```
+
+### Session Cookies
+```javascript
+const res = http.get('https://example.com/');
+const cookies = res.cookies;
+// Cookies automatically sent in subsequent requests from same VU
+http.get('https://example.com/dashboard');
+```
+
+---
+
+## Parameterization
+
+### SharedArray (Memory-Efficient)
+Use `SharedArray` for large datasets; data is shared across VUs.
+
+```javascript
+import { SharedArray } from 'k6/data';
+
+const users = new SharedArray('users', function () {
+  return JSON.parse(open('./users.json'));
+});
+
+export default function () {
+  const user = users[__ITER % users.length];
+  // use user
+}
+```
+
+### Regular Array (Small Data)
+```javascript
+const items = JSON.parse(open('./items.json'));
+```
+
+### CSV
+```javascript
+import { SharedArray } from 'k6/data';
+import papaparse from 'https://jslib.k6.io/papaparse/5.1.1/index.js';
+
+const data = new SharedArray('csv', function () {
+  return papaparse.parse(open('./data.csv'), { header: true }).data;
+});
+```
+
+---
+
+## CI Integration
+
+### GitHub Actions
+```yaml
+name: k6 Performance Tests
+on: [push]
+jobs:
+  k6:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: grafana/setup-k6-action@v1
+        with:
+          k6-version: v0.48.0
+      - name: Run k6
+        run: k6 run --out json=results.json tests/load/script.js
+      - name: Upload results
+        uses: actions/upload-artifact@v4
+        with:
+          name: k6-results
+          path: results.json
+```
+
+### Exit Code
+k6 exits with code 0 if all thresholds pass, non-zero if any fail. CI can use this for gating.
+
+```bash
+k6 run script.js
+echo $?  # 0 = pass, 1 = fail
+```
+
+### Threshold Failure
+```yaml
+- name: Run k6
+  run: k6 run script.js
+  # Job fails automatically if thresholds fail
+```
+
+---
+
+## Script Structure
+
+### Default Export
+```javascript
+export default function () {
+  // Main VU logic
+}
+```
+
+### Scenario-Specific Functions
+```javascript
+export const options = {
+  scenarios: {
+    browse: { exec: 'browseFlow', ... },
+    api: { exec: 'apiFlow', ... },
+  },
+};
+
+export function browseFlow() { /* ... */ }
+export function apiFlow() { /* ... */ }
+```
+
+### Setup and Teardown
+```javascript
+export function setup() {
+  // Run once before test; return data for default function
+  return { token: getAuthToken() };
+}
+
+export default function (data) {
+  // Use data.token
+}
+
+export function teardown(data) {
+  // Run once after test
+}
+```
+
+---
+
+## Checks and Thresholds
+
+### Use Both
+- **Checks** — Per-request assertions; track success rate
+- **Thresholds** — Pass/fail the entire run
+
+```javascript
+import { check } from 'k6';
+import http from 'k6/http';
+
+export const options = {
+  thresholds: {
+    checks: ['rate>0.95'],
+    http_req_duration: ['p(95)<200'],
+  },
+};
+
+export default function () {
+  const res = http.get('https://example.com/');
+  check(res, {
+    'status 200': (r) => r.status === 200,
+    'has body': (r) => r.body.length > 0,
+  });
+}
+```
+
+---
+
+## Avoid Anti-Patterns
+
+| Anti-Pattern | Fix |
+| ------------ | --- |
+| No sleep between requests | Add `sleep()` for realistic pacing |
+| Hardcoded URLs/secrets | Use `__ENV` or `options.env` |
+| Single huge default function | Split into `group()` or scenario functions |
+| Ignoring failed requests | Add `http_req_failed` threshold |
+| No thresholds | Define at least `http_req_duration` and `http_req_failed` |
+| Loading large JSON with `open()` in default | Use `SharedArray` for memory efficiency |
+| Testing production without coordination | Use staging; coordinate with ops |
+
+---
+
+## Debugging
+
+### Verbose Output
+```bash
+k6 run --verbose script.js
+```
+
+### Single VU, Single Iteration
+```bash
+k6 run --vus 1 --iterations 1 script.js
+```
+
+### HTTP Debug
+```javascript
+export const options = {
+  httpDebug: 'full',  // Log all HTTP traffic
+};
+```

package/skills/qa-k6-writer/references/config.md

@@ -0,0 +1,219 @@
+# k6 Configuration Reference
+
+## Options Object
+
+The `options` object configures test execution. Place at top of script or pass via CLI.
+
+```javascript
+export const options = {
+  vus: 10,
+  duration: '30s',
+  thresholds: {},
+  scenarios: {},
+  stages: [],
+  tags: {},
+  noConnectionReuse: false,
+  userAgent: 'k6',
+  insecureSkipTLSVerify: false,
+  tlsVersion: { min: 'tls1.2', max: 'tls1.3' },
+};
+```
+
+---
+
+## Scenarios
+
+Define multiple execution patterns in a single test.
+
+```javascript
+export const options = {
+  scenarios: {
+    scenario_name: {
+      executor: 'constant-vus',
+      vus: 10,
+      duration: '5m',
+      exec: 'functionName',
+      startTime: '0s',
+      gracefulStop: '30s',
+      env: { MY_VAR: 'value' },
+      tags: { scenario: 'api' },
+    },
+  },
+};
+```
+
+### Executor Reference
+
+| Executor | Parameters |
+| -------- | ---------- |
+| shared-iterations | `iterations`, `vus`, `maxDuration` |
+| per-vu-iterations | `vus`, `iterations`, `maxDuration` |
+| constant-vus | `vus`, `duration` |
+| ramping-vus | `startVUs`, `stages`, `gracefulRampDown` |
+| constant-arrival-rate | `rate`, `timeUnit`, `duration`, `preAllocatedVUs`, `maxVUs` |
+| ramping-arrival-rate | `startRate`, `timeUnit`, `stages`, `preAllocatedVUs`, `maxVUs` |
+| externally-controlled | `maxVUs`, `duration` |
+
+---
+
+## Stages (Ramping)
+
+Define load profile with time-based stages.
+
+```javascript
+export const options = {
+  stages: [
+    { duration: '2m', target: 50 },   // Ramp up to 50 VUs over 2 min
+    { duration: '5m', target: 50 },   // Stay at 50 VUs for 5 min
+    { duration: '2m', target: 100 },  // Ramp to 100 VUs
+    { duration: '5m', target: 100 },  // Stay at 100 VUs
+    { duration: '2m', target: 0 },    // Ramp down to 0
+  ],
+};
+```
+
+Time units: `s`, `m`, `h`.
+
+---
+
+## Thresholds
+
+Pass/fail criteria for the test run.
+
+```javascript
+export const options = {
+  thresholds: {
+    http_req_duration: ['p(95)<200', 'p(99)<500'],
+    http_req_failed: ['rate<0.01'],
+    checks: ['rate>0.95'],
+    'http_req_duration{name:api}': ['p(95)<300'],
+  },
+};
+```
+
+### Percentile Syntax
+- `p(50)` — Median
+- `p(90)` — 90th percentile
+- `p(95)` — 95th percentile
+- `p(99)` — 99th percentile
+
+---
+
+## Output Formats
+
+### JSON
+```bash
+k6 run --out json=results.json script.js
+```
+
+### CSV
+```bash
+k6 run --out csv=results.csv script.js
+```
+
+### InfluxDB
+```bash
+k6 run --out influxdb=http://localhost:8086/k6 script.js
+```
+
+### Prometheus (via k6 Prometheus extension)
+```bash
+k6 run --out experimental-prometheus script.js
+```
+
+### Cloud (k6 Cloud)
+```bash
+k6 cloud script.js
+```
+
+### Summary
+Built-in summary prints to stdout. Customize with:
+```javascript
+import { htmlReport } from 'https://raw.githubusercontent.com/benc-uk/k6-reporter/main/dist/bundle.js';
+
+export function handleSummary(data) {
+  return {
+    'summary.html': htmlReport(data),
+    stdout: textSummary(data, { indent: ' ', enableColors: true }),
+  };
+}
+```
+
+---
+
+## Environment and Variables
+
+### Environment Variables
+```javascript
+const baseUrl = __ENV.BASE_URL || 'https://example.com';
+const apiKey = __ENV.API_KEY;
+```
+
+### Options Override via Env
+```bash
+BASE_URL=https://staging.example.com k6 run script.js
+```
+
+### Options Override via CLI
+```bash
+k6 run -e BASE_URL=https://staging.example.com script.js
+k6 run --vus 20 --duration 1m script.js
+```
+
+---
+
+## Tags
+
+Add tags for filtering metrics and organizing output.
+
+```javascript
+import http from 'k6/http';
+
+export default function () {
+  const res = http.get('https://api.example.com/items', {
+    tags: { name: 'list_items', endpoint: 'GET /items' },
+  });
+}
+```
+
+```javascript
+export const options = {
+  tags: {
+    project: 'my-project',
+    env: 'staging',
+  },
+};
+```
+
+---
+
+## TLS and Security
+
+```javascript
+export const options = {
+  insecureSkipTLSVerify: true,  // For dev/staging only
+  tlsVersion: {
+    min: 'tls1.2',
+    max: 'tls1.3',
+  },
+};
+```
+
+---
+
+## Graceful Stop
+
+Allow in-flight requests to complete before stopping VUs.
+
+```javascript
+export const options = {
+  scenarios: {
+    main: {
+      executor: 'constant-vus',
+      vus: 10,
+      duration: '5m',
+      gracefulStop: '30s',
+    },
+  },
+};
+```