K6 Perf Test Website

k6-perf-test-website

An end-to-end, opinionated workflow for performance-testing any public website with k6. The skill produces:

• A scaffolded project with one folder per user-described workflow.
• Functional protocol + browser tests (must pass before load testing).
• Hybrid load tests (protocol scenario + 1 browser VU) per test type (smoke / average / stress / spike / soak / breakpoint).
• SLO-backed thresholds with per-endpoint tagging and Web Vitals.
• A cross-platform load-generator monitor sidecar.
• Optional Grafana-side investigation when the user owns the backend.
• A structured Markdown report at the end.

This skill enforces a few opinions you should not silently override:

• Always elicit workflows first. Don't guess.
• Functional tests must be green before load tests run.
• Always monitor the load generator — server-looks-slow is often laptop-looks-slow.
• Local for validation, cloud for scale — but ask the user where to run each test type; don't hardcode.
• No shared tests/lib/. Iteration-body duplication is preferred; each script reads cleanly on its own during incident review.

Prerequisites

• k6 ≥ v2.0.0 (k6 version) — required for stable k6/browser, expect(), async/await iteration functions, and per-request tags.
• Node.js ≥ 20 + npm.
• Playwright with the Chromium download (npx playwright install chromium).
• har-to-k6 (npm i -D har-to-k6).
• Network access from the load-generator host to the target site.

Tools the skill prefers when installed:

• mcp-k6 — script creation, Playwright→k6/browser migration, API lookup. Prefer over hand-writing k6 boilerplate.
• mcp-grafana — in-session Prometheus/Loki/Tempo/Pyroscope queries during §9 backend investigation.
• gcx — Grafana Cloud CLI for shell-friendly queries, datasource discovery, and Grafana Cloud k6 cloud-run dispatch.
• k6 binary — local validation runs and breakpoint hunting.
• k6 x docs (xk6-docs) — look up k6 API surface when writing or editing scripts without mcp-k6 available.

If these tools are not configured the skill falls back to plain CLI tools (k6, npx, curl) and hand-written scripts. The skill does not own toolchain setup; defer to the user's existing setup process.

Explicit non-goals:

• Protocol-only suites (out of scope for this skill).
• API-only / non-browser apps.
• Mobile-native testing.
• Capacity planning beyond finding and tagging a breakpoint.

Workflow overview

Tick these off in order. Each step has a section below.

1. Elicit workflows from the user. §1
2. Scaffold the project from assets/. §2
3. Record each workflow with Playwright. §3
4. Build functional protocol + browser tests; run tests/run-all.sh until green. §4
5. Design SLO-backed thresholds and per-endpoint tags. §5
6. Build hybrid load tests, one file per test type. §6
7. Run validation locally with the LG sidecar. §7
8. Push to Grafana Cloud k6 for the test types the user chose for cloud. §8
9. Investigate the backend with Grafana (if owned). §9
10. Report back to the user. §10

1. Elicit workflows

The single most important step. Without explicit workflows, every later step is guesswork.

Ask the user the questions in references/workflow-elicitation.md and record answers in a runbook.md alongside the scaffolded project.

You must capture: 2-4 named workflows, credentials, read vs write, destructive actions to avoid during soak, worry list, existing SLOs, backend ownership and Grafana access, and per test type whether each runs locally or in Grafana Cloud k6.

If the user can't name at least one workflow, stop and clarify; do not proceed.

2. Scaffold the project

Copy the assets/ tree from this skill into the user's chosen directory. The skill's assets/ directory is at <SKILL_DIR>/assets/, where <SKILL_DIR> is the absolute path to this skill's directory — your harness exposes this (e.g. opencode prefixes skill metadata with a Base directory for this skill: line). If you can't determine <SKILL_DIR> from context, ask the user.

cp -R "<SKILL_DIR>/assets/." "<target-dir>/"

If cp -R is blocked by sandbox permissions, copy files individually via your agent's file-write tool.

The scaffolded layout:

<target-dir>/
├── package.json
├── .gitignore
├── README.md
├── runbook.md                       # you create from §1 answers
├── recordings/
│   ├── README.md
│   └── scripts/
│       └── recorder.template.js     # copy per workflow → wN-<short-name>.js, …
├── tests/
│   ├── run-all.sh
│   └── workflow.template/           # copy per workflow → wN-<short-name>/, …
│       ├── from-har.js
│       ├── protocol.js
│       ├── browser.js
│       ├── smoke.js
│       ├── average.js
│       ├── stress.js
│       ├── spike.js
│       ├── soak.js
│       └── breakpoint.js
└── tools/
    ├── lg-monitor.sh
    └── run-with-monitor.sh

For each workflow: copy recorder.template.js → recordings/scripts/wN-<short-name>.js, copy tests/workflow.template/ → tests/wN-<short-name>/, and replace <WORKFLOW_PLACEHOLDER> markers with the workflow's short name.

Then install:

cd <target-dir> && npm install && npx playwright install chromium

3. Record each workflow

Per workflow:

1. Fill in recordings/scripts/wN-<short-name>.js: user-action sequence, recordHar.urlFilter regex (allow-list the target host; block third-party RUM/ads — see references/recording-with-playwright.md), and a real Chrome userAgent (the default HeadlessChrome UA triggers bot-blocking on many sites).
2. Run: node recordings/scripts/wN-<short-name>.js → writes recordings/har/wN-<short-name>.har
3. Convert: npx har-to-k6 recordings/har/wN-<short-name>.har -o tests/wN-<short-name>/from-har.js
4. Commit both HAR and from-har.js (audit trail for bundle-path changes).

If the recorder fails or produces an unusable HAR (bot-blocking, missing hydration, third-party noise), see the Recording section of references/gotchas.md and references/recording-with-playwright.md.

Prefer mcp-k6 recording and migration tools if available.

4. Build functional tests

Per workflow:

1. Hand-clean from-har.js into protocol.js — drop per-request UA headers, rename groups, parameterise BASE_URL, replace session tokens, drop sleep(1), add expect() on every load-bearing response. Full procedure in references/functional-tests.md.
2. Hand-write browser.js from the Playwright recorder using the 5-step procedure in references/functional-tests.md.
3. Run ./tests/run-all.sh. Do not proceed to §5 until it exits 0.

Prefer mcp-k6 migration tools for Playwright→k6/browser conversion.