@assertrx/dino 1.0.10 → 1.0.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assertrx/dino",
-  "version": "1.0.10",
+  "version": "1.0.11",
   "description": "A friendly purple dinosaur pi package with a custom TUI header, theme, and Playwright skills.",
   "keywords": [
     "pi-package"

package/prompts/generate-k6-test-from-endpoint.md

@@ -0,0 +1,68 @@
+---
+description: Generate a k6 load test for a single provided endpoint using all the k6 skills
+argument-hint: "<endpoint-url> [output-file] [test-type]"
+---
+
+Generate a complete, runnable k6 load test for the endpoint at `$1`, guided by the k6 skills in this package. The default output file is `${2:-tests/k6/endpoint-test.js}` and the default test type is `${3:-load}`.
+
+## Step 1 — Load the k6 skills
+
+Before writing any code, use `read` to load the SKILL.md files for these skills from the package `skills/` directory (follow the reference files they point to when relevant):
+
+- **designing-test-scenarios** — always; needed for the load profile and thresholds.
+- **generating-api-load-tests** — always; needed for the script structure and protocol patterns.
+- **analyzing-test-results** — always; needed to verify and interpret the validation run.
+
+Load these additional skills only when the corresponding condition applies:
+
+- **generating-tests-from-openapi** — the user provides an OpenAPI spec for the endpoint.
+- **generating-tests-from-code** — the endpoint's source code exists in the current workspace.
+- **generating-browser-tests** — the endpoint serves HTML and the user wants browser-level (Web Vitals) testing instead of protocol-level.
+- **testing-resilience** — the user asks for fault injection or chaos testing against the endpoint.
+- **operating-k6-in-ci-cd** — the user asks for a CI pipeline snippet along with the test.
+
+## Step 2 — Probe the endpoint
+
+- Use `bash` with `curl -s -o /dev/null -w "%{http_code} %{time_total}"` (or similar) to verify the endpoint is reachable and note the status, latency, content type, and auth requirements.
+- If the endpoint requires authentication, determine the scheme (Bearer token, basic, cookie, API key) and ask the user to supply credentials via an environment variable or env file. **Never hardcode credentials in the generated script** — read them from `__ENV`.
+- If the endpoint is unreachable, still generate the script against the given URL and note that verification was skipped.
+
+## Step 3 — Confirm the test design
+
+Ask the user (or infer sensibly and state the assumptions) for:
+
+- **Test type** (`$3`, default `load`): map it to an executor and load profile using the *designing-test-scenarios* skill — smoke, load, stress, spike, soak, or breakpoint.
+- **Performance targets**: p95/p99 latency and error-rate thresholds; use the skill's threshold guidance (e.g. `http_req_failed: ['rate<0.01']`, `http_req_duration: ['p(95)<500']`) if none are given.
+- **Auth and test data**: environment variables needed, any request body for POST/PUT endpoints, and whether test data should be parameterized per the *generating-api-load-tests* skill.
+
+## Step 4 — Generate the script
+
+- Write the test to `${2:-tests/k6/endpoint-test.js}` using kebab-case file names, following the *generating-api-load-tests* skill patterns:
+  - All config via `__ENV` with sensible defaults (`BASE_URL`, `HEADERS`, `STAGES_*`).
+  - `export const options` with the chosen executor, stages, thresholds, and tags (e.g. `{ name: '$1' }`).
+  - A `default` function that hits the endpoint, applies `check`s for status and content, and `sleep`s with realistic think time.
+  - `setup()`/`teardown()` only if auth tokens or shared data require them.
+- If an OpenAPI spec was provided, follow *generating-tests-from-openapi* for request construction and auth mapping; if the API source is in the workspace, follow *generating-tests-from-code* to mirror real routes and payloads.
+- If browser testing applies, generate the browser variant per the *generating-browser-tests* skill (import from `k6/browser`, `export async function default(page)`, Web Vitals measurements).
+- If CI is requested, add a pipeline snippet per *operating-k6-in-ci-cd* (GitHub Actions unless specified otherwise).
+
+## Step 5 — Validate and analyze
+
+- Run `k6 inspect <output-file>` to confirm the script parses and options are exported.
+- With the user's permission (and only for endpoints you are authorized to test), run a short smoke validation, e.g. `k6 run --iterations 2 <output-file>`.
+- If a run was executed, apply the *analyzing-test-results* skill to read the summary: threshold pass/fail, percentiles, and any bottleneck signals.
+- Report the results and suggested next steps (e.g. tuning VUs, adding scenarios, running a soak).
+
+## Rules
+
+- Only target endpoints the user owns or has explicit authorization to load test.
+- Never fire load at production endpoints without the user's explicit confirmation; default to a 2-iteration smoke validation only.
+- Never echo, log, or persist credentials; use `__ENV` exclusively.
+- Do not overwrite existing test files; pick a new file name if the target exists.
+- Keep the script idiomatic k6 (init context, options export, checks, tags); avoid dead code and unused imports.
+
+After generating, summarize:
+- The endpoint, chosen test type, executor, and thresholds (and why).
+- The output file path(s) and any env variables required to run it.
+- The probe/validation results and analysis from any executed run.
+- Which k6 skills were loaded and how each shaped the result.

package/prompts/generate-k6-test-from-openapi.md

@@ -0,0 +1,85 @@
+---
+description: Generate a k6 load test suite from a provided OpenAPI or Swagger specification
+argument-hint: "<spec-path-or-url> [output-dir] [scope]"
+---
+
+Generate a complete, runnable k6 load test suite from the OpenAPI/Swagger specification at `$1`, guided by the k6 skills in this package. Default output directory is `${2:-tests/k6/}` and default scope is `${3:-all}` (all suitable operations, or a tag/path filter like `Users` or `/users`).
+
+## Step 1 — Load the k6 skills
+
+Before writing any code, use `read` to load the SKILL.md files (follow their reference files when relevant):
+
+- **generating-tests-from-openapi** — primary; drives the whole workflow (spec parsing, auth mapping, request body generation).
+- **designing-test-scenarios** — always; for executors, load profiles, and thresholds per endpoint type.
+- **generating-api-load-tests** — always; for idiomatic HTTP script patterns (headers, params, checks, data handling).
+- **analyzing-test-results** — always; to interpret the validation run.
+
+Load these additional skills only when the condition applies:
+
+- **operating-k6-in-ci-cd** — the user asks for a CI pipeline snippet alongside the tests.
+- **testing-resilience** — the user asks for fault injection during the load tests.
+
+## Step 2 — Load and validate the spec
+
+- If `$1` is a URL, download it with `curl -sSL`; if it is a local file, read it directly.
+- Support both **OpenAPI 3.x** (`openapi:` key, `servers`, `components.securitySchemes`) and **Swagger 2.0** (`swagger: '2.0'`, `basePath`/`host`, `securityDefinitions`) — normalize Swagger 2.0 structures to their OpenAPI 3 equivalents while parsing.
+- Support both YAML and JSON. If the file fails to parse, stop and report the exact error instead of guessing.
+- Note the API title, version, base URL (`servers[0].url` or `host + basePath`), and whether a base URL is missing (then require it via `__ENV.BASE_URL` and say so).
+
+## Step 3 — Parse the spec per the skill
+
+Follow the *generating-tests-from-openapi* skill workflow and extract:
+
+- All paths and operations (method, `operationId`, `tags`, parameters, request bodies, response codes).
+- **Security analysis (prerequisite)**: global `security`, per-operation overrides, and public endpoints (`security: []`); map schemes per the skill's auth-mapping reference (OAuth2 flows, API key, Bearer/Basic, OpenID Connect).
+- Request body schemas, resolving `$ref`s to `components`/`definitions`, and building example values from the skill's schema→example table (prefer `example`/`default` values from the spec when present).
+
+## Step 4 — Confirm the scope
+
+- Apply `$3` (default `all`): filter to the requested tag or path prefix if given.
+- By default **exclude**: deprecated operations, destructive operations (`DELETE`, and state-destroying `PUT`/`POST` like reset endpoints), and health/doc endpoints unless trivial — but list everything excluded and let the user re-include any.
+- If the API has many tags, propose one script per tag under the output directory; otherwise a single script organized with `group()`s by tag (per the skill's Step 5 pattern).
+
+## Step 5 — Design the load profile
+
+Use the *designing-test-scenarios* skill:
+
+- Pick executors and load levels per endpoint characteristic (per the OpenAPI skill's Step 6): read-heavy GETs get higher rates, writes get lower rates, admin endpoints are excluded or isolated.
+- Set sensible default thresholds (e.g. `http_req_failed: ['rate<0.01']`, `http_req_duration: ['p(95)<500']`) and let the user override with their SLAs.
+- Confirm the target environment: default `BASE_URL` from the spec's `servers`, but **warn and require explicit confirmation before running against any production URL**.
+
+## Step 6 — Generate the test suite
+
+Following the *generating-tests-from-openapi* script structure (and *generating-api-load-tests* patterns):
+
+- All config via `__ENV` with defaults (`BASE_URL`, auth credentials, scenario tuning); never hardcode secrets.
+- `setup()` implementing the required auth flow from the security analysis (token fetch, API key injection) — pass tokens to the default function via the setup data argument.
+- `export const options` with the designed scenarios and thresholds.
+- Default function with one `group()` per API tag; each operation tagged `{ name: '<operationId>' }` and wrapped in `check`s for the documented success status code (200/201/etc. from the spec).
+- **Chain dependent operations** where the spec implies it (e.g. POST `/users` → use the created `id` in GET `/users/{id}` → DELETE it in cleanup), so writes are self-cleaning and don't pollute the target.
+- Request bodies built from the schema example values; override placeholders like `test@example.com` are fine for load tests.
+- Realistic `sleep(1)` think time between operations.
+- If CI was requested, add the pipeline snippet per *operating-k6-in-ci-cd*; if resilience was requested, follow *testing-resilience* for the fault-injection wrapper.
+
+## Step 7 — Validate and analyze
+
+- Run `k6 inspect` on each generated script to confirm they parse and options export correctly.
+- With the user's explicit permission (non-production target preferred), run a short smoke validation, e.g. `k6 run --iterations 2 <script>` per script or on one representative script.
+- If a run was executed, apply the *analyzing-test-results* skill to interpret threshold pass/fail, percentiles, and error rates.
+- Report results and suggested next steps (tuning VUs, per-endpoint scenarios, soak runs).
+
+## Rules
+
+- Only target APIs the user owns or has explicit authorization to load test; never run against production without explicit confirmation.
+- Never echo, log, or persist credentials; read auth secrets exclusively from `__ENV`.
+- Do not overwrite existing test files; pick new file names if targets exist.
+- Do not invent endpoints or fields that are not in the spec; if something is ambiguous (missing base URL, circular `$ref`, unresolved schema), ask or state the assumption explicitly.
+- Keep generated scripts idiomatic k6 (init context, options export, groups, checks, tags); no dead code.
+
+After generating, summarize:
+- The spec (title, version, OpenAPI/Swagger format), base URL, and number of operations covered vs. excluded.
+- The auth scheme detected and how it was implemented in `setup()`.
+- The scenarios/thresholds designed per endpoint type and why.
+- Output file path(s), required env variables, and how to run them.
+- Validation/analysis results from any executed run.
+- Which k6 skills were loaded and how each shaped the result.

package/prompts/setup-k6.md

@@ -0,0 +1,130 @@
+---
+description: Set up k6 and a skeleton load testing project in the current workspace
+---
+
+Set up k6 and a runnable skeleton load-testing project in the current workspace root. The goal is to end up with the k6 CLI available and a minimal `tests/` folder with working scripts covering a smoke test and a load test.
+
+## Steps
+
+1. **Inspect the workspace**.
+   - Use `bash` to list the current directory and check for `package.json`.
+   - Do not touch existing k6 scripts, options files, or CI pipelines that reference k6.
+
+2. **Check k6 installation**.
+   - Run `k6 version`.
+   - If it prints a version (v0.5x or newer), skip installation.
+
+3. **Install k6 if needed**. Pick the first method that works on the current OS:
+   - Windows: `winget install grafana.k6` (or `choco install k6`, or `scoop install k6`).
+   - macOS: `brew install k6`.
+   - Linux: follow the official apt/dnf instructions from https://grafana.com/docs/k6/latest/set-up/install/.
+   - Fallback for any OS: download a binary from the grafana/k6 GitHub releases and put it on `PATH`, or use Docker: `docker run --rm -i grafana/k6 run - < tests/smoke.js`.
+   - Re-run `k6 version` to confirm the install. If no method works, create the project files anyway and document the install commands in a `README.md`.
+
+4. **Create the project structure**.
+   - Keep it minimal and idiomatic:
+     ```
+     tests/
+       smoke.js
+       load.js
+     ```
+   - Use plain JavaScript; k6 runs scripts natively with no build step.
+
+5. **Create a smoke test**.
+   - Write `tests/smoke.js` with a minimal working script:
+     ```js
+     import http from 'k6/http';
+     import { check, sleep } from 'k6';
+
+     const BASE_URL = __ENV.BASE_URL || 'https://quickpizza.grafana.com';
+
+     export const options = {
+       vus: 1,
+       iterations: 5,
+       thresholds: {
+         http_req_failed: ['rate<0.01'], // http errors should be less than 1%
+         http_req_duration: ['p(95)<500'], // 95% of requests under 500ms
+       },
+     };
+
+     export default function () {
+       const res = http.get(BASE_URL);
+       check(res, {
+         'status is 200': (r) => r.status === 200,
+       });
+       sleep(1);
+     }
+     ```
+
+6. **Create a load test**.
+   - Write `tests/load.js` demonstrating executor stages and thresholds:
+     ```js
+     import http from 'k6/http';
+     import { check, sleep } from 'k6';
+
+     const BASE_URL = __ENV.BASE_URL || 'https://quickpizza.grafana.com';
+
+     export const options = {
+       scenarios: {
+        ramping_vus: {
+          executor: 'ramping-vus',
+          startVUs: 1,
+          stages: [
+            { duration: '30s', target: 10 }, // ramp up
+            { duration: '1m', target: 10 },  // stay at load
+            { duration: '30s', target: 0 },  // ramp down
+          ],
+          gracefulRampDown: '15s',
+        },
+       },
+       thresholds: {
+         http_req_failed: ['rate<0.01'],
+         http_req_duration: ['p(95)<500'],
+       },
+     };
+
+     export default function () {
+       const res = http.get(BASE_URL);
+       check(res, {
+         'status is 200': (r) => r.status === 200,
+       });
+       sleep(1);
+     }
+     ```
+
+7. **Add convenience scripts**.
+   - If `package.json` is missing, run `npm init -y` first.
+   - Use `edit` to add scripts to `package.json`:
+     ```json
+     {
+       "k6:smoke": "k6 run tests/smoke.js",
+       "k6:load": "k6 run tests/load.js"
+     }
+     ```
+   - Do not duplicate scripts that already exist.
+   - If the workspace has no Node.js at all, write a short `README.md` documenting the raw `k6 run tests/smoke.js` / `k6 run tests/load.js` commands instead.
+
+8. **Verify the setup**.
+   - Run `k6 version` and report the version.
+   - Run `k6 inspect tests/smoke.js` to confirm the script parses and the options export is picked up.
+   - Optionally run `k6 run --iterations 2 tests/smoke.js` for a quick live check (it hits `quickpizza.grafana.com`, so skip if offline). Confirm the threshold summary passes.
+   - Report the final k6 version and the list of created files.
+
+## Optional: TypeScript
+
+Only if the user explicitly asks for TypeScript, add esbuild bundling (`k6` has no native TS runtime):
+- `npm install -D esbuild typescript` and add a `build` script that bundles `src/**/*.ts` into `tests/`.
+- Otherwise skip this step entirely; plain JavaScript is the default.
+
+## Rules
+
+- Do not overwrite existing user files unless they are missing or clearly incomplete.
+- Keep the setup minimal and idiomatic; do not add CI pipelines, dashboards, or cloud integrations unless asked.
+- Never hardcode secrets or tokens in the scripts; use `__ENV` and environment variables.
+- Use `edit` for precise changes to `package.json`.
+- Use `write` only for new files or complete rewrites of files you created.
+
+After completing the setup, summarize:
+- Which files were created or modified.
+- The k6 version installed.
+- Any verification results or errors encountered.

package/scripts/api-server.mjs

@@ -88,6 +88,29 @@ const PROMPT_REGISTRY = {
     ],
     description: "Detect, diagnose, and auto-heal failed Playwright tests",
   },
+  "setup-k6": {
+    file: "setup-k6.md",
+    params: [],
+    description: "Install k6 and create a runnable skeleton load-testing project in the workspace",
+  },
+  "generate-k6-test-from-endpoint": {
+    file: "generate-k6-test-from-endpoint.md",
+    params: [
+      { name: "url", required: true, description: "Target endpoint URL to load test" },
+      { name: "outputFile", required: false, description: "Output test file (default: tests/k6/endpoint-test.js)" },
+      { name: "testType", required: false, description: "smoke, load, stress, spike, soak or breakpoint (default: load)" },
+    ],
+    description: "Generate a k6 load test for a single endpoint using the k6 skills",
+  },
+  "generate-k6-test-from-openapi": {
+    file: "generate-k6-test-from-openapi.md",
+    params: [
+      { name: "specUrl", required: true, description: "Path or URL of the OpenAPI/Swagger spec (.yaml/.yml/.json)" },
+      { name: "outputDir", required: false, description: "Output directory (default: tests/k6/)" },
+      { name: "scope", required: false, description: "Tag or path filter, e.g. Users or /users (default: all operations)" },
+    ],
+    description: "Generate a k6 load test suite from an OpenAPI/Swagger specification",
+  },
 };
 
 // ── Server-level agent defaults ────────────────────────────────────────

package/skills/analyzing-test-results/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: analyzing-test-results
+description: Use when interpreting k6 test output, analyzing performance metrics, identifying bottlenecks, tuning thresholds, or optimizing k6 test scripts. Use when the user has k6 test results and needs to understand response times, error rates, percentiles (p95, p99), or performance degradation patterns.
+---
+
+# Analyzing k6 Test Results
+
+Interpret k6 test output, identify performance bottlenecks, and provide optimization recommendations.
+
+## Analysis Workflow
+
+1. **Review summary output** — Check overall pass/fail, iteration count, VU count
+2. **Check thresholds** — Which passed/failed? By how much?
+3. **Analyze response times** — Look at p50, p90, p95, p99 distribution
+4. **Break down request duration** — Examine blocked, connecting, TLS, waiting, receiving
+5. **Identify bottlenecks** — Map timing components to root causes
+6. **Suggest optimizations** — Script improvements, threshold tuning, infrastructure changes
+
+## Understanding k6 Output
+
+### End-of-Test Summary
+
+```
+     data_received..................: 148 kB  4.9 kB/s
+     data_sent......................: 17 kB   564 B/s
+     http_req_blocked...............: avg=23.38ms  min=1µs    med=5µs    max=235.44ms p(90)=10µs   p(95)=210.47ms
+     http_req_connecting............: avg=11.12ms  min=0s     med=0s     max=117.4ms  p(90)=0s     p(95)=99.38ms
+   ✓ http_req_duration..............: avg=131.01ms min=116.4ms med=127.6ms max=196.38ms p(90)=146.21ms p(95)=176.91ms
+     http_req_failed................: 0.00%  ✓ 0  ✗ 200
+     http_req_receiving.............: avg=5.11ms   min=26µs   med=4.88ms max=14.82ms  p(90)=9.31ms p(95)=10.82ms
+     http_req_sending...............: avg=27µs     min=4µs    med=23µs   max=240µs    p(90)=42µs   p(95)=66µs
+     http_req_tls_handshaking.......: avg=11.7ms   min=0s     med=0s     max=116.76ms p(90)=0s     p(95)=105.06ms
+     http_req_waiting...............: avg=125.86ms min=116.27ms med=122.6ms max=185.5ms p(90)=137.21ms p(95)=170.53ms
+     http_reqs......................: 200    6.63/s
+     iteration_duration.............: avg=1.16s    min=1.12s  med=1.13s  max=1.43s    p(90)=1.15s  p(95)=1.41s
+     iterations.....................: 200    6.63/s
+     vus............................: 10     min=10  max=10
+     vus_max........................: 10     min=10  max=10
+```
+
+### Reading the Output
+
+- **✓** = threshold passed, **✗** = threshold failed
+- Each metric shows: `avg`, `min`, `med` (median), `max`, `p(90)`, `p(95)`
+- `http_reqs` rate = requests per second (RPS)
+
+## HTTP Request Duration Breakdown
+
+The total `http_req_duration` is composed of:
+
+```
+blocked → connecting → tls_handshaking → sending → waiting → receiving
+                                                      ↑
+                                              (TTFB / server time)
+```
+
+| Component | What It Measures | Typical Cause of High Values |
+|-----------|-----------------|------------------------------|
+| `http_req_blocked` | Time in queue before request starts | Connection pool exhaustion, DNS lookup |
+| `http_req_connecting` | TCP connection time | Network latency, server far away |
+| `http_req_tls_handshaking` | TLS/SSL handshake | Missing keep-alive, new connections per request |
+| `http_req_sending` | Time to send request body | Large request body, slow upload |
+| `http_req_waiting` | Server processing time (TTFB) | Slow backend, DB queries, server overload |
+| `http_req_receiving` | Time to download response | Large response body, slow network |
+| `http_req_duration` | sending + waiting + receiving | Overall request time |
+
+See [reference/bottleneck-patterns.md](reference/bottleneck-patterns.md) for detailed bottleneck analysis patterns.
+
+## Key Metrics Quick Reference
+
+See [reference/metrics.md](reference/metrics.md) for the complete k6 metrics reference.
+
+### Most Important Metrics to Monitor
+
+| Metric | Type | What to Watch |
+|--------|------|---------------|
+| `http_req_duration` | Trend | p95 and p99 — are they within SLA? |
+| `http_req_failed` | Rate | Error rate — should be < 1% for normal load |
+| `http_reqs` | Counter | Request rate (RPS) — is target throughput achieved? |
+| `iteration_duration` | Trend | Full iteration time including sleeps |
+| `checks` | Rate | Assertion pass rate — should be > 99% |
+| `vus` | Gauge | Active VU count — did it reach target? |
+
+## Percentile Interpretation
+
+| Percentile | Meaning |
+|------------|---------|
+| `p(50)` / `med` | Half of requests are faster. Typical user experience. |
+| `p(90)` | 90% of requests are faster. Most users' experience. |
+| `p(95)` | 95% of requests are faster. Common SLA target. |
+| `p(99)` | 99% of requests are faster. Worst-case for most users. |
+| `p(99.9)` | 1 in 1000 requests slower. Tail latency. |
+
+**Rule of thumb:** If p95 is 2x+ the median, there's likely a bottleneck affecting some requests.
+
+## handleSummary() Customization
+
+Override the default summary output:
+
+```javascript
+import { textSummary } from 'https://jslib.k6.io/k6-summary/0.1.0/index.js';
+
+export function handleSummary(data) {
+  return {
+    'summary.json': JSON.stringify(data, null, 2),
+    stdout: textSummary(data, { indent: ' ', enableColors: true }),
+  };
+}
+```
+
+Available output targets:
+- `stdout` — Console output
+- `stderr` — Error output
+- `'filename.json'` — Write to file
+- `'filename.html'` — Write HTML report
+
+## Results Output Options
+
+### JSON Lines (Real-Time)
+
+```bash
+k6 run --out json=results.json script.js
+```
+
+### CSV Output
+
+```bash
+k6 run --out csv=results.csv script.js
+```
+
+### Web Dashboard (Built-in)
+
+```bash
+K6_WEB_DASHBOARD=true k6 run script.js
+# Dashboard at http://localhost:5665
+```
+
+### Grafana Cloud k6
+
+```bash
+k6 cloud run --local-execution script.js
+# Or set K6_CLOUD_TOKEN environment variable
+```
+
+See [reference/visualization.md](reference/visualization.md) for detailed visualization options.
+
+## Related Skills
+
+- For designing test scenarios and thresholds: `/k6:designing-test-scenarios`
+- For generating test scripts: `/k6:generating-api-load-tests`

package/skills/analyzing-test-results/reference/bottleneck-patterns.md

@@ -0,0 +1,130 @@
+# k6 Bottleneck Patterns Reference
+
+## Diagnostic Matrix
+
+| Symptom | Primary Metric | Root Cause | Action |
+|---------|---------------|------------|--------|
+| High blocked time | `http_req_blocked` > 100ms | Connection pool exhaustion, DNS issues | Increase connection pool, use HTTP keep-alive |
+| High connecting time | `http_req_connecting` > 50ms | Server distance, TCP overhead | Use closer servers, CDN, connection reuse |
+| High TLS time | `http_req_tls_handshaking` > 100ms | New TLS connection per request | Enable keep-alive, TLS session resumption |
+| High waiting time | `http_req_waiting` > 500ms | Slow server processing | Optimize backend, DB queries, caching |
+| High receiving time | `http_req_receiving` > 100ms | Large response body | Compress responses, paginate, reduce payload |
+| High error rate | `http_req_failed` > 1% | Server overload, bugs | Check error codes, server logs, capacity |
+| Low throughput | `http_reqs` rate declining | Resource saturation | Scale infrastructure, optimize code |
+| Dropped iterations | `dropped_iterations` > 0 | Not enough VUs for target rate | Increase `preAllocatedVUs` or `maxVUs` |
+
+## Pattern 1: Connection Pool Exhaustion
+
+**Symptoms:**
+- `http_req_blocked` p95 > 100ms (often > 1s)
+- `http_req_blocked` increases over time
+- `http_req_connecting` stays low
+
+**Diagnosis:** k6 cannot open new connections fast enough. Requests queue waiting for available connections.
+
+**Solutions:**
+- Check target server connection limits
+- Reduce concurrent VU count
+- Add think time (`sleep()`) between requests
+- Check if server supports HTTP/2 (multiplexing)
+
+## Pattern 2: TLS Overhead
+
+**Symptoms:**
+- `http_req_tls_handshaking` consistently > 50ms
+- First requests have much higher duration than subsequent ones
+- `http_req_blocked` correlates with TLS timing
+
+**Diagnosis:** New TLS connections being established for each request instead of reusing.
+
+**Solutions:**
+- k6 reuses connections by default within an iteration
+- Ensure server supports TLS session resumption
+- Check if `noConnectionReuse` option is accidentally set
+- Consider HTTP/2 for multiplexing over single connection
+
+## Pattern 3: Server-Side Bottleneck
+
+**Symptoms:**
+- `http_req_waiting` (TTFB) increases as VUs increase
+- `http_req_waiting` is the dominant component of duration
+- `http_req_sending` and `http_req_receiving` remain low
+
+**Diagnosis:** Server is struggling under load. Could be CPU, memory, database, or application bottleneck.
+
+**Solutions:**
+- Profile server-side code
+- Optimize database queries (add indexes, caching)
+- Scale horizontally (add servers)
+- Implement caching (Redis, CDN)
+- Check for thread/connection pool limits
+
+## Pattern 4: Response Size Bottleneck
+
+**Symptoms:**
+- `http_req_receiving` is high relative to total duration
+- `data_received` is very high
+- Throughput drops as response sizes increase
+
+**Diagnosis:** Large response payloads consuming bandwidth and processing time.
+
+**Solutions:**
+- Enable response compression (gzip, brotli)
+- Implement pagination for list endpoints
+- Return only necessary fields (field selection)
+- Use `discardResponseBodies: true` in k6 options if body isn't needed
+
+## Pattern 5: Gradual Degradation (Soak Test)
+
+**Symptoms:**
+- Metrics gradually worsen over time
+- `http_req_duration` slowly increases during soak test
+- Error rate slowly creeps up
+
+**Diagnosis:** Memory leak, connection leak, or resource exhaustion in server.
+
+**Solutions:**
+- Monitor server-side memory usage
+- Check for connection/handle leaks
+- Verify database connection pool sizing
+- Check log file growth
+- Monitor disk space
+
+## Pattern 6: Sudden Failure (Breakpoint)
+
+**Symptoms:**
+- Metrics suddenly spike at specific VU count or RPS
+- Error rate jumps from ~0% to high percentage
+- `http_req_duration` increases dramatically
+
+**Diagnosis:** System has hit a hard limit (connection limit, thread pool, memory).
+
+**Solutions:**
+- Identify the exact threshold where failure begins
+- Check server error logs at that timestamp
+- Common limits: max connections, max threads, memory, file descriptors
+- Tune the specific limit or scale infrastructure
+
+## Correlation Between Metrics
+
+**Healthy test:**
+- `http_req_duration` stable across all percentiles
+- `http_req_failed` near 0%
+- `http_reqs` rate matches expected throughput
+- `dropped_iterations` = 0
+
+**Signs of trouble:**
+- p99 >> p50 (high variance = inconsistent performance)
+- `http_req_failed` increasing over time
+- `http_reqs` rate declining while VUs are constant
+- `http_req_blocked` growing (connection issues)
+- `dropped_iterations` increasing (can't keep up with arrival rate)
+
+## Performance Ratio Guidelines
+
+| Ratio | Healthy | Warning | Critical |
+|-------|---------|---------|----------|
+| p95 / p50 | < 2x | 2-5x | > 5x |
+| p99 / p50 | < 3x | 3-10x | > 10x |
+| Error rate | < 0.1% | 0.1-1% | > 1% |
+| TTFB / Duration | < 80% | 80-95% | > 95% |