k6-test-maintenance

k6 测试维护

维护、修复并改进现有的 k6 测试脚本。五项维护任务及其分步流程见 references/workflows.md：

1. 收紧阈值 -- 根据观测到的指标调整阈值
2. 版本迁移 -- 更新脚本以适配新版 k6
3. 适配服务变更 -- 在底层服务发生变化时修复测试
4. 重构 -- 清理并更新测试代码
5. 最佳实践审查 -- 检查脚本是否符合当前 k6 最佳实践

核心原则：了解行为的变更控制

根据每项拟议变更是否会改变测试的运行时行为进行分类：

• 语法变更（行为不变）：k6 运行时产生的指标、通过／失败结果和端点均保持一致。例如：重命名变量、将 let 改为 const、删除未使用的导入、更新注释、重新格式化。直接应用。
• 行为变更（行为不同）：任何会影响指标、通过／失败结果、时序、请求目标或负载形态的变更。例如：修改阈值、添加 sleep()、更新端点 URL、重写检查、修改场景、添加新阈值。始终以差异形式呈现并说明理由，且必须获得确认。

对“行为变更”的判定标准刻意设得较低。如有疑问，应将其视为行为变更并征求确认——看似微不足道的阈值变更也可能连带影响 CI 门禁、SLO 计算和告警。

依赖项

• k6-manage -- 安全获取和编辑由 GCk6 托管的脚本（§5：GET、备份、编辑、验证、PUT，并通过 sha256 验证）。操作任何云端托管脚本前，请先阅读该说明。
• gcx -- 访问 Grafana Cloud API 的唯一工具。
• mcp-k6 工具 -- validate_script 和 get_documentation。先检查是否可用；若不可用，则使用 k6 x docs。
• k6 x docs CLI -- mcp-k6 未配置时用于查询文档。
• k6 CLI -- 本地验证（k6 inspect、k6 run）。

验证循环（每次编辑后）

每个工作流都会生成修改后的脚本。绝不要提交或 PUT 未经验证的脚本——运行此循环，并修复问题后重新运行，直到通过：

1. 解析检查：k6 inspect <script> -- 可捕获语法错误、无效选项和损坏的导入。适用于所有类型，包括浏览器测试（无需浏览器）。如果 mcp-k6 可用，也运行 validate_script。
2. 本地冒烟测试（非浏览器且服务可访问）： k6 run --vus 1 --iterations 1 <script>。
3. 对变更进行分类（见下文），并根据矩阵进行验证 -- 操作步骤见 references/verification.md。
4. 云端托管脚本：按照 k6-manage §5 的安全编辑流程应用变更（GET → 备份 → 编辑 → 验证 → 以 application/octet-stream 格式 PUT → 通过 sha256 验证）。

变更分类

• A 类 -- 仅声明式配置。 差异仅涉及 options.thresholds 或类似的声明式字段，不会改变 k6 运行时执行的内容；default function、导入模块和检查谓词中的字节均完全相同。例如：p(95)<500 → p(95)<420。
• B 类 -- 运行时逻辑变更。 对 default function、导入、辅助模块、请求 URL、检查谓词，或 scenarios.*.vus／iterations／duration／executor（会改变负载形态和指标分布）的任何变更。例如：更改 URL、添加检查、重写身份验证、切换执行器。

如有疑问，按 B 类处理。

验证矩阵

类别	测试时长	验证方式
A	任意	sha256 + k6 inspect + 历史通过／失败预测。无需云端运行。
B	短（< 5 min）	sha256 + k6 inspect + 完整云端运行（k6-manage §11）。
B	长（≥ 5 min）	sha256 + k6 inspect + 本地 1 次迭代冒烟测试 + 对本地副本运行 k6 cloud run，并使用 --vus 1 --iterations 1。只有在云端冒烟测试通过后，才 PUT 到已保存的测试。

验证深度取决于更改类别，而非测试时长——大多数编辑都不需要完整运行，而生产测试可能会运行数小时。各类别的操作步骤（A 类预测表、B 类短／长测试，以及场景更改和放宽限制等边缘情况）见 references/verification.md。

文档查询

在提出任何涉及 k6 API、导入或模式的更改前，请对照当前文档确认，并在报告中注明来源——这样可以确保建议依据的是实际 API，而非过时的模型知识。按以下顺序查询：

1. mcp-k6（首选）：get_documentation("best_practices")、 get_documentation("javascript-api/k6-browser")、validate_script(...)。
2. k6 x docs CLI（始终可用）：

   k6 x docs using-k6 thresholds
   k6 x docs javascript-api k6-http
   k6 x docs search "websocket migration"
   

   两次调用策略：先尝试直接路径；如果返回主题列表，则选择子主题并再次调用。必须使用完整的父级路径（using-k6 thresholds， 而非 thresholds）。k6 x docs 提供已安装 k6 版本的文档——迁移时，这些文档可能落后于目标版本。
3. 网页抓取（最后手段）：https://grafana.com/docs/k6/latest/。

异步检查模式

浏览器测试中一个常见的 Bug：在异步断言中使用来自 k6 的 check()。内置的 check() 不会等待 Promise，因此 check(page, { 'title': p => p.locator('h1').textContent() === 'Foo' }) 会悄无声息地通过，因为 Promise 对象为真值。以下两种修复方式都有效：

• 使用 jslib 中支持异步的检查函数： import { check } from 'https://jslib.k6.io/k6-utils/1.5.0/index.js'——之后断言可以是 async，并可在其中使用 await。
• 在检查前解析值： const text = await page.locator('h1').textContent(); check(text, { ... })——保留来自 k6 的标准同步 check。

在任何工作流（迁移、重构、审计）中遇到此问题时，请将其标记为行为 Bug，并提出上述一种修复方式。

脚本来源

• 由 GCk6 托管——通过 k6-manage §5 获取并推送（GET → 备份 → 编辑 → 验证 → PUT → 验证 sha256）。
• 本地磁盘上的文件——直接读取和编辑。提交前进行验证。

开始前先确定来源：GCk6 测试 URL 或 ID 表示托管在云端；文件路径表示本地文件。

编写新测试，而非维护现有测试？ 此技能用于改进现有脚本。若要根据纯文本用户操作流程（通过探索实时网站发现选择器）编写新的浏览器测试，请使用 k6-browser-test 技能；若要编写其他新的 k6 脚本，请使用 k6 技能。

工作流

完整流程见 references/workflows.md：

• 阈值收紧 -- 根据观测到的指标给出有依据的数值建议，展示差异，应用更改，并进行 A 类验证。
• 版本迁移 -- 查找 已弃用或已更名的 API，区分语法层面与行为层面的变更，应用更改，并进行 B 类验证。
• 服务变更适配 -- 将每项服务变更对应到脚本变更，提出修复方案，并进行 B 类验证。
• 重构 -- 查找问题， 自动应用语法层面的变更，提出行为层面的变更建议，并在确认后进行 B 类验证。
• 最佳实践审计 -- 根据文档审查阈值、负载设计、资源管理、代码质量和浏览器特定事项。

以上五项任务都遵循行为感知型变更控制：自动应用语法层面的变更，将行为层面的变更以差异形式呈现并等待确认。

注意事项

问题	详情
云端脚本格式	GCk6 脚本可以是单个文件，也可以是 tar 归档。编辑前使用 file(1) 检测（参见 k6-manage §5）。
零观测阈值	对没有观测数据的指标设置的阈值默认会通过。添加新阈值时，请确保测试确实会生成该指标。
abortOnFail 连锁影响	如果阈值设置了 abortOnFail: true，收紧阈值意味着运行会更早中止。请提醒用户。
浏览器脚本验证	没有浏览器时，无法通过 k6 run --iterations 1 验证浏览器脚本。可使用 k6 inspect 仅进行解析验证，或通过 mcp-k6 使用 validate_script。
k6 x docs 版本对应	k6 x docs 提供与已安装 k6 版本对应的文档；迁移到较新版本时，本地文档可能无法反映目标 API。进行迁移查询时请注明这一点。
编辑后脚本差异	推送托管在云端的脚本后，下一次运行会使用新版本，但历史运行仍保留其打包快照。调查过去的故障时，应比对运行中打包的脚本（只读），而不是当前脚本。

参考资料

• references/workflows.md -- 五项维护任务的分步流程
• references/verification.md -- 各类别的编辑后验证步骤