k6

k6 脚本生成

效率提示： 这是一套简短的线性流程（阅读示例 → 调整 → 保存 → 验证 → 检查）。待办列表只会重复这些标题，并无益处，因此无需花时间制定计划，直接执行步骤即可。

不依赖特定 Agent： 以下步骤描述的是能力，而非特定工具。如果某个步骤要求“获取 URL”或“写入文件”，请使用 Agent 提供的相应能力（例如网页获取工具、文件写入工具，或 shell curl/tee）。

---

步骤 1：选择合适的示例文件

只阅读与用户请求相符的文件。示例提供结构框架，包括正确的框架结构、选项形式和导入模式。

用户需求	阅读此文件
HTTP REST、身份验证流程、批量请求	examples/http.js
使用 parseHTML 解析 HTML、SharedArray	examples/html.js
WebSocket	examples/websocket.js
gRPC	examples/grpc.js
浏览器自动化	examples/browser.js
浏览器 + 功能测试 / expect() / k6-testing	examples/functional.js（浏览器场景）
功能/集成测试、expect()、k6-testing	examples/functional.js
自定义指标、执行模块、handleSummary、per-vu-iterations	examples/metrics.js
负载模式、所有执行器（渐增、到达率、每个 VU 等）	examples/executors.js
云端运行、--local-execution、cloud 选项	examples/cloud.js
加密（HMAC、MD5、SHA256）或编码（base64）	examples/crypto-encoding.js
xk6-faker	examples/ext-faker.js
xk6-redis	examples/ext-redis.js
xk6-sql / sqlite3 / postgres	examples/ext-sql.js
xk6-exec	examples/ext-exec.js
xk6-dns	examples/ext-dns.js
xk6-tls	examples/ext-tls.js
xk6-tcp	examples/ext-tcp.js
xk6-crawler	examples/ext-crawler.js

示例文件位于与此 SKILL.md 同级的 examples/ 目录中。

当请求符合多行条件时（例如“浏览器”+“功能测试”），优先选择断言风格符合意图的行。如果用户说“功能测试”“断言”“验证”或“expect”，即使测试涉及浏览器，也使用 functional.js，因为它演示了如何使用 expect() 和可自动重试的浏览器匹配器。对于不强调正确性断言的浏览器负载/性能测试，则使用 browser.js。

根据自然语言描述编写浏览器测试？ 如果用户用文字描述浏览器流程，但尚未确定选择器——也就是说，必须通过操作实时网站来发现选择器——请使用 k6-browser-test 技能。它会探索实时页面，在编写测试前确定实际的 getBy* 定位器。若页面结构和选择器已知，则使用上方的浏览器相关行。

---

步骤 2：调整示例

以已加载的示例为起点，根据用户的具体要求进行调整：

• 更改端点、VU 数量、持续时间和阈值
• 添加或移除场景步骤
• 重命名函数和变量，使其符合具体领域
• 每个表达式都必须完整且可运行——不得使用 { ... }、// TODO 或存根
• 按请求实现——不要过度构建。 只实现用户明确要求的内容。不要添加自定义请求标签、额外的 sleep() 调用、其他端点或用户未要求的 options。未请求的复杂性会降低质量，也会降低对规范的遵循度。

对于多场景脚本（浏览器 + HTTP、云端）：使用命名的 scenarios，并通过 exec 指向不同的导出函数。

---

步骤 3：查阅文档以补足空缺（仅在需要时）

示例涵盖了常见模式。直接据此调整即可。如果示例已提供所需的全部内容，请完全跳过此步骤。

仅在以下情况下查阅文档：

• 用户要求使用示例中未演示的 API 或选项，或
• 你不确定确切的签名、选项名称或返回类型

存在空缺时，先确定文档命令（每个会话只需一次）。

k6 x docs CLI 只有在检测到 TTY 时才会渲染内容。由于 Agent 以非交互方式运行，每次调用都要用 script 分配伪 TTY，并将去除 ANSI 转义码的内容通过管道输出到 stdout：

# Detect OS once (macOS vs Linux have different `script` flags):
if [[ "$(uname -s)" == "Darwin" ]]; then
  DOCS_CMD="script -q /dev/null k6 x docs"
else
  DOCS_CMD="script -qc 'k6 x docs' /dev/null"
fi

# Verify it works — should print a topic list, NOT a "browse files" guide:
$DOCS_CMD 2>/dev/null | head -5

如果输出仍显示“k6 documentation is a directory of markdown files”，说明 TTY 包装未生效。请改用 Web 文档：https://grafana.com/docs/k6/latest/ — 使用 Agent 可用的任意网页抓取功能获取页面（内置抓取工具，或在 shell 中使用 curl）。

如果 k6 x docs 完全无法运行（命令未找到、配置或 404 错误），请阅读 SETUP.md — 其中介绍了 k6 v1.7.0+ 的自动配置，以及旧版本的手动 xk6 构建方式。

然后查找所需内容：

$DOCS_CMD <path>              # e.g. javascript-api k6-http
$DOCS_CMD <path> --depth 2
$DOCS_CMD search <term>

常见 CLI 路径和两次调用策略见 docs-guidance.md。

不要使用 unpkg、@types/k6 或任何 npm 类型定义 URL。

---

步骤 4：保存

每个脚本的第 1 行必须是生成说明注释。先获取当前 UTC 时间戳（文件内容取决于它，因此不能与写入操作并行）：

date -u +%Y-%m-%dT%H:%M:%SZ

然后将其作为第 1 行：

// Generated by grafana-k6 on 2026-03-25T22:02:20.203Z

保存到 k6/scripts/<descriptive-name>.js。文件名使用小写 kebab-case。如果你的文件写入功能不会自动创建父目录，请先运行 mkdir -p k6/scripts。

磁盘上的脚本文件就是交付物 — 始终要写入文件。绝不能只在聊天中展示脚本就结束任务：步骤 5–7（验证、审查、提交）都要求文件存在于 k6/scripts/<name>.js。如果写入失败，请重试后再继续。

---

步骤 5：验证

从上到下匹配 — 命中第一行后即采用：

脚本类型	命令
导入 k6/browser	k6 run k6/scripts/<name>.js
任意 ramping-vus 或 *-arrival-rate 场景	k6 inspect k6/scripts/<name>.js — 完整运行会针对目标执行整个负载配置
其他命名的 executor: 代码块（短场景）	k6 run k6/scripts/<name>.js
其他所有情况（HTTP、WS、gRPC）	k6 run --vus 1 --iterations 1 k6/scripts/<name>.js

**通过标准：**对于功能和浏览器脚本，只有退出代码为 0，且摘要中没有失败的检查或 expect() 错误，验证才算通过 — 脚本即使运行完成，但断言失败，也不算验证通过。k6 的错误输出会指出失败的具体定位器或断言（以及等待的内容）；请据此修复选择器或逻辑。对于负载测试，退出代码为 0 即表示通过；负载下仅有阈值超限（退出代码 99）也可以接受。

如果验证失败：读取 stderr，修复根本原因，然后重试，最多 3 次。失败 3 次后，展示错误并询问用户如何继续（如果是在无人值守的情况下运行，则交付最佳尝试，并明确报告尚未解决的错误）。

---

步骤 6：最佳实践审查

通用检查（所有脚本）

根据以下规则检查脚本。此清单具有权威性——只有在不确定某条具体规则时，才查阅文档（$DOCS_CMD best-practices 或 https://grafana.com/docs/k6/latest/using-k6/）。

• export const options 中设置合理的 VU 数量和持续时间。 默认 VU 数量和持续时间应确保测试开箱即用且有意义。
• 为每个负载测试定义 thresholds。 如果没有阈值，即使性能退化，测试运行也不会在 CI 中失败，这会让负载测试失去意义。至少应包含 http_req_duration 和 http_req_failed（或对应协议的指标）。纯功能测试——仅执行单次迭代和 expect() 的脚本——可以跳过此项。
• 在闭合模型（基于 VU）的负载测试中加入 sleep()。 sleep() 表示用户思考时间；没有它，VU 会以远超真实用户的速度猛击端点，导致吞吐量虚高，并给被测系统带来过大压力。此规则适用于基于 VU 的 HTTP、WebSocket、gRPC、加密和扩展脚本。开放模型执行器（constant-arrival-rate、ramping-arrival-rate）已经按目标速率调度迭代，因此通常不需要 sleep()——它只会占用 VU，而不会改变施加的负载。浏览器脚本应改用 page.waitForTimeout()；单次迭代的功能测试和一次性连接演示脚本可以跳过此项。在事件驱动的 WebSocket 脚本中，应将 sleep() 放在 close 处理程序内（参见 examples/websocket.js）——在主函数体中休眠会阻塞事件循环，导致任何消息都无法到达。
• 断言每个响应。 浏览器脚本：使用 k6-testing 中的 expect()——它会针对定位器自动重试，并可替代 waitFor() + isVisible() + check() 链式调用。如果需要在异步浏览器函数中使用可跟踪指标的 check()，标准的 k6 中的 check 就可以满足需求，前提是谓词为同步函数——先对值使用 await，再进行检查。只有在谓词本身必须对某个值使用 await 时，才使用 k6-utils 包装器（https://jslib.k6.io/k6-utils/1.5.0/index.js）：裸的 async 谓词会返回一个 Promise，该 Promise 始终为真值，因此检查会悄无声息地通过。HTTP/gRPC/WS 脚本：使用 check() 执行可跟踪指标的断言，或在功能测试中使用 expect()。悄无声息的失败比明确报错更糟糕。
• **浏览器脚本：**使用 try/finally 包裹交互，并在 finally 中调用 page.close()，确保即使断言抛出异常，页面也能清理干净。
• **gRPC 脚本：**使用 try/finally 包裹每次迭代中的调用，并在 finally 块中调用 client.close()，确保即使检查在迭代中途抛出异常，连接也能释放。
• **WebSocket 脚本：**使用 try/catch 包裹对传入消息的 JSON.parse 调用——服务端可能会发送非 JSON 帧，单个错误帧不应导致 VU 崩溃。
• 顶层不得使用 let/var——应使用 const，因为模块作用域中的状态会由多个 VU 共享，而在该作用域中使用可变状态几乎总是错误的。
• 不得使用已弃用的导入——WebSocket 应使用 k6/websockets；k6/ws 和 k6/experimental/websockets 均已弃用。

负载与断点测试

• 断点测试：逐步提高 施加负载，而不是 VU 数量。 使用开放模型执行器（ramping-arrival-rate），使请求速率不受系统变慢的影响；闭合模型（ramping-vus）会在延迟上升时自行降低速率，从而掩盖系统的断点。将阈值与 abortOnFail: true 和较短的 delayAbortEval 配合使用，这样一旦超出 SLO，测试就会停止（并报告）。
• 跟踪与 SLO 相关的自定义指标以用于报告：各端点的延迟（Trend）、错误 Rate 和任何领域计数器；另外，使用 handleSummary 呈现 p95/p99、吞吐量（req/s）和错误率。请参阅 examples/executors.js 和 examples/metrics.js。
• 混合协议与浏览器负载测试： 将浏览器流程封装在 try/catch 中，并将失败记录到自定义错误指标，而不是让 expect() 抛出异常——单次不稳定的浏览器迭代不应中止长时间运行的协议负载测试。

浏览器脚本——推荐实践

如果脚本导入了 k6/browser，请阅读 browser-best-practices.md 并应用所有检查。修复问题并重新验证。

---

步骤 7：呈现结果

1. 完整脚本及文件路径
2. 验证输出
3. 最佳实践说明（发现的问题，或“所有检查均已通过”）
4. 建议的运行命令

k6 run --vus 10 --duration 30s k6/scripts/api-load-test.js
k6 run k6/scripts/browser-test.js
k6 cloud run k6/scripts/cloud-test.js
k6 cloud run --local-execution k6/scripts/hybrid-test.js
./k6-with-faker run k6/scripts/faker-test.js
K6_BROWSER_HEADLESS=true k6 run k6/scripts/browser-test.js

步骤 8：执行

如果用户确认，请运行该命令。