--- name: k6-guides description: Curated map of the official k6 load-testing docs - installation, running a script, scripting (checks/thresholds/scenarios), test types, protocols, and which questions a benchmark's inputs require before it can be authored. Use when authoring or reasoning about a k6 benchmark - pick the topic, open its reference file, and follow the linked official docs. Read by /odd-instrument-bench (which questions to ask), k6-benchmark-expert (authoring and validating), a stored benchmark's replay (running one), and the /odd-instrument-bench, /odd-observe, and /odd-verify preflights (ensuring k6 is present). --- # k6 guides Same pattern as `otel-guides` (one file per language) and `observability-cli-guides` (one file per backend): a selection map whose callers open exactly the reference they need instead of re-deriving k6 usage from memory. Here the selection axis is the topic. ## Fetching the docs `grafana.com/docs/k6/latest/` serves raw markdown by appending `.md` to any page URL, or via an `Accept: text/markdown` header. `https://grafana.com/llms.txt` (curated index) and `https://grafana.com/llms-full.txt` (~1.4 MB, ~1000 `docs/k6/latest` URLs) exist at the site root - the cheapest way to enumerate the k6 doc tree when this skill's reference files need re-verifying; per-page fetching via the `.md` suffix is still how the content itself is read. Both live at the site **root**, not under `/docs/k6/latest/` (that path 404s) - a natural first mistake, verify against the root before concluding they don't exist. **An underscore written outside backticks may come back backslash-escaped.** Names the pages write as code keep their underscores; names written as plain text - the metrics reference's first column is the case that bites - are served as `dropped\_iterations`, so a grep for the bare name finds nothing on a page that does document the metric. It is not a property of tables: verified live (this machine, 2026-09-06) on the fetched `.md` of `using-k6/metrics/reference/` (56 escaped underscores, every one of them an unbackticked name in a table's first column; `grep -c dropped_iterations` -> `0`, `grep -c 'dropped\\_iterations'` -> `1`), against `using-k6/k6-options/reference/` and `using-k6/thresholds/` (143 and 7 table data rows, **zero** escaped underscores - both write their names as code). Before concluding a metric or an option is undocumented, grep with the underscore made optional (`grep -i 'dropped.\?_iterations'`) or on the unambiguous fragment alone (`grep -i dropped`). ## Which reference | Question | Reference | | --- | --- | | Is k6 installed? How do I install/detect it? | [install.md](references/install.md) | | What replay line may a preflight hand the mission? | [install.md](references/install.md), its closing section | | How do I run a k6 script, read its output, know if it passed? | [running-tests.md](references/running-tests.md) | | How do I validate a script without running the benchmark - `k6 inspect`, a one-iteration smoke? | [running-tests.md](references/running-tests.md) | | Why is `res.body` null / why does `res.json()` throw? | [scripting.md](references/scripting.md) | | How do I write the script - requests, checks, thresholds, staged load? | [scripting.md](references/scripting.md) | | Which test type fits this investigation - smoke, load, stress, soak, spike, breakpoint? | [test-types.md](references/test-types.md) | | What does a benchmark's authoring need decided, and by whom - human or agent? | [authoring-inputs.md](references/authoring-inputs.md) | | Does k6 support the service's protocol (gRPC, WebSockets, ...)? | [protocols.md](references/protocols.md) | | How do I drive an MCP server - the session handshake, SSE bodies, one session per VU? | [mcp.md](references/mcp.md) | | Is this browser/frontend performance testing rather than API load? | [browser.md](references/browser.md) | ## Conventions - Reference content is a **snapshot** ("last verified YYYY-MM") - the fetched official page always overrides it. Recommendations must come from a fetched page, never from memory; anything unfetchable is marked unverified rather than presented as sourced. - **The k6 major version is stated.** `latest` currently documents k6 **v2** - `install.md` names it, and `scripting.md` never recommends a removed executor or command. A skill that silently mixes v1 and v2 guidance produces scripts that fail to start. - These references cover k6 **itself** - never this project's `.odd/benchmarks/` format, never the manifest schema. That knowledge lives with `odd-memory`'s `benchmark` reference and `k6-benchmark-expert`.