k6-perf-test-website

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

一种使用k6对任意公共网站进行端到端性能测试的标准化工作流。此技能可生成：

一个脚手架项目，每个用户描述的工作流对应一个文件夹。
功能性协议+浏览器测试（负载测试前必须通过）。
针对每种测试类型（冒烟/常规/压力/尖峰/持续/断点）的混合负载测试（协议场景+1个浏览器VU）。
带有端点标记和Web Vitals的基于SLO的阈值。
跨平台负载生成器监控侧车。
当用户拥有后端时，可选的Grafana端调查流程。
最终生成结构化Markdown报告。

此技能有一些固定规则，请勿擅自修改：

始终先明确工作流，不要猜测。
功能性测试必须全部通过后才能运行负载测试。
始终监控负载生成器——服务器看起来慢往往是本地设备性能不足导致的。
本地用于验证，云端用于大规模测试——但要询问用户每种测试类型的运行环境，不要硬编码。
不共享
tests/lib/
目录。宁愿重复代码，也要保证每个脚本在事件复盘时能独立清晰阅读。

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.

k6 ≥ v2.0.0（执行
```
k6 version
```
查看）——需要稳定的
```
k6/browser
```
、
```
expect()
```
、async/await迭代函数和每个请求的
```
tags
```
功能。
Node.js ≥ 20 + npm。
Playwright并下载Chromium（执行
```
npx playwright install chromium
```
）。
har-to-k6
（执行
```
npm i -D har-to-k6
```
安装）。
负载生成器主机能够访问目标网站。

技能优先使用以下已安装工具：

```
mcp-k6
```
——脚本创建、Playwright→k6/browser迁移、API查询。优先使用它而非手动编写k6模板代码。
```
mcp-grafana
```
——在第9节的后端调查环节中，实时查询Prometheus/Loki/Tempo/Pyroscope数据。
```
gcx
```
——Grafana Cloud CLI，用于便捷的命令行查询、数据源发现和Grafana Cloud k6云端任务调度。
```
k6
```
二进制文件——本地验证运行和断点测试。
```
k6 x docs
```
（xk6-docs）——在没有
```
mcp-k6
```
时，编写或编辑脚本时查询k6 API。

如果未配置这些工具，技能会退回到纯CLI工具（

k6

、

npx

、

curl

）和手动编写脚本。技能不负责工具链的安装配置，请遵循用户现有的安装流程。

明确不支持的场景：

仅协议测试套件（超出此技能范围）。
仅API/非浏览器应用。
原生移动应用测试。
除查找和标记断点之外的容量规划。

Workflow overview

工作流概述

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

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

按顺序完成以下步骤，每个步骤下方都有详细说明。

向用户明确工作流。§1
从
```
assets/
```
目录生成项目脚手架。§2
使用Playwright录制每个工作流。§3
构建功能性协议+浏览器测试；运行
```
tests/run-all.sh
```
直到全部通过。§4
设计基于SLO的阈值和端点标记。§5
构建混合负载测试，每种测试类型对应一个文件。§6
配合LG侧车在本地运行验证。§7
将用户选择的测试类型推送到Grafana Cloud k6运行。§8
使用Grafana调查后端（如果用户拥有后端）。§9
向用户提交报告。§10

1. Elicit workflows

1. 明确工作流

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.

这是最重要的一步。没有明确的工作流，后续所有步骤都是猜测。

询问用户

references/workflow-elicitation.md

中的问题，并将答案记录在脚手架项目旁的

runbook.md

中。

必须收集的信息：2-4个命名工作流、凭据、读/写操作、持续测试中需避免的破坏性操作、关注点列表、现有SLO、后端所有权和Grafana访问权限，以及每种测试类型的运行环境（本地或Grafana Cloud k6）。

如果用户无法说出至少一个工作流，请停止并澄清，不要继续。

2. Scaffold the project

2. 生成项目脚手架

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.

bash

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

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:

bash

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

将此技能的

assets/

assets/

目录位于

<SKILL_DIR>/assets/

，其中

<SKILL_DIR>

是此技能目录的绝对路径——你的运行环境会提供此路径（例如opencode会在技能元数据前添加“Base directory for this skill:”行）。如果无法从上下文确定

<SKILL_DIR>

，请询问用户。

bash

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

如果沙箱权限阻止了

cp -R

命令，请通过你的代理文件写入工具逐个复制文件。

生成的目录结构：

<target-dir>/
├── package.json
├── .gitignore
├── README.md
├── runbook.md                       # 从第1节的答案创建
├── recordings/
│   ├── README.md
│   └── scripts/
│       └── recorder.template.js     # 每个工作流复制一份→wN-<short-name>.js，…
├── tests/
│   ├── run-all.sh
│   └── workflow.template/           # 每个工作流复制一份→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

针对每个工作流：复制

recorder.template.js

→

recordings/scripts/wN-<short-name>.js

，复制

tests/workflow.template/

→

tests/wN-<short-name>/

，并将

<WORKFLOW_PLACEHOLDER>

标记替换为工作流的简称。

然后执行安装：

bash

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

3. Record each workflow

3. 录制每个工作流

Per workflow:

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).

Run:

node recordings/scripts/wN-<short-name>.js

→ writes

recordings/har/wN-<short-name>.har

Convert:

npx har-to-k6 recordings/har/wN-<short-name>.har -o tests/wN-<short-name>/from-har.js

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.

针对每个工作流：

填写
```
recordings/scripts/wN-<short-name>.js
```
：用户操作序列、
```
recordHar.urlFilter
```
正则表达式（允许目标主机，阻止第三方RUM/广告——参考
```
references/recording-with-playwright.md
```
），以及真实的Chrome
```
userAgent
```
（默认的
```
HeadlessChrome
```
UA会触发很多网站的机器人拦截）。

运行：

node recordings/scripts/wN-<short-name>.js

→生成

recordings/har/wN-<short-name>.har

转换：

npx har-to-k6 recordings/har/wN-<short-name>.har -o tests/wN-<short-name>/from-har.js

提交HAR文件和
```
from-har.js
```
（用于跟踪资源路径变化的审计线索）。

如果录制失败或生成无法使用的HAR文件（机器人拦截、缺失内容渲染、第三方干扰），请参考

references/gotchas.md

和

references/recording-with-playwright.md

中的录制部分。

如果可用，优先使用

mcp-k6

的录制和迁移工具。

4. Build functional tests

4. 构建功能性测试

Per workflow:

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
```
.
Hand-write
```
browser.js
```
from the Playwright recorder using the 5-step procedure in
```
references/functional-tests.md
```
.
Run
```
./tests/run-all.sh
```
. Do not proceed to §5 until it exits 0.

Prefer

mcp-k6

migration tools for Playwright→k6/browser conversion.

针对每个工作流：

手动清理
```
from-har.js
```
并转换为
```
protocol.js
```
——删除每个请求的UA头、重命名分组、参数化
```
BASE_URL
```
、替换会话令牌、删除
```
sleep(1)
```
、为每个关键响应添加
```
expect()
```
。完整流程参考
```
references/functional-tests.md
```
。
根据Playwright录制内容，按照
```
references/functional-tests.md
```
中的5步流程手动编写
```
browser.js
```
。
运行
```
./tests/run-all.sh
```
。直到脚本返回0才能进入第5步。

如果可用，优先使用

mcp-k6

的Playwright→k6/browser迁移工具。

5. Design SLOs and thresholds

5. 设计SLO与阈值

Adjust the opinionated defaults in

assets/tests/workflow.template/

to the user's stated SLOs from §1. Four layers:

Global SLOs — overall error rate + aggregate latency.
Per-endpoint thresholds — tag every protocol request, threshold per tag.
Per-iteration thresholds — workflow time + iteration completion rate.
Web Vitals — LCP/INP/CLS only (no FCP).

Default globals:

http_req_failed: ['rate<0.01'],
http_req_duration: ['p(95)<500'],
checks: ['rate>0.99'],

Per-endpoint tagging:

http.get(`${BASE_URL}/api/things`, { tags: { name: 'GetThings' } });
'http_req_duration{name:GetThings}': ['p(95)<400', 'p(99)<800'],

Web Vitals:

browser_web_vital_lcp: ['p(95)<2500'],
browser_web_vital_inp: ['p(95)<200'],
browser_web_vital_cls: ['p(95)<0.1'],

See

references/slo-design.md

for per-iteration tuning, the

performance.mark

custom-Trend pattern,

iteration_completed

Rate, breakpoint abort-on-fail thresholds, and loosening rules.

根据第1节中用户说明的SLO，调整

assets/tests/workflow.template/

中的默认配置。分为四层：

全局SLO——整体错误率+聚合延迟。
端点阈值——为每个协议请求添加标记，针对每个标记设置阈值。
迭代阈值——工作流时长+迭代完成率。
Web Vitals——仅包含LCP/INP/CLS（不包含FCP）。

默认全局配置：

http_req_failed: ['rate<0.01'],
http_req_duration: ['p(95)<500'],
checks: ['rate>0.99'],

端点标记示例：

http.get(`${BASE_URL}/api/things`, { tags: { name: 'GetThings' } });
'http_req_duration{name:GetThings}': ['p(95)<400', 'p(99)<800'],

Web Vitals配置：

browser_web_vital_lcp: ['p(95)<2500'],
browser_web_vital_inp: ['p(95)<200'],
browser_web_vital_cls: ['p(95)<0.1'],

参考

references/slo-design.md

了解迭代调优、

performance.mark

自定义趋势模式、

iteration_completed

比率、断点测试的失败即终止阈值，以及宽松规则。

6. Build hybrid load tests

6. 构建混合负载测试

Per workflow, one file per test type. Each file has a protocol scenario (drives load) plus a single browser VU (measures Web Vitals under load). Breakpoint is protocol-only — a browser VU adds noise to the signal.

Type	Executor	Defaults
smoke	constant-vus	3 VUs × 1m
average	ramping-vus	0→20→0 over 14m
stress	ramping-vus	0→50→0 over 20m
spike	ramping-vus	0→100→0 over 2m
soak	ramping-vus	0→10→0 over 70m
breakpoint	ramping-arrival-rate	5/s→500/s over 20m, abortOnFail

Tune per workflow once you've seen smoke results. See

references/test-types.md

for rationale and

references/hybrid-load-design.md

for why one file per type and why duplication between files is acceptable.

针对每个工作流，每种测试类型对应一个文件。每个文件包含一个协议场景（生成负载）和一个浏览器VU（在负载下测量Web Vitals）。断点测试仅使用协议——浏览器VU会干扰信号。

测试类型	执行器	默认配置
冒烟测试	constant-vus	3个VU × 1分钟
常规测试	ramping-vus	0→20→0，持续14分钟
压力测试	ramping-vus	0→50→0，持续20分钟
尖峰测试	ramping-vus	0→100→0，持续2分钟
持续测试	ramping-vus	0→10→0，持续70分钟
断点测试	ramping-arrival-rate	5次/秒→500次/秒，持续20分钟，失败即终止

查看冒烟测试结果后，针对每个工作流调整配置。参考

references/test-types.md

了解设计理由，参考

references/hybrid-load-design.md

了解为何每种类型对应一个文件，以及为何允许文件间代码重复。

7. Run locally with LG sidecar

7. 配合LG侧车本地运行

bash

./tools/run-with-monitor.sh tests/wN-<short-name>/smoke.js

Starts

lg-monitor.sh

in the background, runs k6, then prints a summary verdict: OK (≥30% idle), NOTE (10–30%), or WARNING (<10%). If WARNING, the laptop is the bottleneck — reduce VUs, switch to cloud, or split across multiple LGs. See

references/lg-monitoring.md

bash

./tools/run-with-monitor.sh tests/wN-<short-name>/smoke.js

在后台启动

lg-monitor.sh

，运行k6，然后输出总结结论：OK（空闲率≥30%）、NOTE（空闲率10–30%）或WARNING（空闲率<10%）。如果是WARNING，说明本地设备是瓶颈——减少VU数量、切换到云端，或使用多个负载生成器。参考

references/lg-monitoring.md

。

8. Push to Grafana Cloud k6

8. 推送到Grafana Cloud k6

For each test type assigned to cloud in the §1 runbook:

Confirm
```
k6 cloud login
```
works (the skill does not own auth setup).
Run smoke locally first to validate the script.

k6 cloud run tests/wN-<short-name>/<type>.js

Capture the run URL for the §10 report.

Cost reminder: browser VU-hours are billed 10× protocol VU-hours. Soak and breakpoint are the most expensive. Check limits before long runs. See

references/local-vs-cloud.md

针对第1节运行手册中指定为云端运行的每种测试类型：

确认
```
k6 cloud login
```
可用（技能不负责认证配置）。
先在本地运行冒烟测试验证脚本。

执行

k6 cloud run tests/wN-<short-name>/<type>.js

记录运行URL，用于第10节的报告。

成本提醒：浏览器VU小时的计费是协议VU小时的10倍。持续测试和断点测试成本最高。长时间运行前请检查限制。参考

references/local-vs-cloud.md

。

9. Investigate the backend

9. 调查后端

Only if the user owns the backend and has Grafana access.

Discover datasources via
```
mcp-grafana
```
or
```
gcx datasources list
```
.
Ask the user for service label keys — do not guess.
Correlate the k6 run window with RED metrics, error logs, traces, and profiles (Pyroscope — use explicit
```
from
```
/
```
to
```
for the run window).
Hand back specific evidence: timestamps, query strings, panel links.

See

references/grafana-investigation.md

for the full flow including how to verify absence before reporting it.

仅当用户拥有后端且具备Grafana访问权限时执行此步骤。

通过
```
mcp-grafana
```
或
```
gcx datasources list
```
发现数据源。
向用户询问服务标签键——不要猜测。
将k6运行时间窗口与RED指标、错误日志、链路追踪和性能分析（Pyroscope——使用明确的
```
from
```
/
```
to
```
指定运行窗口）关联。
返回具体证据：时间戳、查询字符串、面板链接。

参考

references/grafana-investigation.md

了解完整流程，包括如何在报告前验证问题是否存在。

10. Report back

10. 提交报告

Fill in the report template from

references/reporting.md

Summary — workflows, test types, dates
SLOs — pass/fail per threshold
Findings — one paragraph per finding, ordered by severity, with specific evidence
Evidence — k6 output paths, LG monitor CSVs, cloud run URLs, Grafana links
Suggested next steps

Always be specific. "Latency is high" is not a finding. "GetPizza p(95) hit 1.4s at iteration ~200; correlated with sustained 100% CPU on the recommender service per Grafana panel link" is.

填写

references/reporting.md

中的报告模板：

摘要——工作流、测试类型、日期
SLO情况——每个阈值的通过/失败状态
发现——每个发现对应一段内容，按严重程度排序，附带具体证据
证据——k6输出路径、LG监控CSV文件、云端运行URL、Grafana链接
建议下一步操作

务必具体。“延迟高”不是有效发现。“GetPizza接口的p(95)延迟在第200次迭代时达到1.4秒；与推荐服务CPU持续100%相关，参考Grafana面板链接”才是有效发现。

Reference index

参考索引

```
references/workflow-elicitation.md
```
— verbatim question script for §1.
```
references/recording-with-playwright.md
```
— HAR capture, third-party filter regex, hydration signals.
```
references/functional-tests.md
```
— 5-step Playwright→k6/browser conversion procedure.
```
references/hybrid-load-design.md
```
— protocol + 1 browser VU rationale, duplication argument.
```
references/slo-design.md
```
— full threshold rationale, async vs sync metric capture.
```
references/test-types.md
```
— definitions and defaults for all six test types.
```
references/lg-monitoring.md
```
— why the sidecar exists, how to read its output.
```
references/local-vs-cloud.md
```
— framing, cost model, per-test-type tradeoffs.
```
references/grafana-investigation.md
```
— generic backend investigation flow.
```
references/gotchas.md
```
— generic pitfalls.
```
references/reporting.md
```
— final report template.

```
references/workflow-elicitation.md
```
— 第1节使用的逐字提问脚本。
```
references/recording-with-playwright.md
```
— HAR捕获、第三方过滤正则、内容渲染信号。
```
references/functional-tests.md
```
— Playwright→k6/browser转换的5步流程。
```
references/hybrid-load-design.md
```
— 协议+1个浏览器VU的设计理由、代码重复的合理性。
```
references/slo-design.md
```
— 阈值设计的完整理由、异步与同步指标捕获。
```
references/test-types.md
```
— 所有六种测试类型的定义和默认配置。
```
references/lg-monitoring.md
```
— 侧车存在的原因、如何解读其输出。
```
references/local-vs-cloud.md
```
— 场景对比、成本模型、每种测试类型的权衡。
```
references/grafana-investigation.md
```
— 通用后端调查流程。
```
references/gotchas.md
```
— 常见陷阱。
```
references/reporting.md
```
— 最终报告模板。

k6-perf-test-website

Original

Translation

`k6-perf-test-website`

`k6-perf-test-website`

Prerequisites

前置条件

Workflow overview

工作流概述

1. Elicit workflows

1. 明确工作流

2. Scaffold the project

2. 生成项目脚手架

3. Record each workflow

3. 录制每个工作流

4. Build functional tests

4. 构建功能性测试

5. Design SLOs and thresholds

5. 设计SLO与阈值

6. Build hybrid load tests

6. 构建混合负载测试

7. Run locally with LG sidecar

7. 配合LG侧车本地运行

8. Push to Grafana Cloud k6

8. 推送到Grafana Cloud k6

9. Investigate the backend

9. 调查后端

10. Report back

10. 提交报告

Reference index

参考索引