用 k6 编写可运行负载/功能测试脚本时的示例改编…

当需要编写、生成、验证或调试 k6 压测脚本（load、stress、spike、soak、smoke、breakpoint、functional、HTTP/WebSocket/gRPC/browser）时，用示例脚手架改编、落盘、运行验证并做最佳实践复查。

适用场景

解决思路

1. 按用户需求只读匹配的那一个示例文件（示例位于本 SKILL.md 同级的 examples/ 目录），用其提供结构脚手架、option 形状和 import 模式：HTTP REST/认证流程/批量请求→examples/http.js；parseHTML 与 SharedArray 解析 HTML→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；自定义指标、execution 模块、handleSummary、per-vu-iterations→examples/metrics.js；负载模式与所有 executor（ramping、arrival rate、per-VU 等）→examples/executors.js；Cloud 运行、--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。
2. 当请求同时匹配多行时（如“browser”+“functional test”），优先选断言风格符合意图的那一行：用户说“functional test”“assert”“verify”“expect”就用 functional.js（即使涉及浏览器，它演示了带自动重试浏览器匹配器的 expect()）；不强调正确性断言的浏览器负载/性能测试用 browser.js。
3. 把加载的示例作为起点改编到用户的确切需求：改端点、VU 数、时长、阈值；增加或删除场景步骤；把函数和变量重命名以匹配业务域；每个表达式必须完整可运行，不能有 { ... }、// TODO 或 stub；严格贴合请求不要过度构建——不要加用户没要求的自定义请求 tag、额外 sleep()、额外端点或 options；多场景脚本（浏览器+HTTP、Cloud）使用具名 scenarios 并用 exec 指向各自导出的函数。
4. 只有当示例未演示所需 API/选项，或你对确切的签名、选项名、返回类型没把握时才去查文档；否则完全跳过这一步。需要查时先建立一次性的文档命令 DOCS_CMD：k6 x docs 只在检测到 TTY 时渲染内容，因此用 script 分配伪 TTY 并去 ANSI 输出到 stdout——macOS 用 DOCS_CMD="script -q /dev/null k6 x docs"，Linux 用 DOCS_CMD="script -qc 'k6 x docs' /dev/null"；用 $DOCS_CMD 2>/dev/null | head -5 验证，输出应是主题列表而不是 “browse files” 指南；若仍显示 “k6 documentation is a directory of markdown files” 说明 TTY 包装无效，回退到 https://grafana.com/docs/k6/latest/ 用 agent 的网页抓取能力（内置 fetch 工具或 shell 里的 curl）取页面；若 k6 x docs 直接失败（command not found、provisioning 或 404），读 SETUP.md（含 k6 v1.7.0+ 自动安装和旧版手动 xk6 构建）；查询用 $DOCS_CMD <path>（如 javascript-api k6-http）、$DOCS_CMD <path> --depth 2、$DOCS_CMD search <term>；不要使用 unpkg、@types/k6 或任何 npm 类型定义 URL。
5. 保存脚本：先运行 date -u +%Y-%m-%dT%H:%M:%SZ 取当前 UTC 时间戳（内容依赖它，不能与写入并行），把它作为第 1 行写成 // Generated by grafana-k6 on <时间戳>；保存到 k6/scripts/<descriptive-name>.js，文件名用小写 kebab-case；若写文件能力不会自动建父目录，先 mkdir -p k6/scripts；磁盘上的脚本文件才是交付物，必须始终写盘，绝不能只在对话里展示脚本就结束；写入失败要先重试再继续。
6. 按顶向下首个匹配行选择验证命令：导入 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 且摘要中无失败 check 或 expect() 错误（断言失败而跑完不算验证通过，k6 报错会指出失败的 locator/断言及等待条件，据此修选择器或逻辑）；负载测试退出码 0 即通过，纯阈值超限（退出码 99）可接受。验证失败则读 stderr 修根因重试，最多 3 次；3 次后呈现错误并询问用户（无人值守时交付最佳尝试并明确报告未解决的错误）。
7. 做通用最佳实践复查（清单为准，只有不确定某条规则时才查 $DOCS_CMD best-practices 或 https://grafana.com/docs/k6/latest/using-k6/）：export const options 配真实的 VUs/duration，让测试开箱即有意义；每个负载测试都定义 thresholds，至少含 http_req_duration 和 http_req_failed（或协议等价物），否则性能退化时 CI 也无法失败，纯功能性单迭代 expect() 脚本可跳过；闭模型（基于 VU）负载测试要加 sleep() 代表用户思考时间，open-model executor（constant-arrival-rate、ramping-arrival-rate）已按目标速率节流通常无需 sleep()，浏览器脚本改用 page.waitForTimeout()，单迭代功能测试与一次性连通性/演示脚本可跳过，事件驱动的 WebSocket 脚本要把 sleep() 放进 close 处理器（放主函数体会在消息到达前阻塞事件循环）；断言每个响应——浏览器脚本用 k6-testing 的 expect()（自动对 locator 重试，替代 waitFor()+isVisible()+check() 链），异步浏览器函数内若要用带指标追踪的 check() 需保证谓词同步（先 await 值再 check），只有谓词本身需要 await 时才用 k6-utils 包装（https://jslib.k6.io/k6-utils/1.5.0/index.js），因为裸 async 谓词返回 Promise 恒为真会静默通过；HTTP/gRPC/WS 脚本用 check() 做指标追踪断言或 expect() 做功能测试；浏览器脚本把交互包在 try/finally 中并在 finally 里 page.close()；gRPC 脚本把该迭代的调用包在 try/finally 中并在 finally 里 client.close()；WebSocket 脚本对收到的消息做 JSON.parse 时包 try/catch（服务端可能发非 JSON 帧，一个坏帧不应杀死 VU）；顶层不要用 let/var 而用 const（模块作用域状态跨 VU 共享，可变几乎总是 bug）；不要用废弃导入——WebSocket 用 k6/websockets，k6/ws 和 k6/experimental/websockets 均已废弃。
8. 负载与断点测试专项：断点测试要压“提供的负载”而不是 VUs，用 open-model executor（ramping-arrival-rate）使请求速率独立于系统变慢程度，闭模型（ramping-vus）会随延迟上升自我节流而掩盖断点；把 thresholds 与 abortOnFail: true 及较短的 delayAbortEval 搭配，使越过 SLO 时立即停止并报告；用自定义指标跟踪 SLO 相关数据——每端点延迟（Trend）、错误 Rate、任何业务计数器——并用 handleSummary 呈现 p95/p99、吞吐（req/s）和错误率（参见 examples/executors.js 与 examples/metrics.js）；混合协议+浏览器负载测试要把浏览器流程包在 try/catch 中并把失败记到自定义错误指标，而不是让 expect() 抛出——单个不稳定的浏览器迭代不能中止长时间的协议负载运行。
9. 若脚本导入 k6/browser，读 browser-best-practices.md 并应用其中所有检查，修完问题后重新验证。
10. 呈现结果：给出带文件路径的完整脚本、验证输出、最佳实践说明（发现的问题或“全部检查通过”）、建议的运行命令，例如 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。
11. 用户确认后执行该命令。

适用边界 · 注意事项

• 端到端网站性能套件应改用 k6-perf-test-website，而不是本流程。
• 为 k6 本身编写文档应改用 k6-docs。
• 环境里没有 k6 与 xk6-docs CLI（或无法按 SETUP.md 安装/构建）时，本流程的示例读取与文档查询步骤无法执行。