/k6-browser-test

name: k6-browser-test
description: >-
  Generate a working k6 browser test (k6/browser) from a plain-language
  description of a user journey — no CSS selectors or technical detail needed.
  Explores the LIVE target site with a throwaway k6/browser session to discover
  real, verified selectors (getByRole/getByLabel/getByText, etc.), dismisses
  cookie/consent banners, then writes a functional or load test
  using expect() from k6-testing (Web-Vitals thresholds for load).
  Looks up k6/browser APIs via `k6 x docs`; validates
  with `k6 run`. Use when the user wants to write, author, or generate a k6
  browser/UI or load test with a real browser, or says
  things like "write a browser test for…", "test this login/checkout/search
  flow with k6", "click through my site and verify…", or describes navigating a
  site in prose. For a full multi-test performance suite use
  k6-perf-test-website; for HTTP/protocol (non-browser) tests use the general
  k6 skills; for browser or scripted checks in Grafana Cloud Synthetic
  Monitoring, use synthetic-monitoring-checks.
license: Apache-2.0
metadata:
  author: grafana-labs

k6 Browser Test (from prose, with live exploration)

Turn a plain-language user journey into a working, validated `k6/browser` functional test. The user describes what to do the way they'd tell a friend ("go to the site, log in, add a pizza to the cart, check the cart shows one item") — **you** discover the real selectors by driving the live site, so the user never has to supply a CSS selector, XPath, or `data-testid`.

> **Agent-agnostic:** steps describe capabilities ("run a k6 script", "write a > file"), not specific tools. Use whatever your harness provides. The only hard > dependencies are the `k6` binary with browser support and a POSIX shell — no > MCP, no Node, no Playwright.

What this skill produces (and what it doesn't)

• **Produces:** one `k6/browser` test file — functional by default (single

iteration, `expect()` assertions), or a browser *load* test (scenarios + Web-Vitals thresholds) when the user asks for load/performance.

• **Not in scope:** protocol/HTTP tests, HAR recording, or multi-test load

suites with SLOs. If the user wants a full performance suite, hand off to **k6-perf-test-website**. If they want HTTP/gRPC/WS, use the general k6 skills. If the script is destined for Grafana Cloud Synthetic Monitoring (a browser or scripted check), also reference the **synthetic-monitoring-checks** skill — it owns the SM check lifecycle (create/update, cadence, probe locations).

Prerequisites

• `k6 v1.2+` (`k6 version`) — the `getBy*` locator API this skill relies on

landed in v1.2.0 — plus a Chromium-based browser installed on this machine (e.g. Google Chrome) — k6 does **not** bundle one. Point `K6_BROWSER_EXECUTABLE_PATH` at a non-default install location.

• A POSIX shell (`bash`/`zsh`) — the exploration loop uses `mktemp`, `cp`, and

`env`. (Only the final `k6 run` in Step 7 has a PowerShell form.)

• **k6 v2+ is needed only for Step 5's `k6 x docs`** (automatic extension

resolution, no custom build). Verify once that it prints markdown; on v1.x — or if it misbehaves — use the fallbacks in [Step 5](#step-5-fill-api-gaps-with-k6-x-docs-only-if-needed). Everything else works the same.

• Network access from this host to the target site.

---

Step 1: Understand the journey

Restate the user's prose as an explicit, ordered step list and **echo it back** before exploring — a wrong reading is cheap to fix now, expensive after a script is written. Capture:

• **Target URL** (the entry point).
• **Ordered actions** ("click X", "type Y in the search box", "open the first

result").

• **The assertion(s)** — what proves success ("the cart shows 1 item", "the

page title contains 'Dashboard'", "'Rated!' appears").

• **Credentials**, if a login is involved. Take them via environment variables

(`__ENV.TEST_USERNAME` / `__ENV.TEST_PASSWORD` / `__ENV.TEST_TOKEN`) — never hardcode. Avoid reserved names: in zsh (default macOS shell) `USERNAME` is bound to the OS user, so `USERNAME=… k6 run` is silently ignored — use `env TEST_USERNAME=… TEST_PASSWORD=… k6 run …`.

• **Destructive actions** (place order, delete, send). Confirm with the user

before performing these during exploration, and prefer a safe stopping point. If you can't ask (non-interactive run): proceed through the step only against a demo/sandbox with no real fulfillment (e.g. saucedemo) and state why it's safe; against anything that looks real, stop before the step and surface it.

Example restatement:

> 1. Open `https://www.saucedemo.com` > 2. Log in as the standard user (creds via env) > 3. Add the first product to the cart > 4. **Assert:** the cart badge shows `1`

---

Step 2: Explore the live site to resolve selectors

This is the heart of the skill and what makes the output reliable. **Read [`references/explore.md`](references/explore.md)** for the full procedure.

Preflight once before the first run: `k6 version` (this skill needs v1.2+). If the first explorer run fails at browser launch ("browser not found" / executable-path errors), k6 couldn't find a Chromium — install Google Chrome or point `K6_BROWSER_EXECUTABLE_PATH` at one, then re-run. Catching this now beats a confusing failure mid-exploration.

In short:

1. Copy [`scripts/explore.template.js`](scripts/explore.template.js) to a **unique temp path** — `EXPLORER="$(mktemp -d)/explore.js"` — never a fixed name like `/tmp/explore.js` (why: [`references/explore.md`](references/explore.md)). Never save it to the user's project. 2. Run it headless against the target: `K6_BROWSER_HEADLESS=true TARGET=<url> k6 run "$EXPLORER"` 3. Read the `EXPLORE_CANDIDATES` line — a JSON list of visible elements with their naming signals (`text`, `ariaLabel`, `placeholder`, `label`, `value`, `testid`, `dataTest`, `nameAttr`, `role`). The signal→locator table in [`references/explore.md`](ref