k6-perf-test-website

k6-perf-test-website

使用 k6 对任意 公开网站进行性能测试的一套端到端、观点鲜明的工作流。该技能会生成：

• 已搭建好的项目，其中每个用户描述的工作流对应一个文件夹。
• 功能性协议测试和浏览器测试（运行负载测试前必须通过）。
• 混合负载测试（每种测试类型〔冒烟／平均／压力／突增／持续／断点〕包含一个协议场景和 1 个浏览器 VU）。
• 由 SLO 支持的阈值，带有按端点标记和 Web Vitals。
• 跨平台的负载生成器监控 sidecar。
• 用户拥有后端时，可选的 Grafana 端调查。
• 最后生成结构化的 Markdown 报告。

只想根据一段自然语言描述的操作流程，编写一个功能性浏览器测试？ 此技能会构建一套完整的多测试性能套件。如果只需要一个 k6/browser 功能测试（或独立的浏览器负载测试），并希望通过探索实时网站来发现选择器，请改用 k6-browser-test 技能。

此技能坚持以下几项原则，不应悄悄覆盖：

• 始终先询问工作流。 不要猜测。
• 功能测试必须全部通过，才能运行负载测试。
• 始终监控负载生成器——看起来像是服务器变慢，实际上往往是笔记本变慢。
• 验证用本地环境，扩展用云端——但要询问用户每种测试类型的运行位置；不要硬编码。
• 不使用共享的 tests/lib/。 更倾向于重复编写迭代主体；这样每个脚本在事故复盘时都能清晰易读。

先决条件

• 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，可便捷地通过 shell 查询、发现数据源，以及派发 Grafana Cloud k6 云端运行任务。
• k6 二进制文件 — 用于本地验证运行和断点探测。
• k6 x docs（xk6-docs）— 在无法使用 mcp-k6 时，查询编写或编辑脚本所需的 k6 API。

如果未配置这些工具，此技能会退回使用普通 CLI 工具（k6、npx、curl）和手写脚本。此技能不负责配置工具链；请遵循用户现有的配置流程。

明确不包含的内容：

• 仅协议测试套件（不在此技能范围内）。
• 仅 API 应用／非浏览器应用。
• 原生移动端测试。
• 除查找并标记断点外的容量规划。

工作流概览

按顺序逐项完成。下方为每个步骤提供了对应章节。

1. 向用户询问工作流。§1
2. 使用 assets/ 搭建项目。§2
3. 使用 Playwright 记录每个工作流。§3
4. 构建功能性协议测试和浏览器测试；运行 tests/run-all.sh， 直到全部通过。§4
5. 设计由 SLO 支持的阈值和按端点设置的标记。 §5
6. 构建混合负载测试，每种测试类型对应一个文件。 §6
7. 使用 LG sidecar 在本地运行验证。 §7
8. 将用户选择在云端运行的测试类型推送到 Grafana Cloud k6。 §8
9. 使用 Grafana 调查后端（如果用户拥有后端）。 §9
10. 向用户汇报。§10

1. 梳理工作流

最重要的一步。 如果没有明确的工作流，后续每一步都只能靠猜测。

向用户询问 references/workflow-elicitation.md 中的问题，并将答案记录在脚手架项目中的 runbook.md 内。

必须记录：2-4 个命名工作流、凭据、读操作与写操作、浸泡测试期间需要避免的破坏性操作、担忧事项清单、现有 SLO、后端归属和 Grafana 访问权限，以及每种测试类型是在本地运行还是在 Grafana Cloud k6 中运行。

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

2. 搭建项目脚手架

将此技能中的 assets/ 目录树复制到用户选择的目录。此技能的 assets/ 目录位于 <SKILL_DIR>/assets/，其中 <SKILL_DIR> 是此技能目录的绝对路径——你的运行环境会提供此信息（例如，opencode 会在技能元数据前加上 Base directory for this skill:）。如果无法从上下文确定 <SKILL_DIR>，请询问用户。

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

如果沙盒权限阻止执行 cp -R，请使用 Agent 的文件写入工具逐个复制文件。

脚手架目录结构：

<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

针对每个工作流：将 recorder.template.js 复制为 recordings/scripts/wN-<short-name>.js，将 tests/workflow.template/ 复制为 tests/wN-<short-name>/，并将 <WORKFLOW_PLACEHOLDER> 标记替换为该工作流的短名称。

然后安装：

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

3. 记录每个工作流

针对每个工作流：

1. 填写 recordings/scripts/wN-<short-name>.js：用户操作序列、recordHar.urlFilter 正则表达式（将目标主机加入允许列表；屏蔽第三方 RUM/广告——参见 references/recording-with-playwright.md），以及真实的 Chrome userAgent（默认的 HeadlessChrome UA 会触发许多网站的机器人拦截）。
2. 运行：node recordings/scripts/wN-<short-name>.js → 写入 recordings/har/wN-<short-name>.har
3. 转换：npx har-to-k6 recordings/har/wN-<short-name>.har -o tests/wN-<short-name>/from-har.js
4. 提交 HAR 和 from-har.js（作为捆绑路径变更的审计记录）。

如果录制器运行失败，或生成了不可用的 HAR（机器人拦截、未完成 hydration、第三方噪声），请参阅 references/gotchas.md 中的 Recording 部分以及 references/recording-with-playwright.md。

如果可用，优先使用 mcp-k6 录制和迁移工具。

4. 构建功能测试

针对每个工作流：

1. 手动清理 from-har.js 并生成 protocol.js——移除每个请求的 UA 标头、重命名组、将 BASE_URL 参数化、替换会话令牌、移除 sleep(1)，并为每个关键响应添加 expect()。完整流程见 references/functional-tests.md。
2. 根据 Playwright 录制结果，按照 references/functional-tests.md 中的 5 步流程手动编写 browser.js。
3. 运行 ./tests/run-all.sh。在退出代码为 0 之前，不要继续 §5。

优先使用 mcp-k6 迁移工具进行 Playwright→k6/browser 转换。

5. 设计 SLO 和阈值

根据用户在 §1 中说明的 SLO，调整 assets/tests/workflow.template/ 中较为严格的默认值。分为四层：

1. 全局 SLO — 总体错误率和聚合延迟。
2. 每个端点的阈值 — 为每个协议请求添加标签，并为每个标签设置阈值。
3. 每次迭代的阈值 — 工作流耗时和迭代完成率。
4. 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'],

每次迭代的调优、performance.mark 自定义 Trend 模式、iteration_completed Rate、断点失败时中止的阈值，以及放宽规则，请参阅 references/slo-design.md。

6. 构建混合负载测试

每个工作流按测试类型各建一个文件。每个文件包含一个协议场景（施加负载）和一个浏览器 VU（在负载下测量 Web Vitals）。 断点测试仅使用协议 — 浏览器 VU 会给信号带来噪声。

类型	执行器	默认值
smoke	constant-vus	3 VU × 1m
average	ramping-vus	0→20→0，持续 14m
stress	ramping-vus	0→50→0，持续 20m
spike	ramping-vus	0→100→0，持续 2m
soak	ramping-vus	0→10→0，持续 70m
breakpoint	ramping-arrival-rate	5/s→500/s，持续 20m，abortOnFail

查看 smoke 测试结果后，按工作流调整参数。设计依据请参见 references/test-types.md；关于为何每种类型使用一个文件，以及为何文件间允许重复，请参见 references/hybrid-load-design.md。

7. 使用 LG sidecar 在本地运行

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

在后台启动 lg-monitor.sh，运行 k6，然后输出摘要判定：OK（≥30% 空闲）、NOTE（10–30%）或 WARNING （<10%）。如果出现 WARNING，说明笔记本电脑是瓶颈 — 请减少 VU、切换到云端，或使用多个 LG 分担负载。参见 references/lg-monitoring.md。

8. 推送到 Grafana Cloud k6

对于 §1 运行手册中指定在云端运行的每种测试类型：

1. 确认 k6 cloud login 可正常使用（该技能不负责身份验证设置）。
2. 先在本地运行 smoke 测试，验证脚本。
3. k6 cloud run tests/wN-<short-name>/<type>.js
4. 记录运行 URL，以便填入 §10 报告。

**费用提醒：**浏览器 VU 小时的费用是协议 VU 小时的 10 倍。 Soak 和 breakpoint 的费用最高。长时间运行前请检查限额。 参见 references/local-vs-cloud.md。

9. 调查后端

仅当用户负责后端且拥有 Grafana 访问权限时执行。

1. 通过 mcp-grafana 或 gcx datasources list 查找数据源。
2. 向用户询问服务标签键 — 不要猜测。
3. 将 k6 运行时间段与 RED 指标、错误日志、追踪和性能分析数据关联起来（Pyroscope — 使用明确的 from/to 指定运行时间段）。
4. 提供具体证据：时间戳、查询字符串、面板链接。

完整流程请参见 references/grafana-investigation.md，其中包括如何在报告缺失情况前确认其确实不存在。

10. 汇报结果

根据 references/reporting.md 中的报告模板填写：

• 摘要 — 工作流、测试类型、日期
• SLO — 各阈值的通过/失败情况
• 发现 — 每项发现用一段文字说明，按严重程度排序，并提供具体证据
• 证据 — k6 输出路径、LG 监控 CSV、云端运行 URL、Grafana 链接
• 建议的后续步骤

务必具体。“延迟很高”不算一项发现。“GetPizza 的 p(95) 在约第 200 次迭代时达到 1.4s；Grafana 面板链接显示，这与推荐服务持续 100% 的 CPU 使用率相关”才算。

---

参考索引

• references/workflow-elicitation.md — §1 的逐字提问脚本。
• references/recording-with-playwright.md — HAR 捕获、第三方过滤正则表达式、hydration 信号。
• references/functional-tests.md — Playwright→k6/浏览器转换的 5 步流程。
• references/hybrid-load-design.md — 协议 + 1 个浏览器 VU 的设计依据、重复执行论据。
• references/slo-design.md — 完整的阈值依据、异步与同步指标采集。
• references/test-types.md — 全部六种测试类型的定义和默认值。
• references/lg-monitoring.md — sidecar 存在的原因及其输出的读取方法。
• references/local-vs-cloud.md — 对比框架、成本模型、各测试类型的权衡。
• references/grafana-investigation.md — 通用后端调查流程。
• references/gotchas.md — 通用注意事项。
• references/reporting.md — 最终报告模板。